Everpop Jobs API

openapi: 3.2.0
info:
  title: Everpop Jobs 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: Jobs
paths:
  /api/v1/jobs:
    get:
      operationId: listJobs
      summary: List the user's clip jobs, newest first, 20 per page — find the render finalize…
      description: finalize starts the automatic render without returning a job id; list jobs for that video here (or read latestJob on GET /api/v1/videos rows). Pages with an opaque cursor.
      parameters:
      - name: sourceVideoId
        in: query
        required: false
        schema:
          type: string
        description: Only jobs for this library video.
      - 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 jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListEnvelope'
        '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:
      - Jobs
  /api/v1/jobs/{id}:
    get:
      operationId: getJob
      summary: Poll a generate/clip job — returns status and, when done, the produced clips
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The job. Poll every 15–30s until status is not PENDING or PROCESSING.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusEnvelope'
              examples:
                completed:
                  value:
                    ok: true
                    data:
                      jobId: cm1job00000000000000000000
                      status: COMPLETED
                      error: null
                      clipCountApplied: 2
                      clips:
                      - clipId: cm1clip0000000000000000000
                        id: cm1clip0000000000000000000
                        title: The one thing nobody checks
                        clipUrl: https://pub-example.r2.dev/clips/cm1clip0000000000000000000.mp4
                        thumbnailUrl: https://pub-example.r2.dev/clips/cm1clip0000000000000000000.jpg
                        durationSeconds: 41
                        status: READY
                        review:
                          qcWarnings: []
                          sourceStartSeconds: 612.4
                          sourceEndSeconds: 653.1
                          archetype: top_moments
                          captions: BURNED_IN
                          hook: Nobody checks this, and it costs them
                          width: 1080
                          height: 1920
                          heldForReview: false
        '404':
          description: Job not found for this account.
          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:
      - Jobs
components:
  schemas:
    JobListItem:
      type: object
      properties:
        jobId:
          type: string
        sourceVideoId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
          - FAILED
          - CANCELED
        error:
          type:
          - string
          - 'null'
          description: Customer-safe failure detail when the job did not complete.
        clipCountApplied:
          type:
          - integer
          - 'null'
          description: The clip count the job runs with after the plan's per-video cap.
        createdAt:
          type: string
          format: date-time
        poll:
          type: string
          description: Relative URL of the job, e.g. /api/v1/jobs/{id}
      required:
      - jobId
      - sourceVideoId
      - status
      - error
      - clipCountApplied
      - createdAt
      - poll
    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
    QcWarning:
      type: object
      properties:
        flag:
          type: string
          description: Stable machine key (e.g. profanity, dead_zone); _other for a flag without specific copy.
        label:
          type: string
        detail:
          type: string
      required:
      - flag
      - label
      - detail
    ClipItem:
      type: object
      properties:
        clipId:
          type: string
          description: The id POST /api/v1/publish takes (equal to id).
        id:
          type: string
        title:
          type:
          - string
          - 'null'
        clipUrl:
          type:
          - string
          - 'null'
          description: Publicly fetchable MP4 once rendered.
        thumbnailUrl:
          type:
          - string
          - 'null'
        durationSeconds:
          type:
          - integer
          - 'null'
        status:
          type: string
        review:
          $ref: '#/components/schemas/ClipReview'
      required:
      - clipId
      - id
      - title
      - clipUrl
      - thumbnailUrl
      - durationSeconds
      - status
      - review
    JobListEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobListItem'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass back as ?cursor= for the next (older) page; null on the last page.
      required:
      - ok
      - data
      - nextCursor
    ClipReview:
      type: object
      description: What to tell the user before asking them to confirm a publish. Clips with quality-check warnings can still be published by the user's explicit choice; mention the warnings.
      properties:
        qcWarnings:
          type: array
          items:
            $ref: '#/components/schemas/QcWarning'
          description: Owner-facing quality-check warnings; empty when the clip passed.
        sourceStartSeconds:
          type:
          - number
          - 'null'
          description: Where the clip starts in the source video, in seconds (null on older clips).
        sourceEndSeconds:
          type:
          - number
          - 'null'
          description: Where the clip ends in the source video, in seconds (null on older clips).
        archetype:
          type:
          - string
          - 'null'
          description: The editorial cut, e.g. top_moments, summary, punch.
        captions:
          type:
          - string
          - 'null'
          enum:
          - NONE
          - PENDING
          - BURNED_IN
          - FAILED
          - null
          description: Caption state.
        hook:
          type:
          - string
          - 'null'
          description: The words spoken in the clip's opening seconds, when recorded.
        width:
          type:
          - integer
          - 'null'
          description: Rendered width in pixels, measured from the file (null when not measured).
        height:
          type:
          - integer
          - 'null'
          description: Rendered height in pixels, measured from the file (null when not measured).
        heldForReview:
          type: boolean
          description: true when an earlier publish attempt left the clip held for content review (publishing answers 403 content_review until it is cleared).
      required:
      - qcWarnings
      - sourceStartSeconds
      - sourceEndSeconds
      - archetype
      - captions
      - hook
      - width
      - height
      - heldForReview
    JobStatusEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: object
          properties:
            jobId:
              type: string
            status:
              type: string
              enum:
              - PENDING
              - PROCESSING
              - COMPLETED
              - FAILED
              - CANCELED
              description: Stop polling on any status other than PENDING or PROCESSING.
            error:
              type:
              - string
              - 'null'
              description: Customer-safe failure detail when the job did not complete.
            clipCountApplied:
              type:
              - integer
              - 'null'
              description: The clip count the job runs with after the plan's per-video cap (1 for a Summary or Punch).
            clips:
              type: array
              items:
                $ref: '#/components/schemas/ClipItem'
          required:
          - jobId
          - status
          - error
          - clipCountApplied
          - clips
      required:
      - ok
      - data
  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.