Everpop Publish API

openapi: 3.2.0
info:
  title: Everpop Publish API
  version: 1.3.1
  description: 'Turn your own videos into published Shorts for YouTube, Instagram, Facebook and TikTok, with measured receipts on eligible YouTube Shorts. Built to be driven by AI agents: upload a file, clip it, publish it, and pull real 48h/7d performance — all by API. REST and MCP need the Pro or Scale plan; other accounts get HTTP 402 with reason subscription (no active subscription) or plan (the plan doesn''t include API access). Full agent guide: https://everpop.app/skill.md · MCP connector: https://everpop.app/api/mcp/mcp (OAuth, or Authorization: Bearer epk_...)'
  termsOfService: https://everpop.app/terms
  x-changelog:
  - version: 1.3.1
    date: '2026-10-16'
    changes: 'Changed: when no natural sentence end fits a clip, it can now end on a held final frame, flagged open_ending in qcWarnings (one whose hold could not land is flagged mid_sentence_end); both wait for review and never auto-post. A render whose clips all end that way hands its video back, so GET /api/v1/usage does not count it. A video gets one uncharged render a month, shared with repeat-only renders, whichever came first.'
  - version: 1.3.0
    date: '2026-10-08'
    changes: 'Changed: POST /api/v1/clip on a video whose strong moments were all clipped already completed FAILED with nothing new to clip; it now completes with one clip that reuses the best of them, flagged repeat_moment in qcWarnings. The first such render of a video in a month hands its video back, so GET /api/v1/usage does not count it. Automatic renders keep the old answer.'
  - version: 1.2.0
    date: '2026-10-01'
    changes: 'Changed: the upload size limit was 4 GB and is now 32 GB. POST /api/v1/videos/upload answered 413 file_too_large for a file over 4 GB; it now takes a file up to 5 GB, the most one PUT can carry. A file over 5 GB and up to 32 GB answers 413 file_too_large with reason single_put and browserUploadUrl: the user uploads it in the browser. A file over 32 GB still answers 413 file_too_large. Added: browserUploadUrl on that error body.'
  - version: 1.1.0
    date: '2026-09-24'
    changes: 'Changed: a 401 answered code unauthorized and now names its case: key_missing, key_invalid or key_expired. The Instagram posting-safety cap answered 429 rate_limited and now answers posting_cap. A 429 sent Retry-After: 60 whatever its cause; it now fits the cause (the seconds until resetsAt for quota_exhausted, 180 for queue_capacity, none for upload_cleanup_backlog, upload_retention_backlog and posting_cap, which carry retryable: false). A method a route does not support answered an empty 405; it now answers 405 method_not_allowed with an Allow header. Added: error bodies document their detail fields and a list of known codes (ErrorCode), including meta_publish_frozen. GET /api/v1/posts takes clipId. generateShort is marked deprecated while paused. Examples on the upload, finalize, clip, job, publish and receipts operations.'
  - version: 1.0.0
    date: '2026-07-03'
    changes: First published spec.
  contact:
    email: support@everpop.app
    url: https://everpop.app/contact
