CueFrame Jobs API

openapi: 3.2.0
info:
  title: Cueframe Ai Jobs 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 jobs 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: Jobs
paths:
  /v1/jobs/{jobId}:
    get:
      operationId: getJob
      tags:
      - Jobs
      summary: Get an async job's status and result
      description: Read one async job — the uniform status/result resource behind every long-running operation. Poll until `status` is terminal (`succeeded` | `failed` | `cancelled`), then read `result` (kind-specific payload) or `error` (stable code + message). `job_timeout` means the executor died mid-run and the stall sweep reaped the job — re-enqueue the operation to retry.
      security:
      - bearerAuth: []
      - oauth2:
        - projects:read
      - x402: []
      x-permissions:
        projects:
        - read
      responses:
        '200':
          description: Job status/result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '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'
        '422':
          description: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
          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: jobId
        required: true
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/jobs/{jobId}/cancel:
    post:
      operationId: cancelJob
      tags:
      - Jobs
      summary: Cancel an async job
      description: Cancel a running async job so an agent can abort a mis-priced/runaway operation without waiting out its TTL. Cancellation is durable and never meters. Already-terminal jobs are rejected (422 job_not_cancellable).
      security:
      - bearerAuth: []
      - oauth2:
        - projects:write
      - x402: []
      x-permissions:
        projects:
        - write
      responses:
        '200':
          description: Cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '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'
        '422':
          description: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
          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: jobId
        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:
    PreviewFrameJobResult:
      type: object
      properties:
        geometry:
          type: object
          properties:
            scale:
              type: number
            compositionWidth:
              type: number
            compositionHeight:
              type: number
            width:
              type: number
            height:
              type: number
          required:
          - scale
          additionalProperties: false
        warnings:
          type: array
          items:
            type: object
            propertyNames:
              type: string
            additionalProperties: {}
        previewed:
          type: object
          properties:
            source:
              type: string
              enum:
              - inline
              - scratch
              - persisted
            compositionId:
              type: string
            etag:
              type: string
          required:
          - source
          additionalProperties: false
        listUsd:
          description: List price charged for this delivered capture.
          type: number
        artifacts:
          type: array
          items:
            type: object
            properties:
              compositionFrame:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              renderFrame:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              introFrames:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              fps:
                type: number
                exclusiveMinimum: 0
              actualTimeSec:
                type: number
                minimum: 0
              artifactSha256:
                type: string
                pattern: ^sha256:[0-9a-f]{64}$
                example: sha256:0000000000000000000000000000000000000000000000000000000000000000
              id:
                type: string
              beatSec:
                type: number
              bytes:
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              contentType:
                type: string
                enum:
                - image/png
                - image/jpeg
              layers:
                type: object
                properties:
                  video:
                    type:
                    - string
                    - 'null'
                  overlays:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                required:
                - video
                - overlays
                additionalProperties: false
              url:
                type: string
                format: uri
              urlExpiresAt:
                type: string
            required:
            - id
            - beatSec
            - bytes
            - contentType
            - layers
            - url
            - urlExpiresAt
            additionalProperties: false
      required:
      - geometry
      - previewed
      - artifacts
      additionalProperties: false
    ComponentPreviewMotionResult:
      type: object
      properties:
        artifactKind:
          type: string
          const: motion
        contentType:
          type: string
          const: video/webm
        cached:
          type: boolean
        listUsd:
          description: List price charged for this delivered preview.
          type: number
        url:
          type: string
          format: uri
        urlExpiresAt:
          type: string
      required:
      - artifactKind
      - contentType
      - cached
      - url
      - urlExpiresAt
      additionalProperties: false
    ExtractBrandKitResponse:
      type: object
      properties:
        colors:
          type: array
          items:
            type: string
        fonts:
          type: array
          items:
            type: string
        title:
          type: string
        description:
          type: string
      required:
      - colors
      - fonts
      additionalProperties: false
      description: POST /brand-kits/extract response — extracted brand tokens (not persisted).
    ComponentPreviewJobResult:
      anyOf:
      - $ref: '#/components/schemas/ComponentPreviewImageResult'
      - $ref: '#/components/schemas/ComponentPreviewMotionResult'
    VerifyJobResult:
      type: object
      properties:
        perCriterion: {}
        composite:
          type: number
        critique:
          type: string
        checkpointId:
          type: string
        beats: {}
        clientScores:
          type: array
          items: {}
        listUsd:
          description: List price charged for this delivered evaluation.
          type: number
      required:
      - perCriterion
      - composite
      - critique
      - checkpointId
      additionalProperties: false
    JobResponse:
      type: object
      properties:
        id:
          type: string
          description: Job id — pass to GET /v1/jobs/{id} / wait_job.
        jobKey:
          type: string
          description: Deterministic identity of the work (idempotency key, e.g. `verify-<sessionId>-<contentHash>` — the hash covers the composition AND grading inputs). Re-enqueueing the same key returns the same job while it runs.
        kind:
          type: string
          description: Job family, e.g. `verify`.
        status:
          type: string
          enum:
          - running
          - succeeded
          - failed
          - cancelled
          description: Poll until terminal (`succeeded` | `failed` | `cancelled`).
        progress:
          anyOf:
          - type: object
            properties:
              phase:
                type: string
              percent:
                type: number
              message:
                type: string
            required:
            - phase
            additionalProperties: false
          - type: 'null'
          description: Executor heartbeat while running; null when none reported.
        result:
          anyOf:
          - anyOf:
            - $ref: '#/components/schemas/PreviewFrameJobResult'
            - $ref: '#/components/schemas/ComponentPreviewJobResult'
            - $ref: '#/components/schemas/VerifyJobResult'
            - $ref: '#/components/schemas/ExtractBrandKitResponse'
          - type: 'null'
          description: Kind-specific payload when status is `succeeded`; null otherwise.
        error:
          anyOf:
          - type: object
            properties:
              code:
                type: string
              message:
                type: string
            required:
            - code
            - message
            additionalProperties: false
          - type: 'null'
          description: Stable failure code + human message when status is `failed`; null otherwise. `job_timeout` = the executor died mid-run and the stall sweep reaped the job — re-enqueue to retry.
        createdAt:
          type: string
        updatedAt:
          type: string
        completedAt:
          type:
          - string
          - 'null'
      required:
      - id
      - jobKey
      - kind
      - status
      - progress
      - result
      - error
      - createdAt
      - updatedAt
      - completedAt
      additionalProperties: false
    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.
    ComponentPreviewImageResult:
      type: object
      properties:
        artifactKind:
          type: string
          const: image
        contentType:
          type: string
          enum:
          - image/png
          - image/jpeg
        cached:
          type: boolean
        listUsd:
          description: List price charged for this delivered preview.
          type: number
        url:
          type: string
          format: uri
        urlExpiresAt:
          type: string
      required:
      - artifactKind
      - contentType
      - cached
      - url
      - urlExpiresAt
      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
  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