> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Publish a video to social media > Posts the video to one of your connected social accounts: YouTube, YouTube Shorts, LinkedIn, X, Instagram (post, reel or story) or Facebook (post or story). This posts under your own account, so check the destination, text and privacy before calling it. It uploads an existing completed export: start one with POST /v1/videos/{id}/exports, wait until it completes, then pass the same `export` settings here; a 409 means no completed export matches them. The account must already be connected in Tella (Settings → Connections, or Share → Publish in the editor); a 403 means it isn't. TikTok can only be published from the Tella app, because TikTok requires its consent form. Returns 202 with a `queued` publication; poll GET /v1/videos/{id}/publish for the result. One publish per destination runs at a time. Requires edit access to the video. ## OpenAPI ````yaml /openapi.json post /v1/videos/{id}/publish openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/videos/{id}/publish: post: tags: - Videos summary: Publish a video to social media description: >- Posts the video to one of your connected social accounts: YouTube, YouTube Shorts, LinkedIn, X, Instagram (post, reel or story) or Facebook (post or story). This posts under your own account, so check the destination, text and privacy before calling it. It uploads an existing completed export: start one with POST /v1/videos/{id}/exports, wait until it completes, then pass the same `export` settings here; a 409 means no completed export matches them. The account must already be connected in Tella (Settings → Connections, or Share → Publish in the editor); a 403 means it isn't. TikTok can only be published from the Tella app, because TikTok requires its consent form. Returns 202 with a `queued` publication; poll GET /v1/videos/{id}/publish for the result. One publish per destination runs at a time. Requires edit access to the video. operationId: publishVideo parameters: - description: Unique video identifier in: path name: id required: true schema: description: Unique video identifier example: vid_abc123def456 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PublishVideoRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/PublishVideoResponse' description: Publish queued headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '409': content: application/json: example: docsUrl: https://docs.tella.com/ error: conflict message: >- The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles. schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '503': content: application/json: example: docsUrl: https://docs.tella.com/ error: unavailable message: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. schema: $ref: '#/components/schemas/ErrorResponse' description: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: PublishVideoRequest: additionalProperties: false properties: description: description: YouTube description, or the post text on LinkedIn and X. type: string destination: description: >- Where to post. YouTube Shorts must be vertical or square and at most 3 minutes; LinkedIn at most 30 minutes and 500 MB, and at least 3 seconds. YouTube takes at most 15 minutes from a channel that isn't verified; X at most 20 minutes, or 125 with Premium or a checkmark. enum: - youtube - youtube_shorts - linkedin - x type: string export: additionalProperties: false description: >- Settings of the completed export to upload, as passed to POST /v1/videos/{id}/exports. Defaults to 1080p, 30 fps, no burned-in subtitles, 1x. properties: fps: enum: - '30' - '60' type: string resolution: enum: - 4k type: string speed: enum: - '1' - '2' - '0.5' - '0.75' - '1.25' - '1.5' - '1.75' type: string subtitles: type: boolean type: object privacy: description: >- YouTube: private (default), unlisted or public. LinkedIn: private (connections only, default) or public. X: public only. enum: - public - unlisted - private type: string title: description: >- Video title on YouTube. On LinkedIn and X it is the post text when description is empty. minLength: 1 type: string uploadCaptions: description: >- YouTube only: upload the transcript as a caption track (default true). Skipped when the export has burned-in subtitles. type: boolean required: - destination - title type: object PublishVideoResponse: additionalProperties: false properties: publication: $ref: '#/components/schemas/Publication' required: - publication type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - conflict - edit_conflict - not_implemented - unavailable example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object Publication: additionalProperties: false properties: captionsError: description: Set on a completed YouTube publish whose caption track was refused nullable: true type: string createdAt: type: string destination: description: One of the request destinations, or tiktok type: string error: description: Why a failed publish failed nullable: true type: string privacy: enum: - public - unlisted - private - followers - friends type: string providerVideoId: nullable: true type: string status: enum: - queued - running - completed - failed type: string title: type: string updatedAt: type: string url: description: The post on the destination, once completed nullable: true type: string required: - destination - status - title - privacy - url - providerVideoId - error - captionsError - createdAt - updatedAt type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Publish a video to social media](/docs/help/sharing/publish-to-social-media.md) - [Publish to social media with the API or MCP](/docs/help/integrations/publish-with-the-api-and-mcp.md) - [Social publishing](/docs/mcp-tools/social-publishing.md) - [Integrations](/docs/help/integrations/overview.md) - [List social publications](/docs/api-reference/videos/list-social-publications.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.