Everpop Posts API

openapi: 3.2.0
info:
  title: Everpop Posts 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: Posts
paths:
  /api/v1/posts:
    get:
      operationId: listPosts
      summary: List the user's posts (one per clip and destination), newest first, 20 per page…
      description: Per-destination publish status for YouTube, Instagram, Facebook and TikTok, the published URL, and the customer-facing reason when a post did not go out. Measured performance lives in GET /api/v1/receipts (eligible YouTube Shorts only).
      parameters:
      - name: clipId
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 64
        description: Only this clip's posts — pass the clipId you published to follow each destination until its status is final.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: nextCursor from the previous page.
      responses:
        '200':
          description: One page of posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostListEnvelope'
        '422':
          description: Invalid limit, or code=invalid_cursor (pass nextCursor back unchanged).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Posts
components:
  schemas:
    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
    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
    PostItem:
      type: object
      properties:
        postId:
          type: string
        clipId:
          type: string
        destinationId:
          type: string
        destinationName:
          type:
          - string
          - 'null'
          description: The connected account's display name.
        platform:
          type: string
          enum:
          - TIKTOK
          - INSTAGRAM_REELS
          - YOUTUBE_SHORTS
          - FACEBOOK_REELS
          - THREADS
        status:
          type: string
          enum:
          - PENDING
          - QUEUED
          - PUBLISHING
          - PUBLISHED
          - DELIVERED
          - FAILED
          - SCHEDULED
          - DISMISSED
          - DEFERRED
          description: DELIVERED = in the creator's TikTok inbox as a draft; going public stays their tap.
        publishedUrl:
          type:
          - string
          - 'null'
        scheduledAt:
          type:
          - string
          - 'null'
          format: date-time
        postedAt:
          type:
          - string
          - 'null'
          format: date-time
        error:
          type:
          - string
          - 'null'
          description: The customer-facing reason a post did not go out (the same text the Posts page shows), at most 300 characters.
        createdAt:
          type: string
          format: date-time
      required:
      - postId
      - clipId
      - destinationId
      - destinationName
      - platform
      - status
      - publishedUrl
      - scheduledAt
      - postedAt
      - error
      - createdAt
    PostListEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/PostItem'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass back as ?cursor= for the next (older) page; null on the last page.
      required:
      - ok
      - data
      - nextCursor
  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.