Everpop Receipts API

openapi: 3.2.0
info:
  title: Everpop Receipts 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: Receipts
paths:
  /api/v1/receipts:
    get:
      operationId: listReceipts
      summary: Measured performance per published clip — real YouTube Analytics at 48h and 7d…
      description: 'Eligible YouTube Shorts published through Everpop, newest first. Pages with an opaque cursor: pass the envelope''s nextCursor back as ?cursor= until it is null. A receipt may include a separately signed pre-publish prediction; measured metrics are not separately signed.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: nextCursor from the previous page.
      responses:
        '200':
          description: 'One page of receipts: aggregate YouTube Analytics metrics at 48h and 7d (views, retention as averageViewPercentage, likes, comments, shares and subscribers gained), each with its postId.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptListEnvelope'
              examples:
                measured48h:
                  value:
                    ok: true
                    data:
                      receipts:
                      - postId: cm1post0000000000000000000
                        title: The one thing nobody checks
                        publishedUrl: https://youtube.com/shorts/aBcDeFgHiJk
                        postedAt: '2026-09-20T15:00:00.000Z'
                        outcomes:
                          h48:
                            views: 1119
                            averageViewPercentage: 95.2
                            likes: 41
                            comments: 3
                            shares: 2
                            subscribersGained: 1
                            measuredAt: '2026-09-22T15:05:00.000Z'
                          d7: null
                        receiptUrl: https://everpop.app/r/cm1post0000000000000000000?t=...
                      campaignReportUrl: https://everpop.app/r/bundle?ids=cm1post0000000000000000000&t=...
                    nextCursor: null
        '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:
      - Receipts
components:
  schemas:
    ReceiptItem:
      type: object
      properties:
        postId:
          type: string
          description: The post id POST /api/v1/campaigns/{id}/attach takes.
        title:
          type:
          - string
          - 'null'
        publishedUrl:
          type:
          - string
          - 'null'
        postedAt:
          type:
          - string
          - 'null'
          format: date-time
        outcomes:
          type: object
          properties:
            h48:
              oneOf:
              - $ref: '#/components/schemas/ReceiptWindow'
              - type: 'null'
              description: The 48-hour window, or null until it is measured.
            d7:
              oneOf:
              - $ref: '#/components/schemas/ReceiptWindow'
              - type: 'null'
              description: The 7-day window, or null until it is measured.
          required:
          - h48
          - d7
        receiptUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Token-protected public receipt page, once the post has a measured window; null before.
      required:
      - postId
      - title
      - publishedUrl
      - postedAt
      - outcomes
      - receiptUrl
    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
    ReceiptWindow:
      type: object
      description: Aggregate YouTube Analytics metrics for one measurement window.
      properties:
        views:
          type:
          - number
          - 'null'
        averageViewPercentage:
          type:
          - number
          - 'null'
          description: Average percentage of the Short viewed (retention).
        likes:
          type:
          - number
          - 'null'
        comments:
          type:
          - number
          - 'null'
        shares:
          type:
          - number
          - 'null'
        subscribersGained:
          type:
          - number
          - 'null'
        measuredAt:
          type: string
          format: date-time
      required:
      - views
      - averageViewPercentage
      - likes
      - comments
      - shares
      - subscribersGained
      - measuredAt
    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
    ReceiptListEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          type: object
          properties:
            receipts:
              type: array
              items:
                $ref: '#/components/schemas/ReceiptItem'
            campaignReportUrl:
              type:
              - string
              - 'null'
              format: uri
              description: One token-protected link bundling the measured receipts on this page; null when none on the page is measured.
          required:
          - receipts
          - campaignReportUrl
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass back as ?cursor= for the next (older) page; null on the last page.
      required:
      - ok
      - data
      - nextCursor
    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
  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.