CueFrame Billing API

openapi: 3.2.0
info:
  title: Cueframe Ai Billing 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 billing 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: Billing
paths:
  /v1/usage:
    get:
      operationId: getUsage
      tags:
      - Billing
      summary: List metered usage events (the A2 usage ledger)
      description: 'Every metered billing event, newest-first, with attribution: featureId, amount, the project/job that produced it, and the event''s LIST price in USD (the invoice may zero it inside a plan allowance). Filter by projectId, jobId, and/or a [from, to) epoch-ms period. Events appear moments after the job''s success terminal (the meter is scheduler-dispatched).'
      security:
      - bearerAuth: []
      - oauth2:
        - billing:read
      - x402: []
      x-permissions:
        billing:
        - 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: projectId
        in: query
        required: false
        description: Only events attributed to this project.
        schema:
          type: string
      - name: jobId
        in: query
        required: false
        description: Only events produced by this job — how to answer "did my failed render post a charge?" for one run.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: Period start, epoch milliseconds, INCLUSIVE.
        schema:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      - name: to
        in: query
        required: false
        description: Period end, epoch milliseconds, EXCLUSIVE.
        schema:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      responses:
        '200':
          description: Paginated usage events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageListResponse'
        '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'
        '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/billing/plans:
    get:
      operationId: getBillingPlans
      tags:
      - Billing
      summary: 'List the plan catalog: tiers, intervals, product ids, prices'
      description: Returns every purchasable {tier, interval} and its billing catalog product id — discovery to read BEFORE POST /v1/billing/checkout so an agent requests a real plan/interval instead of guessing. `priceUsd` is best-effort (null if unavailable); `billingConfigured:false` flags an env without billing.
      security:
      - bearerAuth: []
      - oauth2: []
      - x402: []
      x-permissions: {}
      responses:
        '200':
          description: Plan catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlansResponse'
        '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'
        '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'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/billing/checkout:
    post:
      operationId: createCheckout
      tags:
      - Billing
      summary: Start a hosted Stripe checkout for a plan/interval
      description: Body `{ plan, interval }` → returns a hosted Stripe checkout `url` to open in a browser to complete payment. Upgrades the CURRENT org (server-resolved from your key/identity, NEVER the body). Always a hosted URL — an existing saved card is NEVER charged without the human confirming on Stripe. `interval:"year"` selects the annual plan. Discover valid combos with GET /v1/billing/plans. Requires `billing:write`.
      security:
      - bearerAuth: []
      - oauth2:
        - billing:write
      - x402: []
      x-permissions:
        billing:
        - write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Hosted Stripe checkout URL to open in a browser.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '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'
        '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'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
components:
  schemas:
    UsageEventResponse:
      type: object
      properties:
        featureId:
          type: string
          description: The metered plan feature (exports, compose, compose_verify, …).
        value:
          description: Metered amount, in the feature's own unit (exports = render-minutes, storage = GB). Absent for a discrete single use, AND deliberately absent on the cost-plus lines (compose, generate, ai_tokens, compose_verify) whose internal metered unit is not a quantity — read `listUsd` for what those events cost you.
          type: number
        projectId:
          type: string
        jobId:
          description: 'The job that produced the meter: a render/compose/preview job id, a media id (transcription, generate), or a clip-suggestion run id (jobKind `suggestions` — see `mediaItemId` for the media it analyzed).'
          type: string
        jobKind:
          description: render | compose | consult_* | verify | preview | generate | suggestions | session_uptime | …
          type: string
        mediaItemId:
          description: The media item the job ran over, when it ran over one (suggestions, transcription). Resolve it with GET /v1/media/{id}.
          type: string
        listUsd:
          description: 'LIST price of this metered event, USD. Honest naming: the invoice may zero it inside a plan allowance — this is the event''s list price, not a Stripe line item.'
          type: number
        createdAt:
          type: number
          description: Epoch-ms when the meter landed.
      required:
      - featureId
      - createdAt
      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.
    CheckoutResponse:
      type: object
      properties:
        url:
          type: string
          description: Hosted Stripe checkout URL to open in a browser to complete payment. Always present on success — an existing saved card is never charged without confirming here.
        plan:
          type: string
        interval:
          type: string
        productId:
          type: string
          description: Resolved billing catalog product id.
      required:
      - url
      - plan
      - interval
      - productId
      additionalProperties: false
    BillingPlansResponse:
      type: object
      properties:
        plans:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanEntry'
          description: Every purchasable {tier, interval} and its product id.
        billingConfigured:
          type: boolean
      required:
      - plans
      - billingConfigured
      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.
    CheckoutRequest:
      type: object
      properties:
        plan:
          type: string
          enum:
          - credit_pack_10
          - credit_pack_30
          - credit_pack_100
          description: Plan tier to subscribe to.
        interval:
          default: month
          description: 'Billing interval: ''month'' (monthly) or ''year'' (annual, ~2 months free).'
          type: string
          enum:
          - month
          - year
      required:
      - plan
      - interval
      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
    BillingPlanEntry:
      type: object
      properties:
        id:
          type: string
          description: Billing catalog product id (e.g. pro, pro_yearly).
        tier:
          type: string
          description: 'Plan tier: pro | business | studio.'
        name:
          type: string
        interval:
          type: string
          description: month | year.
        priceUsd:
          type: number
          description: Price in USD for the interval.
      required:
      - id
      - tier
      - name
      - interval
      - priceUsd
      additionalProperties: false
    UsageListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageEventResponse'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      required:
      - data
      - pagination
      additionalProperties: false
  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