CueFrame Checkpoints API

openapi: 3.2.0
info:
  title: Cueframe Ai Checkpoints API
  version: v1
  contact:
    name: CueFrame
    url: https://cueframe.ai
    email: support@cueframe.ai
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged checkpoints across 2 of this provider''s published API definitions: cueframe-ai-openapi.json, cueframe-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cueframe.ai
  description: Production
tags:
- name: checkpoints
paths:
  /v1/review/{id}:
    get:
      operationId: getReviewPacket
      tags:
      - checkpoints
      summary: Read a hosted review packet (token-authenticated page data)
      description: 'The checkpoint page''s data: stage artifact (rendered from the packet''s own snapshot), presigned stills, critic verdicts, the money triple, the recorded decision once resolved, and the run''s v1→vN version stack. Authenticated by the packet''s reviewToken (?token=) — the URL from the checkpoint.ready webhook / get_checkpoint. Expired or already-answered packets still render (with their decision), never an error page.'
      security: []
      responses:
        '200':
          description: The review packet + version stack.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewPacketResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/review/{id}/decision:
    post:
      operationId: recordReviewDecision
      tags:
      - checkpoints
      summary: Record a hosted review decision (the same resume rail)
      description: Record approve / revise / abandon from the hosted page. Server-side this IS POST /v1/checkpoints/{id}/resume — one implementation; the driving agent learns of the decision via the checkpoint webhooks / wait_job. 409 when the packet is no longer awaiting (superseded, expired, or already decided).
      security: []
      responses:
        '200':
          description: Decision recorded; the run resumes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewDecisionResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Payment required — billing_required or x402 payment_*.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict — stale_etag / idempotency_conflict / suggestions_already_complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/checkpoints:
    get:
      operationId: listCheckpoints
      tags:
      - checkpoints
      summary: List checkpoints (scope to a compose job or project)
      description: The version stack of approval packets, newest first. Scope with ?composeJobId= to see one run's gate history (v1→vN with per-version status + decisions) or ?projectId= for everything reviewable in a project.
      security:
      - bearerAuth: []
      - oauth2:
        - projects:read
      - x402: []
      x-permissions:
        projects:
        - read
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: after
        in: query
        required: false
        description: Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.
        schema:
          type: string
      - name: composeJobId
        in: query
        required: false
        description: Scope to ONE compose run — its v1→vN gate history with per-version status and decisions.
        schema:
          type: string
      - name: projectId
        in: query
        required: false
        description: Scope to everything reviewable in one project.
        schema:
          type: string
      responses:
        '200':
          description: Paginated checkpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckpointListResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).'
          headers:
            Payment-Required:
              description: Base64 x402 v2 PaymentRequired envelope — the same challenge as the body, for clients that read it off the header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/checkpoints/{id}:
    get:
      operationId: getCheckpoint
      tags:
      - checkpoints
      summary: Get a checkpoint packet
      description: 'The full approval packet: the stage artifact under review, presigned storyboard/eval stills, critic verdicts (incl. lock_violation entries), the money triple {thisStep, jobSpendSoFar, estimatedJourneyTotal}, and the recorded decision once resolved. Answer an `awaiting` packet with POST /v1/checkpoints/{id}/resume.'
      security:
      - bearerAuth: []
      - oauth2:
        - projects:read
      - x402: []
      x-permissions:
        projects:
        - read
      responses:
        '200':
          description: The checkpoint packet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckpointResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).'
          headers:
            Payment-Required:
              description: Base64 x402 v2 PaymentRequired envelope — the same challenge as the body, for clients that read it off the header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/checkpoints/{id}/resume:
    post:
      operationId: resumeCheckpoint
      tags:
      - checkpoints
      summary: Answer a held checkpoint (approve / revise / abandon)
      description: 'The A1 review grammar: one `decision` for the gate, optionally carrying anchored `comments` ({beatId} or {timecodeMs} anchors; per-anchor verdict approve|revise|lock — lock freezes the element contractually) and/or `edits` (your revised stage artifact). `revise` loops IN-JOB: the director revises and re-presents this same gate with a new packet (version+1); the brief quote states the included revision cycles — beyond them, revise is refused 402 with the path forward. `abandon` ends the run. Approve-with-comments is legal: the notes record without gating.'
      security:
      - bearerAuth: []
      - oauth2:
        - projects:write
      - x402: []
      x-permissions:
        projects:
        - write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckpointResumeRequest'
      responses:
        '200':
          description: Decision recorded; the run resumes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckpointResumeResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Payment required — billing_required or x402 payment_*.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict — stale_etag / idempotency_conflict / suggestions_already_complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