servers:
- url: https://everpop.app
security:
- apiKey: []
tags:
- name: Publish
paths:
  /api/v1/publish:
    get:
      operationId: listPublishDestinations
      summary: List the exact connected destinations available to this API key
      description: Read this first and show the user the destination id, platform, and display name before requesting publish confirmation.
      responses:
        '200':
          description: The exact destinations a publish may name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishDestinationsEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Publish
    post:
      operationId: publishClip
      summary: Publish a completed clip to explicitly named destinations (explicit user…
      description: Publishing is a real-world action. Before this call, show the user every exact destination, the final title/description, and visibility, then obtain an explicit go-ahead. Omitted destinations never mean all accounts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - clipId
              - destinationIds
              - metadata
              properties:
                clipId:
                  type: string
                  minLength: 1
                destinationIds:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    minLength: 1
                  description: Exact ids returned by GET /api/v1/publish
                metadata:
                  type: object
                  required:
                  - title
                  - description
                  - privacyStatus
                  properties:
                    title:
                      type: string
                      minLength: 1
                      maxLength: 100
                    description:
                      type: string
                      maxLength: 5000
                    privacyStatus:
                      type: string
                      enum:
                      - public
                      - unlisted
                      - private
            examples:
              twoDestinations:
                value:
                  clipId: cm1clip0000000000000000000
                  destinationIds:
                  - cm1dest000000000000000yt1
                  - cm1dest000000000000000ig1
                  metadata:
                    title: The one thing nobody checks
                    description: ''
                    privacyStatus: public
      responses:
        '200':
          description: 'One result per destination; ok:true only means the request was taken. Check every posts[].status and errorCode: PUBLISHED and DELIVERED went out, FAILED and CONFLICT did not, DISMISSED was discarded; the rest are still in flight — follow them with GET /api/v1/posts?clipId=. A post still in flight that carries errorMessage is held: relay the message to the user instead of polling it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishEnvelope'
              examples:
                oneInFlightOneConflict:
                  value:
                    ok: true
                    data:
                      clipId: cm1clip0000000000000000000
                      posts:
                      - destinationId: cm1dest000000000000000yt1
                        platform: YOUTUBE_SHORTS
                        status: PUBLISHING
                      - destinationId: cm1dest000000000000000ig1
                        platform: INSTAGRAM_REELS
                        status: CONFLICT
                        currentStatus: PUBLISHED
                        errorCode: PUBLISH_INTENT_CONFLICT
                        errorMessage: This destination already has a publish with different reviewed choices. Refresh to see the active post before trying again.
        '403':
          description: reason=content_review — the clip is held for content review; or write scope/suspension.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: reason=not_found — the clip does not exist for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: reason=clip_removed — the clip was removed from the library.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: reason=unknown_destination (body.destinationIds lists ids that are not connected and healthy — nothing was published), no_eligible_destination (no requested destination can take this clip, e.g. a YouTube channel other than the clip source's), clip_not_ready, or rights_unconfirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: 'code=meta_publish_frozen: Instagram and Facebook publishing is paused for maintenance, and nothing in the request was published; retry after maintenance, or publish now without the Instagram and Facebook destinations. Otherwise a provider is temporarily unavailable; retry later.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          description: 'code=rate_limited: wait Retry-After (60). code=posting_cap (retryable: false, no Retry-After): an Instagram destination is at its posting-safety cap for a rolling window of days; nothing was published — tell the user.'
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      tags:
      - Publish
components:
  schemas:
    PublishEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: object
          properties:
            clipId:
              type: string
            posts:
              type: array
              items:
                $ref: '#/components/schemas/PublishResult'
              description: 'One result per requested destination that took the clip. Idempotent per (clip, destination): a clip already published there returns its existing post.'
          required:
          - clipId
          - posts
      required:
      - ok
      - data
    ErrorCode:
      type: string
      description: 'Codes an agent branches on, each explained in https://everpop.app/skill.md (Error codes). The list grows additively: handle a code that is not listed by its HTTP status.'
      enum:
      - bad_request
      - unauthorized
      - key_missing
      - key_invalid
      - key_expired
      - payment_required
      - subscription
      - plan
      - forbidden
      - scope
      - suspended
      - disabled
      - content_review
      - not_found
      - method_not_allowed
      - conflict
      - idempotency_conflict
      - clip_removed
      - upload_not_ready
      - file_too_large
      - unprocessable
      - validation_failed
      - invalid_cursor
      - upload_required
      - generated_source
      - demo_source
      - unknown_destination
      - no_eligible_destination
      - clip_not_ready
      - rights_unconfirmed
      - rate_limited
      - quota_exhausted
      - queue_capacity
      - upload_slots
      - upload_cleanup_backlog
      - upload_retention_backlog
      - posting_cap
      - internal_error
      - upstream_error
      - unavailable
      - engine_offline
      - meta_publish_frozen
      - cleanup_pending
    PublishDestinationsEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: object
          properties:
            destinations:
              type: array
              items:
                $ref: '#/components/schemas/PublishDestination'
              description: Connected destinations whose grant is live (not waiting for a reconnect), oldest first.
          required:
          - destinations
      required:
      - ok
      - data
    ErrorEnvelope:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
          description: Human-readable; safe to show the user.
        reason:
          type: string
          description: 'Kept for compatibility where it existed (e.g. subscription, plan, scope, unknown_destination, content_review). With code=file_too_large, single_put: the file is over 5 GB, the most one PUT can carry, and within the 32 GB limit.'
        code:
          anyOf:
          - $ref: '#/components/schemas/ErrorCode'
          - type: string
          description: 'Stable machine code, on every error: the specific code (e.g. upload_required, quota_exhausted, invalid_cursor, file_too_large), else the reason, else by status (bad_request, not_found, rate_limited, internal_error, …). Branch on this.'
        retryable:
          type: boolean
          description: 'On some 429s. false (quota_exhausted, upload_cleanup_backlog, upload_retention_backlog, posting_cap): waiting a minute will not help; stop and tell the user. true (queue_capacity): retry after Retry-After.'
        issues:
          type: object
          description: 'With code=validation_failed: the field errors ({ formErrors, fieldErrors }).'
        used:
          type: integer
          description: 'With code=quota_exhausted: videos (or AI shorts) used in the current window.'
        limit:
          type: integer
          description: 'With code=quota_exhausted: the plan''s monthly allowance.'
        resetsAt:
          type: string
          format: date-time
          description: 'With code=quota_exhausted: when the allowance resets.'
        scope:
          type: string
          enum:
          - videos
          - generations
          - user
          - global
          description: 'With code=quota_exhausted: which allowance (videos or generations). With code=queue_capacity: whose queue is full (user or global).'
        destinationIds:
          type: array
          items:
            type: string
          description: 'With code=unknown_destination: the requested ids that are not connected and healthy.'
        uploadUrl:
          type: string
          format: uri
          description: 'With code=upload_required: the sign-in-gated page where the user uploads this video''s file.'
        browserUploadUrl:
          type: string
          format: uri
          description: 'With code=file_too_large and reason=single_put: the sign-in-gated page where the user uploads the file (up to 32 GB).'
      required:
      - ok
      - error
      - code
    PaywallError:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
        reason:
          type: string
          enum:
          - subscription
          - plan
        code:
          type: string
          enum:
          - subscription
          - plan
          description: The same value as reason.
      required:
      - ok
      - error
      - reason
      - code
    PublishDestination:
      type: object
      properties:
        id:
          type: string
          description: The id POST /api/v1/publish takes in destinationIds.
        platform:
          type: string
          enum:
          - TIKTOK
          - INSTAGRAM_REELS
          - YOUTUBE_SHORTS
          - FACEBOOK_REELS
          - THREADS
        displayName:
          type: string
          description: The connected account's name — show it to the user before they confirm.
      required:
      - id
      - platform
      - displayName
    PublishResult:
      type: object
      properties:
        destinationId:
          type: string
        platform:
          type: string
          enum:
          - TIKTOK
          - INSTAGRAM_REELS
          - YOUTUBE_SHORTS
          - FACEBOOK_REELS
          - THREADS
        status:
          type: string
          description: This destination's post status after the call — one of the post statuses GET /api/v1/posts reports (e.g. PUBLISHING, QUEUED, FAILED) — or CONFLICT when the destination already has a publish of this clip with different reviewed choices (see errorCode). Follow later changes with GET /api/v1/posts.
        currentStatus:
          type: string
          description: 'When the call did not proceed because this destination already has a post for the clip: that post''s status.'
        errorCode:
          type: string
          enum:
          - PUBLISH_INTENT_CONFLICT
          - META_PUBLISH_HISTORY_REVIEW_REQUIRED
        errorMessage:
          type: string
          description: Customer-facing reason, when this destination did not proceed.
      required:
      - destinationId
      - platform
      - status
  responses:
    Forbidden:
      description: 'code=scope (also reason=scope): the API key is read-only and this is a write. code=suspended: the account is suspended. Endpoint-specific refusals document their own reason.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PaymentRequired:
      description: 'REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account''s plan doesn''t include this (API and agent access need Pro or Scale).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaywallError'
    Unauthorized:
      description: 'The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: 'Too many requests. code=rate_limited: the per-minute limit; wait Retry-After (60) seconds. code=quota_exhausted (with used, limit, resetsAt, retryable: false): the monthly allowance is used up; Retry-After is the seconds until resetsAt — tell the user rather than wait. code=queue_capacity (retryable: true): the render queue is full; retry after Retry-After (180).'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  headers:
    RetryAfter:
      description: 'Seconds to wait before retrying: 60 for a per-minute rate limit (rate_limited, upload_slots), 180 for queue_capacity, the seconds until resetsAt for quota_exhausted. Absent on upload_cleanup_backlog, upload_retention_backlog and posting_cap, where waiting will not help soon.'
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: epk_...
      description: Per-user API key from everpop.app/dashboard/api (Dashboard → API). Write scope required for mutating endpoints.