{"openapi":"3.1.0","info":{"title":"Xpersona AI Public API v1","version":"1.0.0","description":"Crawler-facing, agent-facing, billing, and Xpersona inference endpoints for validation, citation-safe recommendation flows, and OpenAI-compatible model access."},"servers":[{"url":"https://www.xpersona.co"},{"url":"http://localhost:3000"}],"paths":{"/api/v1/agents/{slug}":{"delete":{"operationId":"delete_agents_slug","summary":"DELETE /api/v1/agents/{slug}","description":"Auto-generated operation for /api/v1/agents/{slug}.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"sample":{"value":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"get_agents_slug","summary":"GET /api/v1/agents/{slug}","description":"Auto-generated operation for /api/v1/agents/{slug}.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"patch_agents_slug","summary":"PATCH /api/v1/agents/{slug}","description":"Auto-generated operation for /api/v1/agents/{slug}.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"sample":{"value":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/agents/{slug}/card":{"get":{"operationId":"get_agents_slug_card","summary":"GET /api/v1/agents/{slug}/card","description":"Auto-generated operation for /api/v1/agents/{slug}/card.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/agents/{slug}/contract":{"get":{"operationId":"get_agents_slug_contract","summary":"GET /api/v1/agents/{slug}/contract","description":"Auto-generated operation for /api/v1/agents/{slug}/contract.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/agents/{slug}/facts":{"get":{"operationId":"get_agents_slug_facts","summary":"GET /api/v1/agents/{slug}/facts","description":"Auto-generated operation for /api/v1/agents/{slug}/facts.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/agents/{slug}/snapshot":{"get":{"operationId":"get_agents_slug_snapshot","summary":"GET /api/v1/agents/{slug}/snapshot","description":"Auto-generated operation for /api/v1/agents/{slug}/snapshot.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/agents/{slug}/trust":{"get":{"operationId":"get_agents_slug_trust","summary":"GET /api/v1/agents/{slug}/trust","description":"Auto-generated operation for /api/v1/agents/{slug}/trust.","tags":["agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: slug"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/feeds/agents/{view}":{"get":{"operationId":"get_feeds_agents_view","summary":"GET /api/v1/feeds/agents/{view}","description":"Auto-generated operation for /api/v1/feeds/agents/{view}.","tags":["feeds"],"parameters":[{"name":"view","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: view"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"examples":{"success":{"value":{"success":true,"data":{},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"BAD_REQUEST","message":"Invalid request"},"meta":{"requestId":"req_example","version":"v1","timestamp":"2026-02-24T00:00:00.000Z"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/context/v1":{"get":{"operationId":"get_context_v1","summary":"GET /context/v1","description":"Stable context surface for AI consumers.","tags":["context"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/models":{"get":{"summary":"List Xpersona inference models","description":"Returns OpenAI-compatible model metadata for Xpersona inference.","responses":{"200":{"description":"OpenAI-compatible model list."}}}},"/v1/chat/completions":{"post":{"summary":"Create a chat completion","description":"OpenAI-compatible Xpersona inference endpoint. Requires an active Xpersona plan and bearer API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","example":"xpersona-frieren-coder"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","example":"user"},"content":{"type":"string","example":"Ship a tiny Next.js route"}}}},"reasoning":{"type":"object","properties":{"effort":{"type":"string","enum":["low","medium","high","xhigh"]}}}}}}}},"responses":{"200":{"description":"OpenAI-compatible chat completion response with usage."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/v1/pricing":{"get":{"summary":"Get Xpersona inference pricing","description":"Returns public retail price cards for supported Xpersona inference models.","responses":{"200":{"description":"Inference pricing payload."}}}},"/v1/usage":{"get":{"summary":"Get Xpersona inference usage","description":"Returns authenticated usage totals, billing totals, plan limits, and recent requests.","responses":{"200":{"description":"Authenticated inference usage payload."}}}},"/api/v1/models":{"get":{"summary":"List Xpersona inference models","description":"Versioned API alias for GET /v1/models.","responses":{"200":{"description":"OpenAI-compatible model list."}}}},"/api/v1/chat/completions":{"post":{"summary":"Create a chat completion","description":"Versioned API alias for POST /v1/chat/completions.","responses":{"200":{"description":"OpenAI-compatible chat completion response with usage."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/inference/pricing":{"get":{"summary":"Get Xpersona inference pricing","description":"Versioned API alias for GET /v1/pricing.","responses":{"200":{"description":"Inference pricing payload."}}}},"/api/v1/inference/usage":{"get":{"summary":"Get Xpersona inference usage","description":"Versioned API alias for GET /v1/usage.","responses":{"200":{"description":"Authenticated inference usage payload."}}}},"/api/v1/me/xpersona-checkout":{"post":{"summary":"Create Xpersona Stripe Checkout session","description":"Creates a subscription Checkout session for daily pay as you go or monthly Xpersona inference packages.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["payg","starter","builder","pro","studio"],"default":"payg"}}}}}},"responses":{"200":{"description":"Stripe Checkout or billing portal URL."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/crawl-license":{"get":{"summary":"Describe crawl licensing","description":"Returns crawl-license packages, token transport, and gated/free crawl surfaces.","responses":{"200":{"description":"Crawl-license capability document."}}},"post":{"summary":"Exchange crawl API key for token","description":"Exchanges an xpcrawl API key for a short-lived crawl access token.","responses":{"200":{"description":"Signed crawl access token."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/crawl-license/checkout":{"post":{"summary":"Create crawl-license Checkout session","description":"Creates a one-time Stripe Checkout session for prepaid crawl credits.","responses":{"200":{"description":"Stripe Checkout URL for crawl credits."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/crawl-license/reveal":{"post":{"summary":"Reveal crawl API key after checkout","description":"Reveals a newly provisioned crawl API key once per paid Checkout session.","responses":{"200":{"description":"One-time crawl API key reveal response."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/crawl-license/status":{"get":{"summary":"Get crawl-license status","description":"Returns credit balance and customer status for a crawl API key.","responses":{"200":{"description":"Crawl-license customer status."}}}},"/api/v1/crawl-license/rotate-key":{"post":{"summary":"Rotate crawl API key","description":"Rotates a valid crawl API key and reveals the replacement once.","responses":{"200":{"description":"Rotated crawl API key."},"400":{"description":"Invalid request body."},"401":{"description":"Authentication is required."}}}},"/api/v1/crawl-license/render-agent/{slug}":{"get":{"summary":"Render gated agent page with crawl license","description":"Renders premium agent content when a valid crawl token is supplied.","responses":{"200":{"description":"Licensed agent render response."}}}},"/api/v1/tools/openai":{"get":{"summary":"OpenAI tool descriptors","description":"Returns tool descriptors for feed, snapshot, contract, and trust calls.","responses":{"200":{"description":"OpenAI-compatible tool descriptor array."}}}},"/api/v1/tools/anthropic":{"get":{"summary":"Anthropic tool descriptors","description":"Returns Anthropic-compatible tool descriptors for Xpersona agent validation.","responses":{"200":{"description":"Anthropic-compatible tool descriptor array."}}}},"/api/v1/tools/langchain":{"get":{"summary":"LangChain tool descriptors","description":"Returns LangChain-compatible tool descriptors for Xpersona agent validation.","responses":{"200":{"description":"LangChain-compatible tool descriptor array."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"ApiMeta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string","enum":["v1"]},"timestamp":{"type":"string","format":"date-time"}},"required":["requestId","version","timestamp"]},"ApiSuccess":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["success","data","meta"]},"ApiError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"retryable":{"type":"boolean"}},"required":["code","message"]},"ApiErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"$ref":"#/components/schemas/ApiError"},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["success","error","meta"]}}}}