CueFrame Compose Session API

openapi: 3.2.0
info:
  title: Cueframe Ai Compose Session 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 compose-session 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: compose-session
  description: 'Warm reactive session: render frames, capture stills, and verify (judge-score) a composition in a loop.'
paths:
  /v1/projects/{id}/compose-session:
    post:
      operationId: openComposeSession
      tags:
      - compose-session
      summary: Open an isolated scratch composition
      description: Mint isolated scratch state for project authoring. This returns immediately and starts no sandbox or render provider; use /preview-frame-jobs and /score-composition for durable preview and verification work. The scratch closes automatically after its idle TTL or explicitly via DELETE. Optionally seed it from a supplied composition (seedComposition); a bodyless open derives from the project's active composition.
      security:
      - bearerAuth: []
      - oauth2:
        - projects:write
      - x402: []
      x-permissions:
        projects:
        - write
      x-x402: write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeSessionOpenRequest'
      responses:
        '200':
          description: Session opened.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                required:
                - sessionId
                additionalProperties: false
        '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'
      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}/compose-session/{sessionId}/composition:
    get:
      operationId: getComposeSessionComposition
      tags:
      - compose-session
      summary: Read the session's scratch composition
      description: 'Pure read: returns the composition currently held in the session''s SCRATCH (what the author LLM has been editing over this session), NOT the project''s active composition. The Director ensemble reads this back per candidate and returns it as the authored composition — the winner is saved downstream, so a candidate never commits its scratch to active. 404 when the session is unknown/foreign or has never written a scratch.'
      security:
      - bearerAuth: []
      - oauth2:
        - projects:read
      - x402: []
      x-permissions:
        projects:
        - read
      responses:
        '200':
          description: Scratch composition.
          content:
            application/json:
              schema:
                type: object
                properties:
                  composition: {}
                required:
                - composition
                additionalProperties: false
        '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
      - schema:
          type: string
        in: path
        name: sessionId
        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}/compose-session/{sessionId}:
    delete:
      operationId: closeComposeSession
      tags:
      - compose-session
      summary: Close a compose session
      description: End a compose session and discard its uncommitted scratch composition when the work is finished or abandoned. Scratch also closes on its idle timeout; commit first if the edits should be kept.
      security:
      - bearerAuth: []
      - oauth2:
        - projects:write
      - x402: []
      x-permissions:
        projects:
        - write
      responses:
        '200':
          description: Session closed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
        '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
      - schema:
          type: string
        in: path
        name: sessionId
        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}/compose-session/{sessionId}/commit:
    post:
      operationId: commitComposeSession
      tags:
      - compose-session
      summary: Commit the session scratch onto the project's active composition
      description: Save a compose session's scratch edits as the project's active composition and return the new ETag. Call it once previews look right; the scratch is then removed from the session. Refused with 409 if the active composition changed after the session started.
      security:
      - bearerAuth: []
      - oauth2:
        - projects:write
      - x402: []
      x-permissions:
        projects:
        - write
      responses:
        '200':
          description: Promoted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  etag:
                    type: string
                required:
                - etag
                additionalProperties: false
        '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'
        '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: sessionId
        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:
    ComposeSessionOpenRequest:
      type: object
      properties:
        seedComposition: {}
        leaseJobId:
          type: string
          minLength: 1
          maxLength: 64
      additionalProperties: false
      example: {}
    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
    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.
  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