CueFrame Exports API

openapi: 3.2.0
info:
  title: Cueframe Ai Exports 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 exports 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: Exports
paths:
  /v1/projects/{id}/exports/fcpxml:
    post:
      operationId: createFcpxmlExport
      tags:
      - Exports
      summary: Create a Final Cut Pro export
      description: 'Export the project as a Final Cut Pro XML (FCPXML) timeline — eject the agent-authored edit into a professional NLE for human finishing, preserving clips, trims, and timeline structure. Async: poll GET /projects/:id/exports/:exportId for the download URL.'
      security:
      - bearerAuth: []
      - oauth2:
        - renders:write
      - x402: []
      x-permissions:
        renders:
        - write
      x-x402:
        amount: '10000'
        deliverable: true
        maxTimeoutSeconds: 900
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCreateRequest'
      responses:
        '202':
          description: Export queued. Poll GET /projects/:id/exports/:exportId for progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          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/projects/{id}/exports/premiere:
    post:
      operationId: createPremiereExport
      tags:
      - Exports
      summary: Create a Premiere Pro export
      description: 'Export the project to Adobe Premiere Pro — eject the agent-authored edit into a professional NLE for human finishing, preserving clips, trims, and timeline structure. Async: poll GET /projects/:id/exports/:exportId for the download URL.'
      security:
      - bearerAuth: []
      - oauth2:
        - renders:write
      - x402: []
      x-permissions:
        renders:
        - write
      x-x402:
        amount: '10000'
        deliverable: true
        maxTimeoutSeconds: 900
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCreateRequest'
      responses:
        '202':
          description: Export queued. Poll GET /projects/:id/exports/:exportId for progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          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/projects/{id}/exports/videoClip:
    post:
      operationId: createVideoClipExport
      tags:
      - Exports
      summary: Create a video clip export
      description: Export one suggestion as an H.264/AAC MP4 through the keyed NLE workflow. Poll getExport for its artifact.
      security:
      - bearerAuth: []
      - oauth2:
        - renders:write
      - x402: []
      x-permissions:
        renders:
        - write
      x-x402: render
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCreateRequest'
      responses:
        '202':
          description: Video clip export queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          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.5'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/projects/{id}/exports/{exportId}/retry:
    post:
      operationId: retryExport
      tags:
      - Exports
      summary: Retry an export's admitted specification
      description: Create a new keyed export from the original immutable snapshot in its admitted project. Use Idempotency-Key to safely replay the HTTP request. Priced like the export it repeats and charged when the retry completes.
      security:
      - bearerAuth: []
      - oauth2:
        - renders:write
      - x402: []
      x-permissions:
        renders:
        - write
      x-x402: render
      responses:
        '202':
          description: Export retry queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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'
        '409':
          description: Conflict — stale_etag / idempotency_conflict / suggestions_already_complete.
          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'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      - schema:
          type: string
        in: path
        name: exportId
        required: true
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/projects/{id}/exports/{exportId}:
    get:
      operationId: getExport
      tags:
      - Exports
      summary: Get an export job
      description: Check an export job's status and progress from 0 to 1, and get its output URL, size, and duration once complete. Poll it after starting an FCPXML, Premiere, or video clip export.
      security:
      - bearerAuth: []
      - oauth2:
        - renders:read
      - x402: []
      x-permissions:
        renders:
        - read
      responses:
        '200':
          description: Export job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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: id
        required: true
      - schema:
          type: string
        in: path
        name: exportId
        required: true
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/projects/{id}/exports/{exportId}/cancel:
    post:
      operationId: cancelExport
      tags:
      - Exports
      summary: Cancel an in-flight export
      description: Stop an export that is still running and get back the updated job. Call it when an FCPXML, Premiere, or video clip export is no longer needed; a finished export is refused, and a 503 means the cancel was not delivered, so retry.
      security:
      - bearerAuth: []
      - oauth2:
        - renders:write
      - x402: []
      x-permissions:
        renders:
        - write
      responses:
        '200':
          description: Cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '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'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      - schema:
          type: string
        in: path
        name: exportId
        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:
    ExportError:
      type: object
      properties:
        phase:
          type: string
          enum:
          - trim
          - build
          - upload
          - trigger
        message:
          type: string
        detail:
          type: string
        retryable:
          type: boolean
      required:
      - phase
      - message
      - retryable
      additionalProperties: false
    ExportStatus:
      type: string
      enum:
      - queued
      - trimming
      - building
      - uploading
      - reconciliation_required
      - complete
      - error
      - cancelled
    ExportCreateRequest:
      type: object
      properties:
        clipSuggestionId:
          type: string
          minLength: 1
      required:
      - clipSuggestionId
      additionalProperties: false
      description: POST /projects/:id/exports/{fcpxml,premiere} body.
    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.
    ExportResponse:
      type: object
      properties:
        id:
          type: string
        format:
          $ref: '#/components/schemas/ExportFormat'
        status:
          $ref: '#/components/schemas/ExportStatus'
        progress:
          type: number
          minimum: 0
          maximum: 1
          description: Fractional progress 0..1 across the trim/build/upload pipeline. Reaches 1 only on `complete`.
        outputUrl:
          type:
          - string
          - 'null'
        outputExpiresAt:
          type:
          - string
          - 'null'
        outputSizeBytes:
          type:
          - number
          - 'null'
        outputDurationSec:
          type:
          - number
          - 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ExportError'
          - type: 'null'
          description: Set when status is `error`; null otherwise. The phase field localizes the failure to trim / build / upload / trigger.
        trimCacheHit:
          type:
          - boolean
          - 'null'
        clipSuggestionId:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - format
      - status
      - progress
      - outputUrl
      - outputExpiresAt
      - outputSizeBytes
      - outputDurationSec
      - error
      - trimCacheHit
      - clipSuggestionId
      - createdAt
      - updatedAt
      additionalProperties: false
      description: NLE export job response.
    ExportFormat:
      type: string
      enum:
      - fcpxml
      - premiere
      - videoClip
    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