components:
  schemas:
    CheckpointResumeRequest:
      type: object
      properties:
        decision:
          type: string
          enum:
          - approve
          - revise
          - abandon
          description: The ONE verdict for this gate (GitHub review grammar). approve = proceed (comments allowed — they record as taste signal without gating); revise = the director revises per comments/edits and RE-PRESENTS this same gate (in-job, no re-meter); abandon = end the run.
        comments:
          maxItems: 24
          type: array
          items:
            $ref: '#/components/schemas/CheckpointComment'
        edits:
          description: Your edited stage artifact (the power path). With edits the re-presented packet carries exactly what you supplied; with comments alone the director re-authors scoped by them.
        globalNote:
          type: string
          maxLength: 4000
      required:
      - decision
      additionalProperties: false
      description: POST /checkpoints/:id/resume body — the A1 review grammar.
      example:
        decision: approve
    CheckpointListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CheckpointResponse'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      required:
      - data
      - pagination
      additionalProperties: false
    CheckpointResumeResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
      - ok
      additionalProperties: false
      description: POST /checkpoints/:id/resume response.
    CheckpointComment:
      type: object
      properties:
        anchor:
          anyOf:
          - type: object
            properties:
              beatId:
                type: string
                minLength: 1
            required:
            - beatId
            additionalProperties: false
          - type: object
            properties:
              timecodeMs:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
            - timecodeMs
            additionalProperties: false
          description: 'What the comment is about: a plan beat (content gate) or a timecode on the artifact (layout/motion gates).'
        verdict:
          type: string
          enum:
          - approve
          - revise
          - lock
          description: Per-anchor verdict under the single gate decision. `lock` = contractually frozen — the director touching a locked element is a defect, surfaced as a lock_violation verdict on the next packet (the no-discard machinery).
        note:
          type: string
          maxLength: 2000
      required:
      - anchor
      - verdict
      additionalProperties: false
    CheckpointResponse:
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        composeJobId:
          type: string
        briefId:
          type: string
        kind:
          type: string
          enum:
          - gate
          - score
        stage:
          $ref: '#/components/schemas/CheckpointStage'
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        status:
          type: string
          enum:
          - awaiting
          - approved
          - revised
          - abandoned
          - expired
          - superseded
        artifact:
          description: 'The stage artifact under review: the locked ComposePlan at content; the composition wire shape at layout/motion; the judged composition snapshot on kind:''score''.'
        stillUrls:
          description: Presigned storyboard/eval stills — the packet's visual evidence (may be GC'd by the retention sweep after the job goes terminal; the decision record is immortal).
          type: array
          items:
            type: string
        criticVerdicts:
          description: Per-criterion scores + critique from the design loop / judge, incl. lock_violation entries.
        quote:
          $ref: '#/components/schemas/CheckpointQuote'
        revisionCycle:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Revise cycles this gate has consumed. The brief quote states the included count (revisionCyclesIncluded); beyond it, resume(revise) is refused with a typed error.
        decision:
          description: The recorded decision {decision, comments?, globalNote?, decidedAt} once resolved.
        reviewMode:
          description: How this packet is decided (from the Brief's gates). 'hosted' = the review PAGE captures the decision; absent/'agent' = the decision flows back through the driving agent.
          type: string
          enum:
          - agent
          - hosted
        reviewUrl:
          description: Hosted review-page URL (present when reviewMode is 'hosted') — a human decides from this link, no account or agent session; the recorded decision rides the SAME resume rail, and the agent learns of it via checkpoint webhooks / wait_job.
          type: string
        createdAt:
          type: number
        updatedAt:
          type: number
      required:
      - id
      - projectId
      - kind
      - version
      - status
      - artifact
      - revisionCycle
      - createdAt
      - updatedAt
      additionalProperties: false
    PaginationMeta:
      type: object
      properties:
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
        prevCursor:
          type:
          - string
          - 'null'
      required:
      - hasMore
      - nextCursor
      - prevCursor
      additionalProperties: false
      description: Cursor pagination metadata.
    CheckpointQuote:
      type: object
      properties:
        thisStepUsd:
          type: number
          description: What approving costs NEXT (the render at the final gate; $0 earlier).
        jobSpendSoFarUsd:
          type: number
          description: What has SETTLED so far — $0 while the run is live (compose is charge-on-delivery on both rails), so abandoning at a gate charges nothing.
        estimatedJourneyTotalUsd:
          type: number
          description: The same journey number the Brief quoted.
      required:
      - thisStepUsd
      - jobSpendSoFarUsd
      - estimatedJourneyTotalUsd
      additionalProperties: false
    CheckpointStage:
      type: string
      enum:
      - content
      - layout
      - motion
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine-readable error code per §Error Model.
            message:
              type: string
              description: Human-readable message.
            contract:
              type: string
              description: Contract version that produced this verdict. If it differs between two calls, the rules changed underneath you, not your request.
            contractVersion:
              type: string
              description: 'Version of the published `@cueframe/api-contract` this server implements. Compare it with the `contractVersion` of the package your client was generated from: a higher value here means the server has moved ahead of your document.'
            details:
              description: Optional context (currentEtag, projectIds, retryAfter, …).
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          - contract
          - contractVersion
          description: Standard API error envelope.
      required:
      - error
      description: Error envelope used by every non-2xx response.
    ReviewPacketResponse:
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        composeJobId:
          type: string
        briefId:
          type: string
        kind:
          type: string
          enum:
          - gate
          - score
        stage:
          $ref: '#/components/schemas/CheckpointStage'
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        status:
          type: string
          enum:
          - awaiting
          - approved
          - revised
          - abandoned
          - expired
          - superseded
        artifact:
          description: 'The stage artifact under review: the locked ComposePlan at content; the composition wire shape at layout/motion; the judged composition snapshot on kind:''score''.'
        stillUrls:
          description: Presigned storyboard/eval stills — the packet's visual evidence (may be GC'd by the retention sweep after the job goes terminal; the decision record is immortal).
          type: array
          items:
            type: string
        criticVerdicts:
          description: Per-criterion scores + critique from the design loop / judge, incl. lock_violation entries.
        quote:
          $ref: '#/components/schemas/CheckpointQuote'
        revisionCycle:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Revise cycles this gate has consumed. The brief quote states the included count (revisionCyclesIncluded); beyond it, resume(revise) is refused with a typed error.
        decision:
          description: The recorded decision {decision, comments?, globalNote?, decidedAt} once resolved.
        reviewMode:
          description: How this packet is decided (from the Brief's gates). 'hosted' = the review PAGE captures the decision; absent/'agent' = the decision flows back through the driving agent.
          type: string
          enum:
          - agent
          - hosted
        createdAt:
          type: number
        updatedAt:
          type: number
        versionStack:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              version:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              stage:
                type: string
                enum:
                - content
                - layout
                - motion
              status:
                type: string
              decision:
                type: string
              createdAt:
                type: number
            required:
            - id
            - version
            - status
            - createdAt
            additionalProperties: false
          description: The run's v1→vN gate history — per-version status + decision summaries.
      required:
      - id
      - projectId
      - kind
      - version
      - status
      - artifact
      - revisionCycle
      - createdAt
      - updatedAt
      - versionStack
      additionalProperties: false
    X402PaymentRequired:
      type: object
      title: X402PaymentRequired
      description: x402 v2 PaymentRequired challenge — the body of a 402 on a priced operation.
      properties:
        x402Version:
          type: integer
          const: 2
        accepts:
          type: array
          description: Accepted payment requirements. Read `accepts[0]` for scheme (`exact` for a fixed price, `upto` for a measured one), network (CAIP-2), asset, amount and payTo.
          items:
            type: object
        error:
          type: string
          description: Human-readable reason.
      required:
      - x402Version
      - accepts
    ReviewDecisionResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        stage:
          type: string
          enum:
          - content
          - layout
          - motion
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        composeJobId:
          type: string
      required:
      - ok
      additionalProperties: false
      description: Decision recorded; the run resumes (the SAME rail as POST /checkpoints/{id}/resume).
  securitySchemes:
    oauth2:
      type: oauth2
      description: Authorization code with PKCE (S256). Request explicit resource scopes for least privilege; identity-only grants retain account-level access.
      flows:
        authorizationCode:
          authorizationUrl: https://api.cueframe.ai/api/auth/mcp/authorize
          tokenUrl: https://api.cueframe.ai/api/auth/mcp/token
          scopes:
            media:read: Read media
            media:write: Modify media
            sessions:read: Read sessions
            sessions:write: Modify sessions
            projects:read: Read projects
            projects:write: Modify projects
            renders:read: Read renders
            renders:write: Modify renders
            webhooks:read: Read webhooks
            webhooks:write: Modify webhooks
            billing:read: Read billing
            billing:write: Modify billing
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cf_live_* or cf_test_*
      description: API key auth. Prefix `cf_live_` for production orgs, `cf_test_` for sandbox.
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment header (EIP-3009 USDC on Base; base64 PaymentPayload). Returned 402 Payment-Required if absent on priced endpoints.
x-refined-from:
- cueframe-ai-openapi.json
- cueframe-ai-openapi.yml