{"openapi":"3.0.3","info":{"title":"CVize AI Gateway API","version":"0.1.0","description":"External API for authenticated model discovery, resume jobs, and MCP tool calls.\nPublic managed chat routes are retired and return `410 managed_chat_removed`.\nPublic `/v1/*` routes use Bearer authentication; the Studio bridge is internal\nservice-only. MCP accepts a standards-based OAuth access token or a personal\nAPI token with the `mcp:connect` scope.\n"},"servers":[{"url":"/","description":"Same-origin deployment (recommended when reading docs from the hosted app)."},{"url":"https://app.doxai.ch","description":"Production deployment."}],"tags":[{"name":"System"},{"name":"Auth"},{"name":"Models"},{"name":"Billing"},{"name":"Chat"},{"name":"Resume"},{"name":"MCP"}],"paths":{"/healthz":{"get":{"tags":["System"],"summary":"Liveness probe","security":[],"responses":{"200":{"description":"Service is alive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/readyz":{"get":{"tags":["System"],"summary":"Readiness probe","security":[],"responses":{"200":{"description":"Service dependencies are ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyResponse"}}}},"503":{"description":"Dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyResponse"}}}}}}},"/version":{"get":{"tags":["System"],"summary":"Runtime version details","security":[],"responses":{"200":{"description":"Version metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}},"/openapi.json":{"get":{"tags":["System"],"summary":"Machine-readable OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI document as JSON.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/openapi.json":{"get":{"tags":["System"],"summary":"Machine-readable OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI document as JSON.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/openapi.yaml":{"get":{"tags":["System"],"summary":"Machine-readable OpenAPI document in YAML","security":[],"responses":{"200":{"description":"OpenAPI document as YAML.","content":{"application/yaml":{"schema":{"type":"string"}}}}}}},"/v1/auth/me":{"get":{"tags":["Auth"],"summary":"Resolve token principal","description":"Returns user, token, and scopes attached to the current bearer token.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Authenticated principal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthMeResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/v1/auth/check/chat":{"get":{"tags":["Auth"],"summary":"Check chat scope","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"responses":{"200":{"description":"Scope granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeCheckResponse"},"example":{"ok":true,"request_id":"req_123","scope":"chat:run"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/auth/check/resume":{"get":{"tags":["Auth"],"summary":"Check resume scope","security":[{"bearerAuth":[]}],"x-required-scopes":["resume:generate"],"responses":{"200":{"description":"Scope granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeCheckResponse"},"example":{"ok":true,"request_id":"req_123","scope":"resume:generate"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/auth/check/tools":{"get":{"tags":["Auth"],"summary":"Check tools scope","security":[{"bearerAuth":[]}],"x-required-scopes":["tools:invoke"],"responses":{"200":{"description":"Scope granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeCheckResponse"},"example":{"ok":true,"request_id":"req_123","scope":"tools:invoke"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/auth/check/mcp":{"get":{"tags":["Auth"],"summary":"Check MCP scope","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"responses":{"200":{"description":"Scope granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeCheckResponse"},"example":{"ok":true,"request_id":"req_123","scope":"mcp:connect"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/models":{"get":{"tags":["Models"],"summary":"List models and entitlement decisions","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"parameters":[{"in":"header","name":"x-ai-mode","required":false,"schema":{"type":"string","enum":["managed","api","mcp"]},"description":"Optional model surface selector. Defaults to `api`. Public managed chat routes remain retired."}],"responses":{"200":{"description":"Models with per-user allow/deny metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/v1/billing/status":{"get":{"tags":["Billing"],"summary":"Billing status for current user","description":"Returns the internal tier, public tier label, remaining wallet credits,\nchat real-usage flag, and subscription chat allowance.\nFor subscription users, allowance includes `remaining_percent` for UI display.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"responses":{"200":{"description":"Billing status payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatusResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/v1/billing/usage":{"get":{"tags":["Billing"],"summary":"Chat usage events with tokens and credit equivalents","description":"Returns recent `chat_message` usage events with token usage, billed USD cost,\ncomputed credit equivalent, and actual billed credits.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"parameters":[{"in":"query","name":"from","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional inclusive range start (ISO datetime)."},{"in":"query","name":"to","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional exclusive range end (ISO datetime)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"Max events returned."}],"responses":{"200":{"description":"Usage report payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/v1/chat/completions":{"post":{"tags":["Chat"],"summary":"Retired managed chat endpoint","description":"Public use is retired. This endpoint returns `410 managed_chat_removed`.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"responses":{"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"410":{"$ref":"#/components/responses/GoneError"}}}},"/v1/responses":{"post":{"tags":["Chat"],"summary":"Retired managed responses endpoint","description":"Public use is retired. This endpoint returns `410 managed_chat_removed`.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["chat:run"],"responses":{"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"410":{"$ref":"#/components/responses/GoneError"}}}},"/v1/resume/jobs":{"post":{"tags":["Resume"],"summary":"Create asynchronous resume compilation job","description":"Creates an async PDF resume job. Compiling is free for every plan and\ntemplate: the returned billing metadata always reports 0 charged credits\n(older idempotent replays report their original charge).\nIn public tools-only mode this endpoint remains available.\n`cv_data` must include `template` plus `identity.first_name` and `identity.last_name`.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["resume:generate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeJobCreateRequest"}}}},"responses":{"200":{"description":"Idempotent replay (existing job returned).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeJobCreateResponse"}}}},"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeJobCreateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"409":{"$ref":"#/components/responses/ConflictError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/v1/resume/jobs/{jobId}":{"get":{"tags":["Resume"],"summary":"Get resume job status","security":[{"bearerAuth":[]}],"x-required-scopes":["resume:generate"],"parameters":[{"$ref":"#/components/parameters/JobIdPath"}],"responses":{"200":{"description":"Job found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeJobGetResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/resume/jobs/{jobId}/pdf":{"get":{"tags":["Resume"],"summary":"Download generated resume PDF","security":[{"bearerAuth":[]}],"x-required-scopes":["resume:generate"],"parameters":[{"$ref":"#/components/parameters/JobIdPath"}],"responses":{"200":{"description":"PDF artifact bytes.","headers":{"x-resume-storage-bucket":{"schema":{"type":"string"}},"x-resume-storage-path":{"schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/resume/templates":{"get":{"tags":["Resume"],"summary":"List supported resume templates and style values","description":"Returns the template catalog used by resume validation, including valid\ntheme colors, font families, font sizes, localized labels, and preview URLs.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["resume:generate"],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","fr","de"]},"description":"Optional label locale."}],"responses":{"200":{"description":"Template catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeTemplatesResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["MCP"],"summary":"MCP OAuth protected-resource metadata (root)","description":"RFC 9728 protected-resource metadata advertising the MCP authorization\nserver(s) and supported scopes. Unauthenticated discovery endpoint.\n","security":[],"responses":{"200":{"description":"Protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-protected-resource/v1/mcp":{"get":{"tags":["MCP"],"summary":"MCP OAuth protected-resource metadata (resource-scoped)","description":"Resource-scoped RFC 9728 protected-resource metadata for the `/v1/mcp`\nendpoint. Unauthenticated discovery endpoint.\n","security":[],"responses":{"200":{"description":"Protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/v1/mcp/tools":{"get":{"tags":["MCP"],"summary":"List MCP tools","description":"Returns the namespaced app, account, resume, and CV tool catalog.\nEvery definition includes a title, input/output schemas, and MCP annotations.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"responses":{"200":{"description":"Tool manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolsResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/mcp":{"post":{"tags":["MCP"],"summary":"Streamable HTTP MCP JSON-RPC endpoint","description":"Primary MCP server transport endpoint.\nSend JSON-RPC requests (`initialize`, `tools/list`, `tools/call`,\n`resources/list`, `resources/read`, `ping`).\nThe server advertises both tools and resources capabilities. Resources include\n`cv://templates`, `cv://resumes`, user-owned `cv://resumes/{id}`, and\n`cv://profile`.\nSupported protocol versions are `2025-11-25`, `2025-06-18`, `2025-03-26`,\nand `2024-11-05`.\nSession ID is returned in `MCP-Session-Id` and must be reused by clients.\n\nCredentials are optional for the public methods and tools (lazy authentication):\nwithout them `initialize`, `ping`, `notifications/*`, `tools/list`, `resources/list`,\n`resources/templates/list`, `resources/read` of `cv://templates`, and `tools/call` of\n`search_jobs`, `get_job`, `app_get_info`, `resume_list_templates` and `recommend_jobs`\n(only with `cv_text`) are served to a guest. Any other message answers `401` with the\n`WWW-Authenticate` challenge. Guest traffic is rate limited without using the IP\n(`429` with `Retry-After`), and the challenge is never replaced by a `429`.\n","security":[{},{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"parameters":[{"$ref":"#/components/parameters/McpSessionIdHeader"},{"$ref":"#/components/parameters/McpProtocolVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcMessage"}}}},"responses":{"200":{"description":"JSON-RPC response payload.","headers":{"MCP-Session-Id":{"schema":{"type":"string"}},"MCP-Protocol-Version":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcMessage"}}}},"202":{"description":"Single notification accepted without a JSON-RPC response body."},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"}}},"get":{"tags":["MCP"],"summary":"Attach SSE stream to existing MCP session","description":"Optional streamable transport SSE channel for server-to-client events.\nRequires `MCP-Session-Id`.\nRequires credentials: without them the answer is `405` (no server stream for guests).\n","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"parameters":[{"$ref":"#/components/parameters/McpSessionIdHeaderRequired"},{"$ref":"#/components/parameters/McpProtocolVersionHeaderRequired"}],"responses":{"200":{"description":"SSE stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"405":{"description":"No credentials. The server stream needs a signed-in session."},"429":{"$ref":"#/components/responses/RateLimitedError"}}},"delete":{"tags":["MCP"],"summary":"Close MCP session","description":"Credentials are optional. A guest may close its own anonymous session.","security":[{},{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"parameters":[{"$ref":"#/components/parameters/McpSessionIdHeaderRequired"},{"$ref":"#/components/parameters/McpProtocolVersionHeaderRequired"}],"responses":{"204":{"description":"Session closed."},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/mcp/sse":{"get":{"tags":["MCP"],"summary":"Legacy SSE MCP transport endpoint","description":"Legacy MCP transport compatibility route.\nEmits an `endpoint` SSE event containing `/v1/mcp/messages?session_id=...`.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"responses":{"200":{"description":"SSE stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/v1/mcp/messages":{"post":{"tags":["MCP"],"summary":"Legacy SSE MCP message ingress","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"parameters":[{"$ref":"#/components/parameters/McpSessionIdQueryRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcPayload"}}}},"responses":{"202":{"description":"Message accepted and emitted over SSE stream."},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/mcp/tools/call":{"post":{"tags":["MCP"],"summary":"Invoke MCP tool","description":"Invokes one MCP tool call.\nFor `resume_create_job`, `arguments.cv_data.template` is required and is the single supported template field.\nRead-only app, account, validation, template, job, resume, and CV-entry tools are also available.\nJob-ad tools (`search_jobs`, `get_job`, `recommend_jobs`) are read-only and free: ads from employers\nacross Switzerland, collected nightly, not exhaustive. `create_opportunity` accepts their `job_id`.\n`recommend_jobs` accepts an optional `cv_text` (200-20,000 characters) to rank against instead of the stored\nprofile; it is used for matching only and never stored or logged.\nCV persistence tools explicitly scope all reads and writes to the authenticated user.\n","security":[{"bearerAuth":[]}],"x-required-scopes":["mcp:connect"],"x-oauth-access-token-accepted":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolCallRequest"}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolCallResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"402":{"$ref":"#/components/responses/PaymentRequiredError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"409":{"$ref":"#/components/responses/ConflictError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Personal API Token or OAuth Access Token","description":"Personal API tokens require the scope declared by each operation. MCP also accepts OAuth access tokens from the configured authorization server."}},"parameters":{"JobIdPath":{"in":"path","name":"jobId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Resume job UUID."},"McpSessionIdHeader":{"in":"header","name":"MCP-Session-Id","required":false,"schema":{"type":"string"},"description":"MCP session ID returned by `initialize`."},"McpSessionIdHeaderRequired":{"in":"header","name":"MCP-Session-Id","required":true,"schema":{"type":"string"},"description":"MCP session ID returned by `initialize`."},"McpProtocolVersionHeader":{"in":"header","name":"MCP-Protocol-Version","required":false,"schema":{"type":"string","enum":["2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"Negotiated MCP protocol version. It must match the initialized session on subsequent streamable HTTP requests; omission uses the 2025-03-26 compatibility fallback."},"McpProtocolVersionHeaderRequired":{"in":"header","name":"MCP-Protocol-Version","required":true,"schema":{"type":"string","enum":["2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"Negotiated MCP protocol version for an initialized streamable HTTP session."},"McpSessionIdQuery":{"in":"query","name":"session_id","required":false,"schema":{"type":"string"},"description":"Legacy SSE transport session ID."},"McpSessionIdQueryRequired":{"in":"query","name":"session_id","required":true,"schema":{"type":"string"},"description":"Legacy SSE transport session ID."}},"responses":{"BadRequestError":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnauthorizedError":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"unauthorized","message":"Missing bearer token","details":null},"request_id":"req_123"}}}},"PaymentRequiredError":{"description":"Tier or credit requirement not met.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ForbiddenError":{"description":"Missing required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ConflictError":{"description":"Idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"GoneError":{"description":"Endpoint is retired and no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFoundError":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimitedError":{"description":"Token or user request limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServiceUnavailableError":{"description":"Upstream or internal service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"GatewayError":{"type":"object","additionalProperties":false,"required":["code","status","message","details","category","retryable","suggested_action"],"properties":{"code":{"type":"string"},"status":{"type":"integer"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true,"nullable":true},"category":{"type":"string","enum":["validation","auth","quota","billing","provider","rate_limit","conflict","not_found","internal"]},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"}}},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"$ref":"#/components/schemas/GatewayError"},"request_id":{"type":"string"}}},"HealthResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","service"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"service":{"type":"string","example":"ai-gateway"}}},"ReadyResponse":{"type":"object","required":["ok","checks","request_id"],"properties":{"ok":{"type":"boolean"},"checks":{"type":"object","required":["supabase"],"properties":{"supabase":{"type":"boolean"}}},"request_id":{"type":"string"},"error_code":{"type":"string","nullable":true}},"additionalProperties":false},"VersionResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","service","node_env","version"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"service":{"type":"string"},"node_env":{"type":"string"},"version":{"type":"string"}}},"AuthPrincipal":{"type":"object","required":["user_id","token_id","token_name","token_prefix","scopes","expires_at"],"properties":{"user_id":{"type":"string","format":"uuid"},"token_id":{"type":"string","format":"uuid","nullable":true},"token_name":{"type":"string","nullable":true},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string","enum":["chat:run","resume:generate","tools:invoke","mcp:connect"]}},"expires_at":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"AuthMeResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","principal"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"principal":{"$ref":"#/components/schemas/AuthPrincipal"}}},"ScopeCheckResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","scope"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"scope":{"type":"string"}}},"ModelPricing":{"type":"object","additionalProperties":false,"required":["inputUsdPer1M","outputUsdPer1M"],"properties":{"inputUsdPer1M":{"type":"number"},"outputUsdPer1M":{"type":"number"},"inputUsdPer1MOver200k":{"type":"number"},"outputUsdPer1MOver200k":{"type":"number"},"highContextThresholdTokens":{"type":"integer"}}},"ModelInfo":{"type":"object","required":["id","label","provider","protocol","origin","surfaces","api_model","access","description","usage_multiplier","pricing","allowed","blocked_reason","paywall_required","fallback_model_ids"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"provider":{"type":"string","description":"Built-in providers or `custom:<slug>` for custom registry entries.","example":"custom:moonshot"},"protocol":{"type":"string","enum":["openai-completions","anthropic-messages","google-generative-ai"]},"origin":{"type":"string","enum":["provided","custom"]},"surfaces":{"type":"array","items":{"type":"string","enum":["managed","api","mcp"]}},"api_model":{"type":"string"},"access":{"type":"string","enum":["all","paid","subscription"],"description":"Internal model access bucket. `paid` means a non-free model that Flex and Pro users may access."},"description":{"type":"string"},"usage_multiplier":{"type":"number"},"pricing":{"$ref":"#/components/schemas/ModelPricing"},"allowed":{"type":"boolean"},"blocked_reason":{"type":"string","nullable":true},"paywall_required":{"type":"boolean"},"fallback_model_ids":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"ModelsResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","surface","tier","tier_label","models"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"surface":{"type":"string","enum":["managed","api","mcp"]},"tier":{"type":"string","enum":["free","credits","subscription"]},"tier_label":{"type":"string","enum":["free","flex","pro"]},"models":{"type":"array","items":{"$ref":"#/components/schemas/ModelInfo"}}}},"SubscriptionChatAllowance":{"type":"object","additionalProperties":false,"required":["window_start","window_end","limit_usd","used_usd","remaining_usd","remaining_percent"],"properties":{"window_start":{"type":"string","format":"date-time"},"window_end":{"type":"string","format":"date-time"},"limit_usd":{"type":"number"},"used_usd":{"type":"number"},"remaining_usd":{"type":"number"},"remaining_percent":{"type":"number","description":"Weekly subscription chat allowance percentage remaining (0-100)."}}},"BillingStatusResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","tier","tier_label","remaining_credits","chat_real_usage_enabled","subscription_chat_allowance"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"tier":{"type":"string","enum":["free","credits","subscription"]},"tier_label":{"type":"string","enum":["free","flex","pro"]},"remaining_credits":{"type":"number"},"chat_real_usage_enabled":{"type":"boolean"},"subscription_chat_allowance":{"allOf":[{"$ref":"#/components/schemas/SubscriptionChatAllowance"}],"nullable":true}}},"BillingUsageQuery":{"type":"object","additionalProperties":false,"required":["from","to","limit"],"properties":{"from":{"type":"string","format":"date-time","nullable":true},"to":{"type":"string","format":"date-time","nullable":true},"limit":{"type":"integer"}}},"BillingUsageSummary":{"type":"object","additionalProperties":false,"required":["events","provider_usage_events","estimated_fallback_events","total_input_tokens","total_output_tokens","total_tokens","total_cost_usd","total_computed_credits","total_billed_credits"],"properties":{"events":{"type":"integer"},"provider_usage_events":{"type":"integer"},"estimated_fallback_events":{"type":"integer"},"total_input_tokens":{"type":"integer"},"total_output_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"total_cost_usd":{"type":"number"},"total_computed_credits":{"type":"number","description":"Cost converted to credits at 0.1 USD per credit."},"total_billed_credits":{"type":"number","description":"Actual debited credits from usage events."}}},"BillingUsageItem":{"type":"object","additionalProperties":false,"required":["id","created_at","source","model_id","provider","usage_source","input_tokens","output_tokens","total_tokens","cost_usd","computed_credits","billed_credits"],"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"model_id":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true},"usage_source":{"type":"string","enum":["provider_usage","estimated_fallback"],"nullable":true},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"cost_usd":{"type":"number"},"computed_credits":{"type":"number","description":"Cost converted to credits at 0.1 USD per credit."},"billed_credits":{"type":"number","description":"Actual billed credits from `credits_delta`."}}},"BillingUsageResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","query","summary","items"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"query":{"$ref":"#/components/schemas/BillingUsageQuery"},"summary":{"$ref":"#/components/schemas/BillingUsageSummary"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BillingUsageItem"}}}},"ResumeJobCreateRequest":{"type":"object","required":["request_id","cv_data"],"properties":{"request_id":{"type":"string"},"language":{"type":"string","enum":["en","fr","de"],"description":"Optional shortcut for cv_data.language."},"mode":{"type":"string","enum":["managed","byom_tools"],"default":"managed"},"cv_data":{"type":"object","required":["template","identity"],"properties":{"template":{"type":"string","enum":["original","picture","harvard","business","sidebar"],"description":"Required source-of-truth template field."},"language":{"type":"string","enum":["en","fr","de"],"description":"Localizes default section headings and Present labels."},"theme_color":{"type":"string","description":"Optional theme color. Recommended values are listed by GET /v1/resume/templates (ResumeThemeColor); an unrecognized color falls back to the template default instead of failing the job."},"font_family":{"$ref":"#/components/schemas/ResumeFontFamily"},"font_size":{"$ref":"#/components/schemas/ResumeFontSize"},"identity":{"type":"object","required":["first_name","last_name"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"}},"additionalProperties":true},"sections":{"type":"object","additionalProperties":true},"sections_order":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"additionalProperties":false},"OAuthProtectedResourceMetadata":{"type":"object","description":"RFC 9728 OAuth protected-resource metadata.","additionalProperties":true,"properties":{"resource":{"type":"string"},"authorization_servers":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}}},"ResumeThemeColor":{"type":"string","enum":["black","NavyBlue","RoyalBlue","blue","brown","cyan","darkgray","gray","green","OliveGreen","magenta","olive","orange","pink","purple","red","teal","violet","yellow"]},"ResumeFontFamily":{"type":"string","enum":["arial","carlito","helvetica","noto-sans","source-sans-3"]},"ResumeFontSize":{"type":"string","enum":["8pt","9pt","10pt","11pt","12pt","14pt","17pt","20pt"]},"ResumeTemplate":{"type":"object","additionalProperties":false,"required":["id","label","theme_colors","font_families","font_sizes","preview_url"],"properties":{"id":{"type":"string","enum":["original","picture","harvard","business","sidebar"]},"label":{"type":"string"},"description":{"type":"string"},"theme_colors":{"type":"array","items":{"$ref":"#/components/schemas/ResumeThemeColor"}},"font_families":{"type":"array","items":{"$ref":"#/components/schemas/ResumeFontFamily"}},"font_sizes":{"type":"array","items":{"$ref":"#/components/schemas/ResumeFontSize"}},"preview_url":{"type":"string"},"default_theme_color":{"$ref":"#/components/schemas/ResumeThemeColor"},"default_font_family":{"$ref":"#/components/schemas/ResumeFontFamily"},"default_font_size":{"$ref":"#/components/schemas/ResumeFontSize"},"compile_credits":{"type":"number","description":"Always 0 — compiling a PDF is free for every template and plan."},"first_compile_free":{"type":"boolean","description":"Always true (kept for compatibility)."}}},"ResumeTemplatesResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","templates"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"templates":{"type":"array","items":{"$ref":"#/components/schemas/ResumeTemplate"}}}},"ResumeJobSummary":{"type":"object","required":["id","status","mode","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"mode":{"type":"string","enum":["managed","byom_tools"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"ResumeJob":{"type":"object","required":["id","user_id","request_id","mode","status","input_payload","output_metadata","error_code","error_message","started_at","completed_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"request_id":{"type":"string","nullable":true},"mode":{"type":"string","enum":["managed","byom_tools"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"input_payload":{"type":"object","additionalProperties":true},"output_metadata":{"type":"object","additionalProperties":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"ResumeJobCreateResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","idempotent_replay","job_id","billing","job"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"idempotent_replay":{"type":"boolean"},"job_id":{"type":"string","format":"uuid"},"billing":{"$ref":"#/components/schemas/ResumeJobBilling"},"job":{"$ref":"#/components/schemas/ResumeJobSummary"}}},"ResumeJobBilling":{"type":"object","additionalProperties":false,"required":["charged_credits","remaining_credits","idempotent_replay","template","cv_template"],"properties":{"charged_credits":{"type":"number","minimum":0},"remaining_credits":{"type":"number","nullable":true},"idempotent_replay":{"type":"boolean"},"template":{"type":"string","enum":["original","picture"]},"cv_template":{"type":"string","enum":["original","picture","harvard","business","sidebar"]}}},"ResumeJobGetResponse":{"type":"object","additionalProperties":false,"required":["ok","request_id","job"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"job":{"$ref":"#/components/schemas/ResumeJob"}}},"McpToolDefinition":{"type":"object","required":["name","title","description","input_schema","output_schema","annotations"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":true},"output_schema":{"type":"object","additionalProperties":true},"annotations":{"$ref":"#/components/schemas/McpToolAnnotations"}},"additionalProperties":false},"McpToolAnnotations":{"type":"object","required":["readOnlyHint","destructiveHint","idempotentHint","openWorldHint"],"properties":{"readOnlyHint":{"type":"boolean"},"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"}},"additionalProperties":false},"McpJsonRpcMessage":{"type":"object","additionalProperties":true},"McpJsonRpcPayload":{"oneOf":[{"$ref":"#/components/schemas/McpJsonRpcMessage"},{"type":"array","items":{"$ref":"#/components/schemas/McpJsonRpcMessage"}}]},"McpToolsResponse":{"type":"object","required":["ok","request_id","mode","tools"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"mode":{"type":"string","enum":["namespaced_tools"]},"tools":{"type":"array","items":{"$ref":"#/components/schemas/McpToolDefinition"}}},"additionalProperties":false},"McpToolCallRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["app_get_info","account_get_billing_status","resume_create_job","resume_validate_cv_data","resume_get_create_job_example","resume_get_job","resume_get_pdf","resume_list_templates","resume_list_jobs","cv_list_resumes","cv_get_resume","cv_create_resume","cv_update_resume","cv.list_entries","cv.upsert_entry","get_profile","update_profile","patch_profile_entries","list_opportunities","get_opportunity","list_applications","get_application","search_jobs","get_job","recommend_jobs","create_opportunity","analyze_opportunity","create_application","generate_application","generate_letter","get_application_cv_pdf","get_application_letter","resolve_review_points","update_application_status","quick_apply"]},"arguments":{"type":"object","additionalProperties":true}},"additionalProperties":false},"McpToolCallResponse":{"type":"object","required":["ok","request_id","tool","result"],"properties":{"ok":{"type":"boolean"},"request_id":{"type":"string"},"tool":{"type":"string"},"result":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}}