{"openapi":"3.1.0","info":{"title":"AgentPrizm V2 account billing API","version":"1.0.0","description":"Account-administrator billing contracts. Universal MCP keys do not confer account administration. Provider actions return 503 until billing is explicitly configured and activated. Recovery is an operator CLI, not a customer HTTP endpoint."},"servers":[{"url":"/"}],"paths":{"/api/account/billing":{"get":{"operationId":"getAccountBilling","summary":"Read the caller’s account billing state and configured checkout choices","security":[{"AccountSession":[]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSummary"}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/account/billing/invoices":{"get":{"operationId":"listAccountBillingInvoices","summary":"List current invoice snapshots for the caller’s account","description":"Session-only tenant-administrator read. Results are current objects observed from supported Stripe events, not a complete accounting ledger or guaranteed historical backfill.","security":[{"AccountSession":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size; defaults to 25 and is capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque seek cursor returned as nextCursor by the preceding page.","schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneyPage"}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/account/billing/history":{"get":{"operationId":"listAccountBillingHistory","summary":"List one kind of current money-object snapshot for the caller’s account","description":"Session-only tenant-administrator read. Currency values are minor-unit decimal strings and must not be combined across currencies. Defaults to charge snapshots.","security":[{"AccountSession":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"enum":["invoice","charge","refund","dispute"],"default":"charge"}},{"name":"limit","in":"query","required":false,"description":"Page size; defaults to 25 and is capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque seek cursor returned as nextCursor by the preceding page.","schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneyPage"}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/account/billing/overage":{"get":{"operationId":"getAccountBillingOverage","summary":"Read the caller’s usage-overage enrollment state","description":"Session-only account-administrator read. Universal MCP keys cannot administer or read account billing.","security":[{"AccountSession":[]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["overage","available"],"additionalProperties":false,"properties":{"overage":{"$ref":"#/components/schemas/OverageSummary"},"available":{"type":"boolean"}}}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/account/billing/overage/enable":{"post":{"operationId":"enableAccountBillingOverage","summary":"Accept the versioned usage-overage terms and enable future paid capacity","security":[{"AccountSession":[]}],"parameters":[{"name":"Origin","in":"header","required":true,"description":"Must match the configured public origin for cookie-authenticated mutations.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverageConsent"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["overage"],"additionalProperties":false,"properties":{"overage":{"$ref":"#/components/schemas/OverageSummary"}}}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Requires an active, non-trial verified base subscription and both verified meter attachments. Pre-consent reads are frozen until they finish or expire; otherwise returns 409 BILLING_OVERAGE_READS_PENDING."}},"/api/account/billing/overage/disable":{"post":{"operationId":"disableAccountBillingOverage","summary":"Disable future paid capacity without erasing already-authorized usage","security":[{"AccountSession":[]}],"parameters":[{"name":"Origin","in":"header","required":true,"description":"Must match the configured public origin for cookie-authenticated mutations.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["overage"],"additionalProperties":false,"properties":{"overage":{"$ref":"#/components/schemas/OverageSummary"}}}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Disables future paid capacity immediately. Usage authorized before disable, including frozen prior reads, remains reportable and owed."}},"/api/account/usage":{"get":{"operationId":"getAccountUsage","summary":"Read account usage and estimated overage reporting state","description":"Session-only account-administrator read. Estimates are safety and reconciliation inputs, not provider invoices or actual provider prices.","security":[{"AccountSession":[]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["usage"],"additionalProperties":false,"properties":{"usage":{"$ref":"#/components/schemas/UsageSummary"}}}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/checkout":{"post":{"operationId":"createAccountCheckout","summary":"Start or resume a durable subscription checkout","security":[{"AccountSession":[]}],"parameters":[{"name":"Origin","in":"header","required":true,"description":"Must match the configured public origin for cookie-authenticated mutations.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutInput"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderUrl"}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/checkout/cancel":{"post":{"operationId":"cancelAccountCheckout","summary":"Expire the caller’s pending checkout; completed checkouts cannot be canceled","security":[{"AccountSession":[]}],"parameters":[{"name":"Origin","in":"header","required":true,"description":"Must match the configured public origin for cookie-authenticated mutations.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["canceled"],"additionalProperties":false,"properties":{"canceled":{"type":"boolean"}}}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/portal":{"post":{"operationId":"createAccountPortal","summary":"Open the configured portal for the server-bound customer","security":[{"AccountSession":[]}],"parameters":[{"name":"Origin","in":"header","required":true,"description":"Must match the configured public origin for cookie-authenticated mutations.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderUrl"}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/webhook":{"post":{"operationId":"receiveStripeWebhook","summary":"Verify exact bytes and enqueue supported subscription and money events","description":"One MiB maximum. Signature verification precedes JSON use. Subscription and money events use distinct transactional projections. Unsupported signed event types are acknowledged with ignored=true, not processed.","security":[{"StripeSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The original, unmodified Stripe event JSON."}}}},"responses":{"200":{"description":"Accepted or explicitly ignored","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["received","duplicate"],"additionalProperties":false,"properties":{"received":{"const":true},"duplicate":{"type":"boolean"}}},{"type":"object","required":["received","ignored"],"additionalProperties":false,"properties":{"received":{"const":true},"ignored":{"const":true}}}]}}}},"400":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A bounded domain error; never provider payloads or credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"AccountSession":{"type":"apiKey","in":"cookie","name":"__Host-agentprizm_v2_session","description":"Secure HttpOnly account session obtained through sign-in. Billing also requires tenant-administrator authority."},"StripeSignature":{"type":"apiKey","in":"header","name":"stripe-signature","description":"Stripe timestamped HMAC signature of the exact request bytes; not a bearer credential."}},"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string"}}},"EmptyObject":{"type":"object","additionalProperties":false,"maxProperties":0},"ProviderUrl":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"Short-lived HTTPS Stripe-hosted destination. Do not persist or log this URL."}}},"CheckoutInput":{"type":"object","required":["plan"],"additionalProperties":false,"properties":{"plan":{"enum":["starter","builder","scale","pro","team"]},"interval":{"enum":["monthly","annual"],"default":"monthly"}}},"OverageSummary":{"type":"object","required":["state","enabledAt","termsVersion","recallRateMicroUsd","ingestRateMicroUsd"],"additionalProperties":false,"properties":{"state":{"enum":["disabled","authorized","enabled","reconciliation"]},"enabledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"termsVersion":{"const":"v1-overage-rates-2026-09"},"recallRateMicroUsd":{"const":1100},"ingestRateMicroUsd":{"const":500}}},"OverageConsent":{"type":"object","required":["accepted","termsVersion","recallRateMicroUsd","ingestRateMicroUsd"],"additionalProperties":false,"properties":{"accepted":{"const":true},"termsVersion":{"const":"v1-overage-rates-2026-09"},"recallRateMicroUsd":{"const":1100},"ingestRateMicroUsd":{"const":500}}},"UsageSummary":{"type":"object","required":["overageEnabled","overage","estimatedCostMicroUsd"],"additionalProperties":true,"properties":{"overageEnabled":{"type":"boolean","description":"Database/provider attachment proof for the current active overage enrollment; not inferred from consent alone."},"overage":{"type":"object","required":["estimatedMicroUsd","pendingReports","failedReports","reported"],"additionalProperties":false,"properties":{"estimatedMicroUsd":{"type":"string","pattern":"^[0-9]+$","description":"Decimal-string micro-USD estimate for queued/reported overage usage."},"pendingReports":{"type":"integer","minimum":0},"failedReports":{"type":"integer","minimum":0},"reported":{"type":"integer","minimum":0}}},"estimatedCostMicroUsd":{"type":"string","pattern":"^[0-9]+$","description":"Decimal-string estimated safety cost in micro-USD; not an invoice or actual provider charge."}}},"MoneySnapshot":{"type":"object","required":["id","kind","currency","status","amount","amountPaid","amountRemaining","createdAt","invoiceId","chargeId","paymentIntentId","subscriptionId","number","hostedInvoiceUrl","periodStart","periodEnd","updatedAt"],"additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"kind":{"enum":["invoice","charge","refund","dispute"]},"currency":{"type":"string","pattern":"^[a-z]{3}$"},"status":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]*)$","description":"Signed integer minor units."},"amountPaid":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)$"},"amountRemaining":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)$"},"createdAt":{"type":"string","format":"date-time"},"invoiceId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"chargeId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"paymentIntentId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"subscriptionId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"number":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"hostedInvoiceUrl":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"null"}]},"periodStart":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"periodEnd":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"type":"string","format":"date-time"}}},"MoneyPage":{"type":"object","required":["items","nextCursor"],"additionalProperties":false,"properties":{"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/MoneySnapshot"}},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},{"type":"null"}]}}},"Subscription":{"type":"object","required":["status","plan","periodStart","periodEnd","cancelAtPeriodEnd","updatedAt"],"additionalProperties":false,"properties":{"status":{"enum":["incomplete","incomplete_expired","trialing","active","past_due","canceled","unpaid","paused"]},"plan":{"enum":["hobby","starter","builder","scale"]},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}},"CheckoutOption":{"type":"object","required":["plan","name","interval","priceCents","currency","trialDays"],"additionalProperties":false,"properties":{"plan":{"enum":["starter","builder","scale"]},"name":{"type":"string"},"interval":{"enum":["monthly","annual"]},"priceCents":{"type":"integer","minimum":0},"currency":{"const":"USD"},"trialDays":{"const":14}}},"BillingSummary":{"type":"object","required":["billing","portalEnabled","checkoutOptions","pendingCheckout"],"additionalProperties":false,"properties":{"billing":{"type":"object","required":["effectivePlan","customerConnected","portalAvailable","subscription"],"additionalProperties":false,"properties":{"effectivePlan":{"enum":["hobby","starter","builder","scale"]},"customerConnected":{"type":"boolean"},"portalAvailable":{"type":"boolean"},"subscription":{"anyOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"null"}]}}},"portalEnabled":{"type":"boolean"},"checkoutOptions":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/CheckoutOption"}},"pendingCheckout":{"anyOf":[{"type":"null"},{"type":"object","required":["plan","interval"],"additionalProperties":false,"properties":{"plan":{"enum":["starter","builder","scale",null]},"interval":{"enum":["monthly","annual",null]}}}]}}}}}}