AccountResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cueframe-ai/json-schema/cueframe-ai-account-response-schema.json",
  "title": "AccountResponse",
  "description": "Account discovery for the authenticated key: identity + plan + entitlements + cost ceilings + the browser surfaces that exist. Read this to see what your plan/credits allow before a metered call (create_render / compose / generate_media / create_brand_kit).",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cueframe-ai-account-api-openapi.yml#/components/schemas/AccountResponse",
  "type": "object",
  "properties": {
    "generationLimit": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "applies": {
              "type": "boolean"
            },
            "unit": {
              "type": "string",
              "const": "cents_of_provider_cost"
            },
            "cap": {
              "type": [
                "number",
                "null"
              ]
            },
            "spent": {
              "type": [
                "number",
                "null"
              ]
            },
            "remaining": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "applies",
            "unit",
            "cap",
            "spent",
            "remaining"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Separate lifetime generation cap before a credit-pack purchase. Wallet balance is still shared; generation must also fit this remaining provider-cost allowance. null means unknown."
    },
    "orgId": {
      "type": "string",
      "description": "The org this API key is bound to — resolved server-side from the Authorization credential, NEVER from the request body/query."
    },
    "displayName": {
      "description": "Org/customer display name from the billing record; null when not set or unknown.",
      "type": [
        "string",
        "null"
      ]
    },
    "plan": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Plan/product id (e.g. free, pro, business, studio)."
            },
            "name": {
              "description": "Plan display name.",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's current base plan/tier. null = unknown (billing not configured, or no active plan resolvable yet)."
    },
    "entitlements": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/EntitlementEntry"
      },
      "description": "Per-feature entitlements keyed by featureId. Covers the billing-gated capabilities: `exports` gates create_render AND generate_media output; `compose` gates compose; `brand_kits` gates create_brand_kit; `resource_import` gates import_resource (a boolean grant: `listUsdPerUnit` 0 — stock search and import cost no credits for a keyed caller); plus ai_tokens/storage/compose_verify/compose_capture/etc. Read `listUsdPerUnit` for what one unit costs before you spend it. Most capabilities are CREDIT-FUNDED — `included` is true and the real limit is `balance`, drawn from the shared wallet named in `fundedBy` (`credits` — generation included; a free org is additionally bounded by a generation cap). So read `balance`, not `included`, to decide whether you can afford a call; `included:false` means the plan genuinely lacks the feature. Check BEFORE a metered call to avoid a mid-workflow 402 billing_required (whose error `details.featureId` names the gating feature)."
    },
    "costCeilings": {
      "type": "object",
      "properties": {
        "generateMediaUsdPerCall": {
          "description": "Per-call USD ceiling for generate_media: a generation whose ESTIMATE exceeds this 402s (generation_budget_exceeded) before any spend. Right-size the prompt/duration under this. null = unknown.",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "generateMediaUsdPerCall"
      ],
      "additionalProperties": false,
      "description": "Discoverable per-call cost ceilings so an agent can price/right-size a request before a guaranteed 402."
    },
    "billingConfigured": {
      "type": "boolean",
      "description": "false = billing is not configured in this environment, so plan/entitlement values are best-effort and may be null (unknown), not authoritative."
    },
    "surfaces": {
      "type": "object",
      "properties": {
        "console": {
          "type": "string",
          "description": "Origin of the authenticated web console."
        },
        "usage": {
          "type": "string",
          "description": "Browser URL for the usage ledger."
        },
        "billing": {
          "type": "string",
          "description": "Browser URL for plan and credits."
        },
        "apiKeys": {
          "type": "string",
          "description": "Browser URL for minting and revoking API keys."
        },
        "project": {
          "type": "null",
          "description": "No per-project browser view exists yet, so there is no URL to hand a user for a project or its composition. Stated as an explicit null so a client does not construct a route that 404s. Show a rendered frame (preview_frame) or a completed render instead."
        }
      },
      "required": [
        "console",
        "usage",
        "billing",
        "apiKeys",
        "project"
      ],
      "additionalProperties": false,
      "description": "The browser URLs that actually exist, so an agent asked to \"show me\" can hand the user a real link instead of guessing one from an id. A null means the surface is not built, not that it is hidden from this key."
    }
  },
  "required": [
    "generationLimit",
    "orgId",
    "displayName",
    "plan",
    "entitlements",
    "costCeilings",
    "billingConfigured",
    "surfaces"
  ],
  "additionalProperties": false,
  "$defs": {
    "EntitlementEntry": {
      "type": "object",
      "properties": {
        "featureId": {
          "type": "string",
          "description": "Stable billing feature id."
        },
        "name": {
          "type": "string",
          "description": "Human-readable feature name."
        },
        "type": {
          "type": "string",
          "enum": [
            "metered",
            "boolean",
            "credit_system"
          ],
          "description": "metered = a depleting/gauge quota (has balances); boolean = an on/off plan grant; credit_system = a spendable wallet the metered lines draw from."
        },
        "unit": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "cents",
                "count",
                "minutes",
                "gb"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "What `balance`/`includedUsage`/`usage` are COUNTED IN — do not assume. `exports` is output-MINUTES (not a number of renders), `compose`/`ai_tokens`/`compose_verify`/`generate` are CENTS of spend (not a number of calls), `compose_capture` is a count of stills, `storage` is GB, a credit system is cents (1 credit = $0.01). null = boolean feature, nothing to count."
        },
        "included": {
          "description": "Does the CURRENT plan grant this feature? For a credit-funded feature (see `fundedBy`) this is true whenever the plan grants the funding wallet — spend is then bounded by `balance`, not by inclusion. false = not on this plan (a create gated on it 402s billing_required); null = unknown (billing not configured / no live data).",
          "type": [
            "boolean",
            "null"
          ]
        },
        "unlimited": {
          "description": "Metered only: the plan grants an effectively-unlimited allowance. null = unknown / boolean feature.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "balance": {
          "description": "Metered only: remaining balance for the current period, in THIS feature's unit. For a credit-funded feature it is the funding wallet's balance restated at `creditCost` credits per unit — a SHARE of a pool, not a private allowance. null = unknown / boolean feature.",
          "type": [
            "number",
            "null"
          ]
        },
        "includedUsage": {
          "description": "Metered only: the plan's included allowance (the period limit), in this feature's unit. null = unknown / boolean feature.",
          "type": [
            "number",
            "null"
          ]
        },
        "usage": {
          "description": "Metered only: amount consumed this period, in this feature's unit. null = unknown / boolean feature.",
          "type": [
            "number",
            "null"
          ]
        },
        "nextResetAt": {
          "description": "Metered only: epoch-ms when the period balance resets. null = unknown / no scheduled reset.",
          "type": [
            "number",
            "null"
          ]
        },
        "fundedBy": {
          "description": "The credit system that actually pays for this feature (always `credits` — there is one wallet). Non-null means the feature has NO separate allowance: its `balance` restates that shared wallet, and every other feature with the same `fundedBy` competes for the same money. null = the plan grants this feature directly.",
          "type": [
            "string",
            "null"
          ]
        },
        "creditCost": {
          "description": "Credits consumed per ONE unit of this feature (exports 50 = $0.50 per 1080p output-minute; compose_capture 2 = $0.02 per still). null = not credit-funded.",
          "type": [
            "number",
            "null"
          ]
        },
        "listUsdPerUnit": {
          "description": "LIST price in USD of ONE unit of this feature (see `unit`) — the quote to read BEFORE a call. Credit-funded: `creditCost`/100 (exports 0.5 per 1080p output-minute; compose_capture 0.02 per still; compose/ai_tokens/generate 0.015 per cent of provider cost). 0 = the plan grants this feature and it draws NO credits (resource_import: stock search AND import are free for a keyed caller, bytes count toward `storage`; brand_kits). null = not quotable up front (a wallet, a gauge, or a feature the plan does not grant).",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "featureId",
        "name",
        "type",
        "unit",
        "included",
        "unlimited",
        "balance",
        "includedUsage",
        "usage",
        "nextResetAt",
        "fundedBy",
        "creditCost",
        "listUsdPerUnit"
      ],
      "additionalProperties": false,
      "description": "A single feature's entitlement: whether the plan includes it, remaining/limit when metered, and the per-unit list price to quote before a call"
    }
  }
}