{"openapi":"3.1.0","x-citadel-agentic-execute-plane":"designed_but_disabled","x-citadel-agentic-execute-endpoint":"available_disabled_stub","x-citadel-agentic-execute-claim-model":"available_design_layer","x-citadel-agentic-atomic-spend-design":"available_dry_run_only","x-citadel-agentic-execute-revalidation-runtime":"implemented_disabled_runtime","x-citadel-agentic-atomic-spend-runtime":"implemented_disabled_runtime_mocked","x-citadel-agentic-execute-auth":"oauth_only_execute_scope_required_static_disallowed","x-citadel-agentic-execute-required-scopes":["agentic:execute:roast","agentic:execute:flake"],"x-citadel-agentic-execute-forge":"reserved_but_disabled","x-citadel-agentic-execute-founder-gate":"default_closed","x-citadel-agentic-execute-rate-abuse":"defined","x-citadel-agentic-execute-receipt-model":"defined_issue_after_final_execution_only","x-citadel-agentic-execute-receipt-verification":"defined","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. Exposes paid-action discovery rules via /.well-known/citadel-paid-action-contract.json and /.well-known/citadel-paid-action-contract.schema.json (Contract reference only. Does not grant execution rights). Agentic execute plane is designed but disabled; /api/agentic/execute exists only as a fail-closed policy stub.","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 Profile Signal Audit or Message Risk Audit","description":"Submit operator text and attached evidence to the gateway. Use Profile Signal Audit photos and Message Risk Audit screenshots or transcript. For Message Risk Audit, 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' and 'conversation screenshots'. For Message Risk Audit, query alone is not conversation evidence."},"conversation_text":{"type":"string","description":"Full pasted conversation transcript for Message Risk Audit. Prefer this field when the operator pasted the entire text conversation into chat."},"intent":{"type":"string","enum":["roast","fd","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 Profile Signal Audit photos or Message Risk Audit screenshots."},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Direct HTTPS image URLs for Profile Signal Audit photos or Message Risk Audit screenshots. Local /mnt/data sandbox paths are invalid."},"openaiFileIdRefs":{"type":"array","description":"ChatGPT upload field for attached screenshots or photos. Supports Profile Signal Audit photos and Message Risk Audit conversation screenshots. 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 Profile Signal Audit and Message Risk Audit 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 Message Risk Audit 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"],"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"}}}},"/agentic/consent":{"get":{"operationId":"reviewAgenticConsent","summary":"Human consent review for agent quotes","description":"Human-facing consent surface for agent-initiated paid-action quotes. Displays agent identity, product, cost, policy blocks, and approve/reject controls. Persists explicit consent decisions via POST /api/agentic/consent. Does not execute products, deduct credits, create payments, or return audit output.","tags":["Agentic"],"x-citadel-execution":"consent_review_only","parameters":[{"name":"quote_id","in":"query","required":true,"schema":{"type":"string"},"description":"Signed stateless agentic quote token issued by POST /api/agentic/quote"}],"responses":{"200":{"description":"Consent review page HTML"}}}},"/agentic/entitlement":{"get":{"operationId":"reviewAgenticEntitlementHandoff","summary":"Non-executing entitlement handoff after consent approval","description":"Shows consent status, product cost, and entitlement requirement after an approved agentic consent record. Does not execute products, deduct credits, or return audit output.","tags":["Agentic"],"x-citadel-execution":"entitlement_handoff_only","parameters":[{"name":"consent_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entitlement handoff page HTML"}}}},"/api/agentic/consent":{"post":{"operationId":"recordAgenticConsentDecision","summary":"Persist explicit human approve/reject for agent quotes","description":"Authenticated users may approve or reject an agentic quote. Records consent only. Does not execute products, deduct credits, create payments, or call providers. Approval routes to /agentic/entitlement for payment/credit verification.","tags":["Agentic"],"x-citadel-execution":"consent_persistence_only","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quote_token","decision"],"properties":{"quote_token":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]}}}}}},"responses":{"200":{"description":"Consent recorded"},"401":{"description":"Authentication required"},"409":{"description":"Conflicting prior decision"}}}},"/api/agentic/entitlement/status":{"get":{"operationId":"getAgenticEntitlementStatus","summary":"Verify entitlement status for an approved consent record","description":"Authenticated users can check if a consented quote currently satisfies payment or credit entitlement requirements. This endpoint is verification-only: no execution, no credit deduction, no payment creation, and no product output.","tags":["Agentic"],"x-citadel-execution":"entitlement_verification_only","parameters":[{"name":"consent_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entitlement verification status (non-executing)"},"401":{"description":"Authentication required"},"404":{"description":"Consent record not found for user"}}}},"/api/agentic/execute":{"post":{"operationId":"postAgenticExecuteDisabledStub","summary":"Disabled execute boundary (policy stub only)","description":"Fail-closed execute boundary that evaluates auth/policy/trust/abuse/founder/receipt preconditions and always returns blocked while execution remains disabled. No product execution, no credit deduction, no payment creation, no provider calls.","tags":["Agentic"],"x-citadel-execution":"disabled_stub_non_executing","responses":{"403":{"description":"Blocked policy"},"423":{"description":"Execute plane disabled (blocked policy, non-executing)"}}}},"/api/agentic/quote":{"post":{"operationId":"requestAgenticQuote","summary":"Quote-only agent orchestration (no execution)","description":"Approved external agents may request a paid-action quote and human consent URL. Does not execute products, deduct credits, call AI providers, or return audit findings. Execution still requires future user authentication, explicit consent, and verified entitlement.","tags":["Agentic"],"x-citadel-execution":"quote_only","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","agent","intent"],"properties":{"product_id":{"type":"string","enum":["roast","flake-detector","forge"]},"agent":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"callback_url":{"type":"string","format":"uri"}}},"user_context":{"type":"object","properties":{"external_user_ref":{"type":"string"}}},"intent":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["request_quote"]},"input_summary":{"type":"string"},"contains_user_media":{"type":"boolean","const":false}}},"return_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Quote issued with consent URL. No product output. Execution unavailable."},"400":{"description":"Unknown or unsupported product"},"401":{"description":"Missing or invalid approved agent credentials"},"403":{"description":"Blocked by policy (preview/output/media/execution intent)"}}}},"/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","forge","agentic_roast","agentic_flake","agentic_forge","CITADEL-ROAST-001","CITADEL-FD-001","CITADEL-FORGE-001"]},"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 for credits/stripe (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","enum":["roast","flake-detector","forge"]},"session_id":{"type":"string"},"payment_method":{"type":"string","enum":["credits","stripe"]}}}}}},"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","enum":["roast","flake-detector","forge","agentic_roast","agentic_flake","agentic_forge","CITADEL-ROAST-001","CITADEL-FD-001","CITADEL-FORGE-001"]},"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"}}}}