{"openapi":"3.1.0","info":{"title":"Bellaso Recon Agent API","version":"1.0.0","description":"Cortex Recon Agent API — pay-per-call intent data, served over REST and MCP (POST /mcp).\nEvery operation is callable as POST /v1/{operation} with the operation's arguments as the JSON\nbody; GET /v1/balance and GET /v1/pricing are the billing reads.\n\nGuest purchases: /v1/audiences offers downloadable B2B audiences without an account or API key.\nDiscover, quote, then POST /v1/audiences/orders for a Stripe MPP 402 challenge; the buyer approves through Link.\nThe payment POST carries a public owner verifier only. Private status/download reads use X-Recon-Order-Secret.\n\nOrganization API authentication: `Authorization: Bearer rk_live_...` — an org-scoped API key minted in the console.\nThe key pins the organization; no request field can choose it. Anonymous callers may pay per call\nwith x402 (PAYMENT-SIGNATURE header) on the operations that allow it; enrich_lead never accepts\nanonymous payment. Unauthenticated initialize, tools/list and ping over /mcp are discovery.\n\nIdempotency: send an `Idempotency-Key` header (required on enrich_lead). The same key with the\nsame request replays the stored result without a second charge; the same key with a different\nrequest is a 409 idempotency_conflict.\n\nErrors are always {\"error\":{\"code\",\"message\",\"retry_after\"?,\"details\"?}}. Money is\ninteger micro-USD (1 micro = 1e-6 USD = 1 atomic unit of USDC).\n\nPII policy: search_leads and account_intent return aggregate-level stubs only — never a name,\nemail, phone, LinkedIn URL or street-level person field. The political, donor, financial and\nhousehold bundles are never offered, priced, cached or returned."},"servers":[{"url":"https://recon.bellaso.ai","description":"Current deployment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"discovery","description":"This contract and the MCP endpoint"},{"name":"paid","description":"Operations charged per call"},{"name":"billing","description":"Balance, pricing and usage reads"}],"paths":{"/openapi.json":{"get":{"security":[],"tags":["discovery"],"operationId":"getOpenApiDocument","summary":"Get this public contract","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/mcp":{"post":{"security":[{"bearerAuth":[]},{"x402Payment":[]},{}],"tags":["discovery"],"operationId":"mcpEndpoint","summary":"MCP endpoint (JSON-RPC 2.0 over single-response HTTP)","description":"MCP 2025-06-18 Streamable HTTP. initialize, ping and tools/list are unauthenticated (IP rate limited); tools/call is billed per tool. Tools: search_leads, account_intent, enrich_lead, get_balance, get_pricing. Billing errors arrive as tool results with isError and a structuredContent.error envelope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"}}}},"/v1/credits/purchases":{"post":{"security":[{"reconApiKey":[]}],"tags":["billing"],"operationId":"createCreditPurchase","summary":"Machine credit purchase (Stripe MPP / Shared Payment Token)","description":"Create a durable credit-pack purchase for an API key. The unauthenticated-by-payment first attempt returns 402 with `WWW-Authenticate: Payment` — an mppx stripe/charge challenge for the exact pack amount. Retry the same POST with `Authorization: Payment` carrying a Shared Payment Token; the durable single-owner claim charges at most once. `Authorization` is reserved for the MPP credential on this route: the rk_live_ key goes in `X-Recon-Api-Key`. Requires the opt-in `billing:purchase` scope and accepted terms. `Idempotency-Key` is required; an exact replay returns the original purchase, a different request is 409. 200 means credited; 202 means the webhook is still posting the topup (poll GET /v1/credits/purchases/{purchase_id}).","parameters":[{"name":"X-Recon-Api-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^rk_live_"},"description":"Org-scoped API key (replaces Authorization, which MPP reserves)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Required. Replays return the original purchase."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pack_id"],"properties":{"pack_id":{"type":"string","enum":["usd20","usd100","usd500"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Credited. Payment-Receipt header carries the MPP receipt."},"202":{"description":"Paid at Stripe; webhook credit pending, or charge in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"MPP challenge (WWW-Authenticate) or a terminal decline problem+json."},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/credits/purchases/{purchase_id}":{"get":{"security":[{"reconApiKey":[]}],"tags":["billing"],"operationId":"getCreditPurchase","summary":"Credit purchase status","description":"Org-bound status read (`billing:read` or `billing:purchase`): ready | charging | credited | failed, plus credited_micros once credited. No PII.","parameters":[{"name":"X-Recon-Api-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^rk_live_"}},{"name":"purchase_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/audiences":{"get":{"security":[],"tags":["audiences"],"operationId":"getAudienceOffer","summary":"Guest B2B audience offer (capabilities, limits, bundles, terms)","description":"Account-free downloadable B2B contact audiences. Reports `enabled` — new quote work and initial charge claims are launch-gated; existing buyers keep reads/downloads.","responses":{"200":{"description":"Offer document"}}}},"/v1/audiences/quotes":{"post":{"security":[],"tags":["audiences"],"operationId":"createAudienceQuote","summary":"Quote a bounded B2B contact audience","description":"Validate targeting + bundles (professional required; emails/phones optional; max 50 contacts), admit global+per-IP quote work, preview the matching feed and freeze a durable quote at the current price book. The response carries NO contact ids, names, emails, phones or vendor payloads — counts and company/job samples only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["targeting","bundles","max_contacts"],"properties":{"targeting":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":3,"maxLength":500},"similarity":{"type":"string","enum":["low","medium","high"],"default":"medium"},"lookback_days":{"type":"integer","minimum":1,"maximum":14,"default":14},"filters":{"type":"object","additionalProperties":false,"properties":{"company_domains":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"company_industries":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"job_title_contains":{"type":"string","minLength":1,"maxLength":200},"seniority_levels":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"departments":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"employee_ranges":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"countries":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}},"states":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","minLength":1,"maxLength":200}}}}}},"bundles":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["professional","emails","phones"]},"contains":{"const":"professional"}},"max_contacts":{"type":"integer","minimum":1,"maximum":50}}}}}},"responses":{"200":{"description":"The frozen quote (no PII)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/audiences/quotes/{quote_id}":{"get":{"security":[],"tags":["audiences"],"operationId":"getAudienceQuote","summary":"Read back a quote (never vendor work)","parameters":[{"name":"quote_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The quote"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/audiences/orders":{"post":{"security":[],"tags":["audiences"],"operationId":"createAudienceOrder","summary":"Fund a quote (MPP challenge → one PaymentIntent)","description":"FUNDING ONLY: quote_id + owner_verifier + accepted terms. 402 returns the mppx stripe/charge challenge for the exact quote ceiling; retry with `Authorization: Payment` (SPT). The durable claim is won inside the charge seam — an unknown Stripe outcome stays 202 `charging`, never a re-payable 402. Minimal response {order_id,status_url}; detailed state is behind the owner reads.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["quote_id","owner_verifier","accept_terms_version","terms_document_digest","authority"],"properties":{"quote_id":{"type":"string","format":"uuid"},"owner_verifier":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","description":"base64url SHA-256 of UTF-8 recon-audience-owner/v1, one NUL byte, then the locally generated ros_ secret. Never send the secret on this route."},"accept_terms_version":{"type":"string","const":"2026-11-11-audiences-v1"},"terms_document_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"authority":{"type":"string","const":"buyer_delegated"}}}}}},"responses":{"200":{"description":"Existing order replayed"},"202":{"description":"Paid at Stripe; fulfillment or webhook pending"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"MPP payment challenge"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}},"get":{"security":[{"orderSecret":[]}],"tags":["audiences"],"operationId":"listAudienceOrders","summary":"The caller's orders (X-Recon-Order-Secret)","parameters":[{"name":"X-Recon-Order-Secret","in":"header","required":true,"schema":{"type":"string","pattern":"^ros_"},"description":"Owner secret; the verifier bound at order creation derives from it."}],"responses":{"200":{"description":"Order ids + coarse state"}}}},"/v1/audiences/orders/{order_id}":{"get":{"security":[{"orderSecret":[]}],"tags":["audiences"],"operationId":"getAudienceOrder","summary":"Private order status + settlement/refund state","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Recon-Order-Secret","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Private order view"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/audiences/orders/{order_id}/download":{"get":{"security":[{"orderSecret":[]}],"tags":["audiences"],"operationId":"downloadAudienceOrder","summary":"Deterministic audience.csv / audience.json (window + count bounded)","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Recon-Order-Secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","json"]}}],"responses":{"200":{"description":"text/csv or application/json artifact"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/usage":{"get":{"security":[{"bearerAuth":[]}],"tags":["billing"],"operationId":"getUsage","summary":"Recent calls (cursor-paged, newest first)","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Call rows","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"type":"object","properties":{"call_id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string"},"charged_micros":{"type":"integer"},"created_at":{"type":"string"}}}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"}}}},"/v1/search_leads":{"post":{"security":[{"bearerAuth":[]},{"x402Payment":[]}],"tags":["paid"],"operationId":"call_search_leads","summary":"Search leads","description":"Search intent leads by natural-language query and structured filters. Returns up to `limit` lead stubs (company, title, seniority, department, country — never names, emails, phones, LinkedIn URLs or street-level person fields) plus an account roll-up. Charged per call.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Optional. Replays return the stored result without a second charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":3,"maxLength":500,"description":"Natural-language intent query, e.g. \"companies researching SIEM migration\"."},"filters":{"type":"object","additionalProperties":false,"properties":{"company_domains":{"type":"array","items":{"type":"string"},"maxItems":50},"company_industries":{"type":"array","items":{"type":"string"},"maxItems":20},"job_title_contains":{"type":"string","maxLength":100},"seniority_levels":{"type":"array","items":{"type":"string"},"maxItems":10},"departments":{"type":"array","items":{"type":"string"},"maxItems":10},"employee_ranges":{"type":"array","items":{"type":"string"},"maxItems":10},"countries":{"type":"array","items":{"type":"string"},"maxItems":20},"states":{"type":"array","items":{"type":"string"},"maxItems":60}}},"lookback_days":{"type":"integer","minimum":1,"maximum":14,"default":14},"similarity":{"type":"string","enum":["low","medium","high"],"default":"medium"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25}}}}}},"responses":{"200":{"description":"The operation ran","content":{"application/json":{"schema":{"type":"object","required":["search_id","query","window","matched_total","leads","accounts","call"],"properties":{"search_id":{"type":"string","pattern":"^rs_[0-9a-f]{24}$"},"query":{"type":"string"},"window":{"type":"object","required":["start_date","end_date","lookback_days"],"properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"lookback_days":{"type":"integer"}}},"matched_total":{"type":["integer","null"]},"leads":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","pattern":"^(id|cb)_[0-9a-f]{16}$"},"job_title":{"type":["string","null"]},"seniority_level":{"type":["string","null"]},"department":{"type":["string","null"]},"job_function":{"type":["string","null"]},"company_name":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"company_industry":{"type":["string","null"]},"company_employee_range":{"type":["string","null"]},"person_country":{"type":["string","null"]},"match_confidence":{"type":["number","null"]}}}},"accounts":{"type":"array","items":{"type":"object","properties":{"company_name":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"company_industry":{"type":["string","null"]},"leads":{"type":"integer"}}}},"call":{"type":"object","required":["call_id","charged_micros"],"properties":{"call_id":{"type":"string"},"charged_micros":{"type":"integer"},"balance_micros":{"type":["integer","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/account_intent":{"post":{"security":[{"bearerAuth":[]},{"x402Payment":[]}],"tags":["paid"],"operationId":"call_account_intent","summary":"Account intent","description":"Aggregate in-market signals at ONE company domain for up to 3 topics (or a search_id from an earlier search_leads call). Returns aggregates only — in-market headcount, seniority/department/job-function mixes, intent level and the lookback window. Charged per call.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Optional. Replays return the stored result without a second charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"additionalProperties":false,"properties":{"domain":{"type":"string","description":"Company domain; scheme, www. and path are stripped."},"topics":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","minLength":3,"maxLength":500}},"search_id":{"type":"string","pattern":"^rs_[0-9a-f]{24}$"},"lookback_days":{"type":"integer","minimum":1,"maximum":14,"default":14}}}}}},"responses":{"200":{"description":"The operation ran","content":{"application/json":{"schema":{"type":"object","required":["domain","company","window","topics","call"],"properties":{"domain":{"type":"string"},"company":{"type":"object","properties":{"name":{"type":["string","null"]},"industry":{"type":["string","null"]},"employee_range":{"type":["string","null"]}}},"window":{"type":"object","required":["start_date","end_date","lookback_days"],"properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"lookback_days":{"type":"integer"}}},"topics":{"type":"array","items":{"type":"object","required":["topic","search_id","in_market_people","sampled","intent_level"],"properties":{"topic":{"type":"string"},"search_id":{"type":"string"},"in_market_people":{"type":"integer"},"sampled":{"type":"integer"},"intent_level":{"type":"string","enum":["none","low","medium","high"]},"seniority":{"type":"object"},"departments":{"type":"object"},"job_functions":{"type":"object"}}}},"call":{"type":"object","required":["call_id","charged_micros"],"properties":{"call_id":{"type":"string"},"charged_micros":{"type":"integer"},"balance_micros":{"type":["integer","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/enrich_lead":{"post":{"security":[{"bearerAuth":[]}],"tags":["paid"],"operationId":"call_enrich_lead","summary":"Enrich lead","description":"Enrich ContactBased contact ids with per-bundle data (professional, emails, phones, …). Requires the `enrich` scope AND accepted current terms; NEVER available to anonymous callers. Charged per found contact per bundle; repeat access by the same org within 30 days is free. Idempotency-Key header is required.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Required. Replays return the stored result without a second charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_ids"],"additionalProperties":false,"properties":{"contact_ids":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","pattern":"^(id|cb)_[0-9a-f]{16}$"}},"bundles":{"type":"array","items":{"type":"string","enum":["professional","emails","phones","individual_core","location","interests","purchases","auto"]},"default":["professional","emails"]}}}}}},"responses":{"200":{"description":"The operation ran","content":{"application/json":{"schema":{"type":"object","required":["results","call"],"properties":{"results":{"type":"array","items":{"type":"object","required":["contact_id","found","charged"],"properties":{"contact_id":{"type":"string","pattern":"^(id|cb)_[0-9a-f]{16}$"},"found":{"type":"boolean"},"charged":{"type":"boolean"},"data":{"type":"object"}}}},"call":{"type":"object","required":["call_id","charged_micros"],"properties":{"call_id":{"type":"string"},"charged_micros":{"type":"integer"},"balance_micros":{"type":["integer","null"]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/balance":{"get":{"security":[{"bearerAuth":[]}],"tags":["billing"],"operationId":"call_get_balance","summary":"Get balance","description":"The calling org's prepaid credit balance in integer micro-USD and USD string form.","parameters":[],"responses":{"200":{"description":"The operation ran","content":{"application/json":{"schema":{"type":"object","required":["balance_micros","balance_usd"],"properties":{"balance_micros":{"type":"integer"},"balance_usd":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/pricing":{"get":{"security":[],"tags":["billing"],"operationId":"call_get_pricing","summary":"Get pricing","description":"The published price list: per-call prices, per-found-contact bundle prices, credit packs and the x402 payment surface. Served unauthenticated.","parameters":[],"responses":{"200":{"description":"The operation ran","content":{"application/json":{"schema":{"type":"object","required":["currency","unit","operations","credit_packs","x402"],"properties":{"currency":{"type":"string"},"unit":{"type":"string"},"price_version":{"type":["string","null"]},"operations":{"type":"object"},"credit_packs":{"type":"array"},"x402":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/UpstreamUnavailable"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_ API key"},"x402Payment":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload (base64). The legacy X-PAYMENT header is accepted as read-compat."},"reconApiKey":{"type":"apiKey","in":"header","name":"X-Recon-Api-Key","description":"rk_live_ API key for the MPP purchase routes, where Authorization is reserved for the Payment credential."},"orderSecret":{"type":"apiKey","in":"header","name":"X-Recon-Order-Secret","description":"ros_ guest-order owner secret for the private audience order reads (never a URL or body field)."}},"responses":{"BadRequest":{"description":"Arguments failed validation, or a malformed payment payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, malformed, revoked or unknown credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"insufficient_credits (key principal, details.topup_url) or payment_required (x402)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"scope_missing, terms_required, bundle_not_offered, account_inactive or anonymous_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"idempotency_conflict or payment_replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit reached; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown purchase id or route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamUnavailable":{"description":"The upstream provider failed (details.refunded:true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"unavailable or search_capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotImplemented":{"description":"The handler for this operation is not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"PurchaseStatus":{"type":"object","required":["purchase_id","status","pack_id","usd","status_url"],"properties":{"purchase_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["ready","charging","credited","failed"]},"pack_id":{"type":"string","enum":["usd20","usd100","usd500"]},"usd":{"type":"number"},"credited_micros":{"type":"integer"},"payment_intent_id":{"type":"string"},"receipt":{"type":"string"},"status_url":{"type":"string"}}},"CallMeta":{"type":"object","required":["call_id","charged_micros"],"properties":{"call_id":{"type":"string"},"charged_micros":{"type":"integer"},"balance_micros":{"type":["integer","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code: invalid_request, invalid_payment, unauthorized, insufficient_credits, payment_required, scope_missing, terms_required, bundle_not_offered, account_inactive, anonymous_not_allowed, idempotency_conflict, payment_replayed, rate_limited, upstream_unavailable, unavailable, search_capacity; transport: not_found, method_not_allowed, invalid_json, payload_too_large, not_implemented, internal_error, origin_forbidden."},"message":{"type":"string"},"retry_after":{"type":"integer"},"details":{}}}}}}}}