{"openapi":"3.1.0","info":{"title":"Tella (BYOK) API","version":"0.1.0","description":"Tella (BYOK) lets an AI assistant read your own Tella data through the Tella API with a key you supply (Tella API key). Read-only: 9 tools (list_videos, search_videos, get_video, get_video_analytics, get_workspace_analytics, list_playlists, get_playlist, list_tags, list_video_chapters). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached;...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-tella.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-tella/docs"},"termsOfService":"https://connectorbay.com/byok-tella/terms"},"servers":[{"url":"https://byok-tella.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-tella/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_videos":{"post":{"operationId":"list_videos","summary":"List your workspace's videos with name, description, view count, dates and share links; filter by playlist or tag IDs. P","description":"List your workspace's videos with name, description, view count, dates and share links; filter by playlist or tag IDs. Page with cursor. Use for \"What videos do I have in Tella and how many views does each have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextCursor to fetch the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Items per page (1 to 100, default 20).","title":"Limit"},"playlist_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only videos in this playlist.","title":"Playlist Id"},"tag_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only videos with all of these tag IDs, comma-separated (ignored when playlist_id is set).","title":"Tag Ids"}},"title":"list_videosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_videos":{"post":{"operationId":"search_videos","summary":"Search videos by words in the title or in transcript sentences; returns the video and the matching excerpts. Use for \"Fi","description":"Search videos by words in the title or in transcript sentences; returns the video and the matching excerpts. Use for \"Find my Tella videos where I talk about pricing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Words to find in video titles or transcripts.","maxLength":200,"title":"Query","type":"string"},"search_in":{"anyOf":[{"enum":["all","title","transcript"],"type":"string"},{"type":"null"}],"default":null,"description":"Where to search: all, title or transcript (default all).","title":"Search In"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Items per page (1 to 100, default 20).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextCursor to fetch the next page.","title":"Cursor"}},"required":["query"],"title":"search_videosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_video":{"post":{"operationId":"get_video","summary":"Get one video's name, description, duration, view count, dates, chapters, playlist IDs and share links. Use for \"How lon","description":"Get one video's name, description, duration, view count, dates, chapters, playlist IDs and share links. Use for \"How long is my Tella video and what chapters does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"video_id":{"description":"Tella video ID from list_videos or search_videos.","maxLength":200,"title":"Video Id","type":"string"}},"required":["video_id"],"title":"get_videoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_video_analytics":{"post":{"operationId":"get_video_analytics","summary":"Get a video's views, unique sessions, watch time, average percent viewed, views per day, countries, referrers, traffic s","description":"Get a video's views, unique sessions, watch time, average percent viewed, views per day, countries, referrers, traffic sources and retention curve. Use for \"How did my Tella video perform last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"video_id":{"description":"Tella video ID from list_videos or search_videos.","maxLength":200,"title":"Video Id","type":"string"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of the range, YYYY-MM-DD in UTC (inclusive). Omit to start from the first recorded view.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the range, YYYY-MM-DD in UTC (inclusive). Omit to run through today.","title":"End Date"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone used to bucket views into days, for example 'Europe/Berlin' (default UTC).","title":"Timezone"}},"required":["video_id"],"title":"get_video_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_workspace_analytics":{"post":{"operationId":"get_workspace_analytics","summary":"Get workspace-wide view analytics: totals, views per day, top videos, countries, referrers and retention; scope can be t","description":"Get workspace-wide view analytics: totals, views per day, top videos, countries, referrers and retention; scope can be the whole workspace or only your videos. Use for \"Which of my Tella videos got the most views this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of the range, YYYY-MM-DD in UTC (inclusive). Omit to start from the first recorded view.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the range, YYYY-MM-DD in UTC (inclusive). Omit to run through today.","title":"End Date"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone used to bucket views into days, for example 'Europe/Berlin' (default UTC).","title":"Timezone"},"scope":{"anyOf":[{"enum":["workspace","mine"],"type":"string"},{"type":"null"}],"default":null,"description":"Which videos to aggregate: workspace (default) or mine.","title":"Scope"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Top videos per page (1 to 100, default 20).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextCursor to fetch the next page.","title":"Cursor"}},"title":"get_workspace_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_playlists":{"post":{"operationId":"list_playlists","summary":"List playlists with name, description, video count, visibility and share link; choose your own or the shared organizatio","description":"List playlists with name, description, video count, visibility and share link; choose your own or the shared organization playlists. Use for \"What playlists do I have in Tella\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"visibility":{"anyOf":[{"enum":["personal","org"],"type":"string"},{"type":"null"}],"default":null,"description":"personal (your playlists, default) or org (shared with the organization).","title":"Visibility"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextCursor to fetch the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Items per page (1 to 100, default 20).","title":"Limit"}},"title":"list_playlistsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_playlist":{"post":{"operationId":"get_playlist","summary":"Get one playlist's name, description, video count, visibility, share link and dates. Use for \"Tell me about my Tella pla","description":"Get one playlist's name, description, video count, visibility, share link and dates. Use for \"Tell me about my Tella playlist pl_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"playlist_id":{"description":"Tella playlist ID from list_playlists.","maxLength":200,"title":"Playlist Id","type":"string"}},"required":["playlist_id"],"title":"get_playlistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List the tags available in the workspace with name, color, description and scope (workspace or private). Use for \"Which ","description":"List the tags available in the workspace with name, color, description and scope (workspace or private). Use for \"Which tags can I put on Tella videos\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_video_chapters":{"post":{"operationId":"list_video_chapters","summary":"List a video's chapters with title, start time in seconds and description. Use for \"What chapters does my Tella video ha","description":"List a video's chapters with title, start time in seconds and description. Use for \"What chapters does my Tella video have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"video_id":{"description":"Tella video ID from list_videos or search_videos.","maxLength":200,"title":"Video Id","type":"string"}},"required":["video_id"],"title":"list_video_chaptersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}