{"openapi":"3.1.0","info":{"title":"The Citadel — Agent Commerce API","version":"10.0.0","description":"AI dating intelligence platform. Agent-native commerce via headless API, x402 on-chain USDC settlement, OAuth 2.0 + PKCE, and MCP.","contact":{"email":"support@thecitadelapp.com","url":"https://thecitadelapp.com"}},"servers":[{"url":"https://thecitadelapp.com","description":"Production"}],"paths":{"/.well-known/agent.json":{"get":{"operationId":"getAgentCard","summary":"Agent discovery card (A2A)","tags":["Discovery"],"responses":{"200":{"description":"Agent card with capabilities, pricing, protocols"}}}},"/.well-known/jwks.json":{"get":{"operationId":"getJWKS","summary":"JSON Web Key Set for receipt verification","tags":["Discovery"],"responses":{"200":{"description":"JWKS document"}}}},"/api/oauth/register":{"post":{"operationId":"registerOAuthClient","summary":"Dynamic client registration (RFC 7591)","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_name","redirect_uris"],"properties":{"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"}},"grant_types":{"type":"array","items":{"type":"string","enum":["authorization_code","client_credentials","refresh_token"]}},"scope":{"type":"string"}}}}}},"responses":{"201":{"description":"Client registered — returns client_id + client_secret"},"400":{"description":"Invalid request"}}}},"/api/oauth/authorize":{"get":{"operationId":"getAuthorizationInfo","summary":"Validate authorization request","tags":["Auth"],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}},{"name":"response_type","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Authorization request valid"}}},"post":{"operationId":"issueAuthorizationCode","summary":"Issue authorization code (PKCE)","tags":["Auth"],"responses":{"200":{"description":"Authorization code issued"}}}},"/api/oauth/token":{"post":{"operationId":"exchangeToken","summary":"Token exchange (auth_code, client_credentials, refresh_token)","tags":["Auth"],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","client_credentials","refresh_token"]},"code":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Access token + refresh token"},"400":{"description":"Invalid grant"},"401":{"description":"Invalid credentials"}}}},"/api/gpt/gateway":{"get":{"operationId":"getGptGatewayHealth","summary":"GPT gateway heartbeat and fulfillment readiness","tags":["GPT","Discovery"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Gateway health, env readiness, and fulfillment status"},"401":{"description":"Missing authorization"},"403":{"description":"Invalid gateway key"}}},"post":{"operationId":"submitGptGatewayRequest","summary":"Route a Custom GPT request to ROAST, FLAKE DETECTOR, or VICE","description":"Submit operator text and attached evidence to the gateway. Use Roast photos, Flake screenshots or transcript, and Vice profile photos plus a suspicion summary. For Flake, labels like \"conversation screenshots\" are valid only when evidence is attached.","tags":["GPT","Commerce"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Provide at least one of query, conversation_text, openaiFileIdRefs, image_urls, or images. For chat uploads, use only openaiFileIdRefs; local /mnt/data sandbox paths are invalid.","properties":{"query":{"type":"string","description":"Operator request text. Use a short routing label only when evidence files are actually attached. Examples: 'profile audit', 'conversation screenshots', 'scan this profile'. For Flake Detector, query alone is not conversation evidence. For Vice, a suspicion summary does not replace required profile-photo evidence."},"conversation_text":{"type":"string","description":"Full pasted conversation transcript for Flake Detector. Prefer this field when the operator pasted the entire text conversation into chat."},"intent":{"type":"string","enum":["roast","fd","vice","unknown"],"description":"Optional intent override."},"operator_id":{"type":"string","description":"Optional operator ID. The server prefers openai-ephemeral-user-id from headers."},"images":{"type":"array","items":{"type":"string"},"description":"Base64 or data-URI image payloads for Roast photos, Flake Detector screenshots, or Vice profile photos."},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Direct HTTPS image URLs for Roast photos, Flake Detector screenshots, or Vice profile photos. Local /mnt/data sandbox paths are invalid."},"openaiFileIdRefs":{"type":"array","description":"ChatGPT upload field for attached screenshots or photos. Supports Roast photos, Flake Detector conversation screenshots, and Vice profile photos. Never substitute local /mnt/data sandbox paths or fabricated file references.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"download_link":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}}}}}}}},"responses":{"200":{"description":"Routed immediately. Includes unknown-intent clarifications, non-async flows, and image-terminal stop responses for Roast, Vice, and Flake Detector with operator_message, response_mode='stop', and local_analysis_allowed=false."},"202":{"description":"Accepted. Returns product routing and job or checkout details, and may continue an existing Flake Detector job when Builder replays a routing-only request after evidence was already accepted."},"400":{"description":"Validation failed, usually missing query, malformed payloads, or hard validation errors outside the image-terminal stop contract."},"401":{"description":"Missing authorization."},"402":{"description":"Account linking or payment required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GptGatewayAccountLinkRequiredResponse"},"examples":{"accountLinkRequired":{"summary":"Recognized operator must bind account before credits can be used","value":{"status":"payment_required","type":"account_link_required","intent":"roast","confidence":0.92,"product":"roast","link_url":"https://thecitadelapp.com/link/bind_abc123","checkout_url":"https://thecitadelapp.com/checkout/roast","message":"Open this exact one-time bind link to use your Citadel subscription credits: https://thecitadelapp.com/link/bind_abc123. If you prefer to purchase this analysis individually, use this checkout link: https://thecitadelapp.com/checkout/roast"}}}}}},"403":{"description":"Invalid gateway key."},"409":{"description":"Idempotent replay. Treat as success and keep polling the returned job."},"429":{"description":"Daily mandate limit reached."},"503":{"description":"Fulfillment unavailable for bound operators."}}}},"/api/gpt/identity":{"get":{"operationId":"getGptOperatorIdentity","summary":"Resolve GPT operator identity and binding state","tags":["GPT","Discovery"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Resolved operator identity and binding status","content":{"application/json":{"schema":{"type":"object","required":["auth_status","operator_id","message"],"properties":{"auth_status":{"type":"string","enum":["bound","unbound","anonymous"]},"operator_id":{"type":"string"},"credits_balance":{"type":"number"},"daily_remaining":{"type":"number"},"daily_limit":{"type":"number"},"allowed_products":{"type":"array","items":{"type":"string"}},"link_url":{"type":"string","format":"uri"},"challenge_expires_at":{"type":"string","format":"date-time"},"message":{"type":"string"}}},"examples":{"bound":{"summary":"Bound operator with credits available","value":{"auth_status":"bound","operator_id":"op_****1234","credits_balance":18,"daily_remaining":15,"daily_limit":20,"allowed_products":["roast","flake","vice"],"message":"Authenticated. Balance: 18 credits."}},"unbound":{"summary":"Recognized operator must bind account","value":{"auth_status":"unbound","operator_id":"op_****1234","link_url":"https://thecitadelapp.com/link/bind_abc123","challenge_expires_at":"2026-03-12T12:00:00.000Z","message":"Operator detected but not linked to a Citadel account. Open this exact one-time link to bind your account and use credits: https://thecitadelapp.com/link/bind_abc123"}},"anonymous":{"summary":"Anonymous operator will use checkout flow","value":{"auth_status":"anonymous","operator_id":"anonymous","message":"No operator identity detected. Submissions will use checkout flow until ChatGPT provides a stable operator identity."}}}}}},"401":{"description":"Missing authorization"},"403":{"description":"Invalid gateway key"}}}},"/api/gpt/playbook":{"get":{"operationId":"getGptPlaybook","summary":"Load operational playbook","tags":["GPT","Discovery"],"security":[{"bearerAuth":[]}],"description":"Call once at the start of each conversation to load operational protocols, routing patterns, and tone guidance. Do not recite verbatim.","responses":{"200":{"description":"Playbook loaded","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"instructions":{"type":"string"},"products":{"type":"array","items":{"type":"object"}},"triage_patterns":{"type":"object"},"pushback_handling":{"type":"object"},"worldview":{"type":"array","items":{"type":"string"}},"tone":{"type":"string"}}}}}},"401":{"description":"Missing authorization"},"403":{"description":"Invalid gateway key"}}}},"/api/commerce/headless":{"get":{"operationId":"getProductCatalog","summary":"Discover products, pricing, payment methods","tags":["Commerce"],"responses":{"200":{"description":"Product catalog"}}},"post":{"operationId":"headlessPurchase","summary":"Execute purchase without browser redirect","tags":["Commerce"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","payment_method"],"properties":{"product":{"type":"string","enum":["roast","flake-detector","vice","agentic_roast","agentic_flake","agentic_vice"]},"payment_method":{"type":"string","enum":["credits","x402","mandate"]},"user_id":{"type":"string"},"tx_hash":{"type":"string"},"network":{"type":"string","enum":["base","base-sepolia"]},"mandate_jwt":{"type":"string"},"agent_id":{"type":"string"},"input":{"type":"object"}}}}}},"responses":{"202":{"description":"Job created — returns job_id, receipt, poll_url"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment required"}}}},"/api/commerce/checkout/conversational":{"post":{"operationId":"conversationalCheckout","summary":"State-machine checkout (initiate → quote → confirm → execute)","tags":["Commerce"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["step"],"properties":{"step":{"type":"string","enum":["initiate","quote","confirm","execute","receipt"]},"product":{"type":"string"},"session_id":{"type":"string"},"payment_method":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout state transition"}}}},"/api/commerce/x402/settle":{"post":{"operationId":"submitSettlement","summary":"Submit USDC payment proof for on-chain verification","tags":["Commerce","x402"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","agent_id","payment_proof"],"properties":{"product":{"type":"string"},"agent_id":{"type":"string"},"payment_proof":{"type":"object","required":["txHash","network","fromAddress","amountUsd"],"properties":{"txHash":{"type":"string"},"network":{"type":"string","enum":["base","base-sepolia"]},"fromAddress":{"type":"string"},"amountUsd":{"type":"number"},"token":{"type":"string","default":"USDC"}}}}}}}},"responses":{"200":{"description":"Settlement recorded + receipt"},"400":{"description":"Invalid proof"}}},"get":{"operationId":"getSettlementStatus","summary":"Check settlement confirmation","tags":["Commerce","x402"],"parameters":[{"name":"id","in":"query","schema":{"type":"string"}},{"name":"agent_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Settlement status"},"404":{"description":"Not found"}}}},"/api/agents/register":{"post":{"operationId":"registerAgent","summary":"Register agent (KYA)","tags":["Agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","platform_agent_id"],"properties":{"platform":{"type":"string"},"platform_agent_id":{"type":"string"},"display_name":{"type":"string"},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Agent registered"},"409":{"description":"Already registered"}}}},"/api/admin/agent-kpi":{"get":{"operationId":"getAgentKPI","summary":"KPI snapshot","tags":["Admin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"KPI metrics + alerts"}}}},"/api/admin/commerce-analytics":{"get":{"operationId":"getCommerceAnalytics","summary":"Revenue/volume analytics","tags":["Admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Commerce analytics"}}}},"/api/admin/escalations":{"get":{"operationId":"listEscalations","summary":"List pending escalations","tags":["Admin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Escalation list"}}},"post":{"operationId":"reviewEscalation","summary":"Approve/reject escalation","tags":["Admin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["escalation_id","action"],"properties":{"escalation_id":{"type":"string"},"action":{"type":"string","enum":["approve","reject"]},"reviewer_note":{"type":"string"}}}}}},"responses":{"200":{"description":"Reviewed"}}}},"/api/mcp/server":{"post":{"operationId":"mcpServer","summary":"MCP Server (Model Context Protocol)","tags":["MCP"],"description":"JSON-RPC endpoint exposing citadel_list_products, citadel_check_credits, citadel_get_job_status, citadel_platform_status, citadel_list_trust_tiers + agent skill tools.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"MCP JSON-RPC response"}}}}},"components":{"schemas":{"GptGatewayAccountLinkRequiredResponse":{"type":"object","required":["status","type","product","link_url","message"],"properties":{"status":{"type":"string","enum":["payment_required"]},"type":{"type":"string","enum":["account_link_required"]},"intent":{"type":"string"},"confidence":{"type":"number"},"product":{"type":"string"},"link_url":{"type":"string","format":"uri","description":"Exact one-time binding URL. Preserve the returned value verbatim when rendering it back to GPT operators."},"checkout_url":{"type":"string","format":"uri"},"message":{"type":"string","description":"Human-readable instruction that repeats the exact link_url for GPT rendering."}}},"GptIdentityBoundResponse":{"type":"object","required":["auth_status","operator_id","credits_balance","daily_remaining","daily_limit","allowed_products","message"],"properties":{"auth_status":{"type":"string","enum":["bound"]},"operator_id":{"type":"string"},"credits_balance":{"type":"number"},"daily_remaining":{"type":"number"},"daily_limit":{"type":"number"},"allowed_products":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}},"GptIdentityUnboundResponse":{"type":"object","required":["auth_status","operator_id","link_url","challenge_expires_at","message"],"properties":{"auth_status":{"type":"string","enum":["unbound"]},"operator_id":{"type":"string"},"link_url":{"type":"string","format":"uri","description":"Exact one-time binding URL. Preserve the returned value verbatim when rendering it back to GPT operators."},"challenge_expires_at":{"type":"string","format":"date-time"},"message":{"type":"string"}}},"GptIdentityAnonymousResponse":{"type":"object","required":["auth_status","operator_id","message"],"properties":{"auth_status":{"type":"string","enum":["anonymous"]},"operator_id":{"type":"string","enum":["anonymous"]},"message":{"type":"string"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 access token or static API key"}}}}