{"openapi":"3.1.0","info":{"title":"gotcontext.ai API","description":"Semantic compression API — cut AI token costs by up to 85%. Compress text and code while preserving meaning. Supports REST API and MCP (Model Context Protocol) via Streamable HTTP.","contact":{"name":"gotcontext.ai","url":"https://gotcontext.ai/","email":"support@gotcontext.ai"},"license":{"name":"Proprietary","url":"https://gotcontext.ai/terms"},"version":"1.52.14"},"servers":[{"url":"https://api.gotcontext.ai","description":"Production"},{"url":"http://localhost:8080","description":"Local development"}],"paths":{"/health":{"get":{"tags":["health","health"],"summary":"Health Shortcut","description":"Alias for /health/liveness — convenience for monitoring tools.","operationId":"health_shortcut_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/liveness":{"get":{"tags":["health"],"summary":"Liveness","description":"Simple alive check — always returns 200 if process is running.","operationId":"liveness_health_liveness_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/readiness":{"get":{"tags":["health"],"summary":"Readiness","description":"Readiness check — verifies core dependencies are available.","operationId":"readiness_health_readiness_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/diagnostics":{"get":{"tags":["health"],"summary":"Diagnostics","description":"Detailed diagnostics snapshot for ops/SRE monitoring.\n\nNot auth-gated — all fields are operational metadata, no user data.\n\nFields populated at this time:\n - status, version, uptime_seconds, circuit_breakers: always present.\n - latency_p50/p95/p99_ms: null — populated by latency middleware in v1.10.\n - cache_hit_rate: sourced from token-saver HealthChecker when available.\n - mcp_sessions_active: null — MCP session count not yet exposed via a\n stable accessor; tracked via Prometheus gc_mcp_* counters instead.","operationId":"diagnostics_health_diagnostics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/infra/health":{"get":{"tags":["infra"],"summary":"Get Health","operationId":"get_health_v1_infra_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/metrics":{"get":{"tags":["monitoring"],"summary":"Prometheus Metrics","description":"Export Prometheus metrics in text format.\n\nIncludes counters and gauges from the prometheus_client registry.\nUseful for Grafana dashboards, alerting, and SLO monitoring.","operationId":"prometheus_metrics_metrics_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["oauth"],"summary":"Oauth Protected Resource","description":"Return the RFC 9728 Protected Resource Metadata document.","operationId":"oauth_protected_resource__well_known_oauth_protected_resource_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Oauth Protected Resource Well Known Oauth Protected Resource Get"}}}}}}},"/.well-known/agent.json":{"get":{"tags":["a2a"],"summary":"Agent Card Legacy","description":"A2A Agent Card — legacy 0.x path used by early Vertex AI ADK + CEO spec.","operationId":"agent_card_legacy__well_known_agent_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/agent-card.json":{"get":{"tags":["a2a"],"summary":"Agent Card","description":"A2A Agent Card — v1.0 canonical path per spec section 8.2.","operationId":"agent_card__well_known_agent_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/internal/benchmark-aggregate":{"get":{"tags":["internal"],"summary":"Benchmark Aggregate","description":"Return aggregated benchmark rows (v0: empty; v1: first-party MCP traffic).\n\nRequires ``X-Internal-Token`` header matching the ``INTERNAL_API_TOKEN``\nenvironment variable. Returns 401 if the token is absent or incorrect.","operationId":"benchmark_aggregate_internal_benchmark_aggregate_get","parameters":[{"name":"x-internal-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Internal-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compress":{"post":{"tags":["compression"],"summary":"Compress","description":"Compress text using semantic compression.\n\nv1.9.0: end-to-end latency is recorded as ``gc_compress_duration_seconds``\nfor the CompressP95HighLatency Prometheus alert rule.\n\nAchieves 80-95% token reduction on medium-to-large documents.\nSmall documents (<100 tokens) may see less compression.\n\nPass an optional ``query`` to enable query-guided mode — the compressor\nwill prioritise sections most relevant to your query while maintaining\nthe overall compression ratio set by ``fidelity``.\n\nv1.3 adds a plan-gated semantic dedup cache. Pro/Team/Enterprise\ncompressions go through the cache first; on hit the stored response\nis returned verbatim with ``X-Semantic-Cache: hit``. On miss the\nnormal compressor runs and the response is stored with a\nplan-sized TTL (1h/24h/7d). Free plan bypasses the cache entirely.","operationId":"compress_v1_compress_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compress-code":{"post":{"tags":["compression"],"summary":"Compress Code Endpoint","description":"Compress source code using AST-aware semantic compression.\n\nUnlike plain text compression, this endpoint:\n- Parses the AST to respect function/class boundaries as natural chunk units\n- Extracts imports, docstrings, and dependency graphs\n- Ranks functions/classes by importance using PageRank on the dependency graph\n- Returns a skeleton with signatures, docstrings, and importance scores\n\nSupported languages: Python (AST-native), JavaScript/TypeScript (regex-based),\nJava, Go, Rust, C++ (line-based fallback).\n\nAuto-detects language from content when ``language`` is not provided.","operationId":"compress_code_endpoint_v1_compress_code_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressCodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressCodeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compress-code/structural":{"post":{"tags":["compression"],"summary":"Compress Code Structural","description":"v1.5.0 — structural-context compression via tensor-grep blast-radius\n+ BM25 + Reciprocal Rank Fusion.","operationId":"compress_code_structural_v1_compress_code_structural_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuralCompressRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuralCompressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-compress":{"post":{"tags":["compression"],"summary":"Batch Compress","description":"Compress multiple documents concurrently.\n\nAccepts up to 50 documents per call. Each document may specify its own\n``fidelity`` level and optional ``query`` for query-guided mode.\n\nDocuments are processed with bounded concurrency (max 4 simultaneous) to\navoid saturating the embedding model. Failed documents are reported in the\n``results`` list with an ``error`` field; the overall batch still returns 200.\n\nReturns per-document results plus aggregate summary statistics.","operationId":"batch_compress_v1_batch_compress_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/recommend":{"post":{"tags":["compression"],"summary":"Recommend","description":"Recommend the best compression fidelity level for a document.\n\nAnalyses document size and (optionally) the target model's context window\nto suggest a fidelity level that balances information preservation with\ntoken efficiency.\n\nRules (in priority order):\n1. Document < 500 tokens → \"detailed\" (minimal compression, preserve quality)\n2. Document 500–2,000 tokens → \"balanced\" (standard 5× compression target)\n3. Document 2,000–10,000 tokens → \"outline\" (structural skeleton)\n4. Document > 10,000 tokens → \"abstract\" (aggressive summary)\n5. If model/context_window provided and compressed output would exceed 70% of\n the context window, step up to a more aggressive fidelity level.","operationId":"recommend_v1_recommend_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys":{"get":{"tags":["api-keys"],"summary":"List Keys","description":"List all API keys for the authenticated user.\n\nReads from Postgres (authoritative). Returns 503 when the database is\nunavailable rather than serving potentially stale partial data.","operationId":"list_keys_v1_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKeysResponse"}}}}}},"post":{"tags":["api-keys"],"summary":"Create Key","description":"Create a new API key for the authenticated user.\n\nThe full key is returned **once** in the response and cannot be retrieved\nagain. Store it in a secure location immediately.\n\nKeys are prefixed ``gc_`` and consist of 32 random hex characters.\nThey can be used with ``Authorization: Bearer gc_...`` headers as an\nalternative to Clerk JWT tokens.\n\nStorage order: Postgres first (primary), then Redis (cache).\nIf Postgres is unavailable, return 503 rather than creating a partial key.","operationId":"create_key_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/{key_id}":{"patch":{"tags":["api-keys"],"summary":"Update Key","description":"Update mutable fields on an API key.\n\nCurrently supports ``name``, ``default_model``, and ``monthly_quota``\n(v1.20.2 per-key quota). Pass ``\"monthly_quota\": null`` to clear the\nquota — the key becomes uncapped and ``quota_alert_state`` resets\nto ``'none'``. Any change to ``monthly_quota`` (set or clear) also\nresets ``quota_period_start`` to the current time so the next cron\nsweep evaluates against a clean window.","operationId":"update_key_v1_keys__key_id__patch","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyListItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["api-keys"],"summary":"Revoke Key","description":"Revoke an API key by ID.\n\nUpdates Postgres status to 'revoked' (primary), then removes the Redis\ncache entries so the auth middleware stops accepting the key immediately.","operationId":"revoke_key_v1_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/{key_id}/rotate":{"post":{"tags":["api-keys"],"summary":"Rotate Key","description":"Rotate an API key (v1.20.10).\n\nCreates a successor key in one atomic call, sets the predecessor's\n``expires_at = now + grace_period_days`` (auth-time enforcement\nvia v1.20.9 cuts the predecessor off when the deadline passes), and\nlinks the pair via ``replaces_key_id`` / ``replaced_by_key_id``.\n\nThe successor inherits the predecessor's environment, default_model,\nenforce_quota, and monthly_quota. The successor's plan is sourced\nfrom the caller's current plan (``request.state.plan``) — this\nmatches ``POST /v1/keys`` semantics so a customer who has upgraded\nsince the predecessor was minted gets a fresh-plan key.\n\nReturns the plaintext successor exactly once.\n\nSee:\n - docs/plans/requirements-gotcontext-2026-04-26-2200.md (§F1-F5)\n - docs/plans/design-gotcontext-2026-04-26-2200.md (§3.4)","operationId":"rotate_key_v1_keys__key_id__rotate_post","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/confirm/{token_hash}":{"post":{"tags":["api-keys"],"summary":"Complete a confirm-token approval","description":"Complete a single-use confirmation-token operation.\n\nThis endpoint is callable only via a Clerk session (not a gc_ API key)\nbecause it approves destructive actions on the caller's own keys.\n\nSteps:\n 1. 404 — token not found.\n 2. 410 — token expired.\n 3. 409 — token already consumed.\n 4. 403 — token belongs to a different user.\n 5. SELECT FOR UPDATE + set consumed_at (atomic, prevents double-use).\n 6. Execute the operation (rotate | revoke | scope_grant).\n 7. Return a structured response.\n\nPart of Phase 2 (ships as v1.35.0 when all chunks land).","operationId":"confirm_token_v1_keys_confirm__token_hash__post","parameters":[{"name":"token_hash","in":"path","required":true,"schema":{"type":"string","title":"Token Hash"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/leads":{"post":{"tags":["leads"],"summary":"Create Lead","description":"Persist a sales lead and notify the gotcontext sales inbox.","operationId":"create_lead_v1_leads_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/licenses/generate":{"post":{"tags":["licenses"],"summary":"Generate License","description":"Generate a signed self-hosted license, persist it, and email it via Resend.","operationId":"generate_license_v1_licenses_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateLicenseRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateLicenseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/licenses/validate":{"post":{"tags":["licenses"],"summary":"Validate License","description":"Public endpoint that verifies a self-hosted license signature and expiry.","operationId":"validate_license_v1_licenses_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateLicenseRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseValidationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metering":{"post":{"tags":["licenses"],"summary":"Ingest Metering Report","description":"Accept one self-hosted usage report authenticated by the license key.","operationId":"ingest_metering_report_v1_metering_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeteringReportRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeteringAcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Checkout","description":"Create a Polar checkout session for upgrading to a paid plan.\n\nRequires authentication — reads ``user_id`` from ``request.state`` (set by\nthe Clerk JWT middleware).\n\nArgs:\n req: Body with ``plan`` field (currently only \"pro\" is valid).\n request: FastAPI request object (provides auth state).\n\nReturns:\n CheckoutResponse with ``checkout_url`` to redirect the client to.","operationId":"create_checkout_v1_billing_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/portal":{"post":{"tags":["billing"],"summary":"Customer Portal","description":"Return the Polar customer portal URL for the authenticated user.\n\nRequires authentication — reads ``user_id`` and ``polar_customer_id`` from\n``request.state`` (set by the Clerk JWT middleware).\n\nArgs:\n request: FastAPI request object (provides auth state).\n\nReturns:\n PortalResponse with ``portal_url`` to redirect the client to.","operationId":"customer_portal_v1_billing_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}}}}},"/v1/billing/orders":{"get":{"tags":["billing"],"summary":"List Billing Orders","description":"List the authenticated user's Polar order history.","operationId":"list_billing_orders_v1_billing_orders_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/OrderItem"},"type":"array","title":"Response List Billing Orders V1 Billing Orders Get"}}}}}}},"/v1/billing/subscription":{"get":{"tags":["billing"],"summary":"Get Subscription Info","description":"Return the authenticated user's current plan and subscription details.","operationId":"get_subscription_info_v1_billing_subscription_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionInfo"}}}}}}},"/v1/billing/meter-usage":{"get":{"tags":["billing"],"summary":"Get Meter Usage","description":"Return the authenticated user's metered compression count for this billing period.\n\nReads from Polar's Meters API. Falls back to a cached value when the\nPolar breaker is open so the dashboard widget never shows a stale 0\nduring a Polar outage.\n\nFree-plan users return count=0 since they never emit events.","operationId":"get_meter_usage_v1_billing_meter_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterUsageResponse"}}}}}}},"/v1/billing/overage-preview":{"get":{"tags":["billing"],"summary":"Get Overage Preview","description":"Return the authenticated user's projected overage cost for this period.\n\nFree plans return a zero overage (hard cap enforced elsewhere).\nEnterprise returns ``included_units=-1`` (unlimited) with zero cost.\nPaid tiers (pro/team) compute: ``overage = max(0, used - included)``,\ncost = ``overage * unit_amount_cents``, billed = ``min(cost, cap)``.\n\nAll math is deterministic from env knobs — CEO can tune without\nredeploy via ``flyctl secrets set``.","operationId":"get_overage_preview_v1_billing_overage_preview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OveragePreviewResponse"}}}}}}},"/v1/usage":{"get":{"tags":["usage"],"summary":"Get Usage","description":"Return monthly compression stats for the authenticated user.\n\nReads daily Redis counters for the current calendar month and sums them.\nKey patterns:\n ``usage:{user_id}:{YYYY-MM-DD}`` — compression count\n ``usage_tokens_in:{user_id}:{YYYY-MM-DD}`` — original token total\n ``usage_tokens_saved:{user_id}:{YYYY-MM-DD}`` — tokens saved total\n\nRequires authentication — reads ``user_id`` and ``plan`` from\n``request.state`` (set by AuthMiddleware).","operationId":"get_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}}}}},"/v1/usage/activation":{"get":{"tags":["usage","admin"],"summary":"Get Usage Activation","description":"Return a time-to-first-compression histogram segmented by plan.\n\nAdmin-only. Reads ``users`` LEFT JOIN ``MIN(usage_events.created_at)``\nand buckets the delta against ``users.created_at`` into:\n``<1h | 1h-24h | 1d-7d | never``.\n\nResponse shape::\n\n {\n \"period\": \"all_time\",\n \"buckets\": {\n \"free\": {\"<1h\": int, \"1h-24h\": int, \"1d-7d\": int, \"never\": int},\n \"pro\": {...},\n \"team\": {...},\n \"enterprise\": {...}\n },\n \"generated_at\": \"2026-04-23T...\"\n }","operationId":"get_usage_activation_v1_usage_activation_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Usage Activation V1 Usage Activation Get"}}}}}}},"/v1/usage/by-model":{"get":{"tags":["usage"],"summary":"Usage By Model","operationId":"usage_by_model_v1_usage_by_model_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageByModelResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/by-cache":{"get":{"tags":["usage"],"summary":"Usage By Cache","operationId":"usage_by_cache_v1_usage_by_cache_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageByCacheResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/by-key":{"get":{"tags":["usage"],"summary":"Usage By Key","description":"Top-N API keys by tokens saved across the window.","operationId":"usage_by_key_v1_usage_by_key_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageByKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/by-tool":{"get":{"tags":["usage"],"summary":"Usage By Tool","description":"Top tools called by this user over the last N days.\n\nNULL tool_name rows (REST /v1/compress hits) bucket under\n``\"rest-api\"``. Returns at most ``_TOP_N`` items ordered by call\ncount descending. Zero-tokens_saved rows (e.g. gc_blast_radius)\nstill count — the endpoint measures engagement, not savings.","operationId":"usage_by_tool_v1_usage_by_tool_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageByToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/by-client":{"get":{"tags":["usage"],"summary":"Usage By Client","description":"Tool-call counts + compression ratios grouped by AI client over the last N days.\n\nPer-user. NULL on both signals → \"other\" bucket. Rows ordered by\ncall count descending.","operationId":"usage_by_client_v1_usage_by_client_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageByClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/history":{"get":{"tags":["usage"],"summary":"Get Usage History","description":"Return daily compression stats for the last N days.\n\nEach element in ``data`` corresponds to one calendar day. Days with no\nrecorded activity return zeros — the client always receives exactly ``days``\ndata points.\n\nRequires authentication — reads ``user_id`` from ``request.state``.","operationId":"get_usage_history_v1_usage_history_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Granularity — currently only 'day' is supported","default":"day","title":"Period"},"description":"Granularity — currently only 'day' is supported"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"description":"Number of days to look back","default":30,"title":"Days"},"description":"Number of days to look back"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/events":{"get":{"tags":["analytics"],"summary":"Get Usage Events","description":"Return paginated compression history for the authenticated user.\n\nEach event represents one compression call with input/output token\ncounts, savings percentage, fidelity level, method (REST/MCP/batch),\nand latency. Users can see exactly what the engine did with their data.\n\n**Privacy:** Input text is NOT stored. Only a 100-char preview\n(first line, truncated) is kept for identification purposes.\nUsers can identify which document a compression belongs to without\nthe full content being retained.","operationId":"get_usage_events_v1_usage_events_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Page Size"}},{"name":"fidelity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fidelity"}},{"name":"method","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"}},{"name":"exclude_advisory","in":"query","required":false,"schema":{"type":"boolean","description":"Exclude advisory/non-compressing MCP tool calls (method='mcp_advisory', e.g. gc_lookup, ingest_context, gc_agent_capsule). The Compression History view sets this so 0-token advisory rows don't dominate it and make it look broken.","default":false,"title":"Exclude Advisory"},"description":"Exclude advisory/non-compressing MCP tool calls (method='mcp_advisory', e.g. gc_lookup, ingest_context, gc_agent_capsule). The Compression History view sets this so 0-token advisory rows don't dominate it and make it look broken."},{"name":"model","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by call status (success, client_error, timeout, ...)","title":"Status"},"description":"Filter by call status (success, client_error, timeout, ...)"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"ISO timestamp; only return events created after.","title":"Since"},"description":"ISO timestamp; only return events created after."},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"ISO timestamp; only return events created before.","title":"Until"},"description":"ISO timestamp; only return events created before."},{"name":"key_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter by api_keys.key_id (v1.20.6). Cross-tenant safe.","title":"Key Id"},"description":"Filter by api_keys.key_id (v1.20.6). Cross-tenant safe."},{"name":"environment","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"description":"Filter by api_keys.environment (v1.20.8). Cross-tenant safe.","title":"Environment"},"description":"Filter by api_keys.environment (v1.20.8). Cross-tenant safe."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/events/{event_id}":{"get":{"tags":["analytics"],"summary":"Get Usage Event","description":"v1.19.0 — single-event lookup for the call detail drill-down page.\n\nReturns 404 if the event isn't owned by the caller (no cross-tenant\nleak). Drill-down permalink uses the dashed UUID; a future enhancement\ncan accept the dash-stripped 8-char prefix for cleaner URLs.","operationId":"get_usage_event_v1_usage_events__event_id__get","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressionEvent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/latency-percentiles":{"get":{"tags":["usage"],"summary":"Latency Percentiles","description":"Return p50/p95/p99 of latency_ms for the caller's events in the window.","operationId":"latency_percentiles_v1_usage_latency_percentiles_get","parameters":[{"name":"window_hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Window Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatencyPercentilesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/profiles":{"get":{"tags":["profiles"],"summary":"List Profiles","description":"List all fidelity profiles for the authenticated user, newest first.","operationId":"list_profiles_v1_profiles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileListResponse"}}}}}},"post":{"tags":["profiles"],"summary":"Create Profile","description":"Create a new fidelity profile for the authenticated user.","operationId":"create_profile_v1_profiles_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/profiles/{profile_id}":{"get":{"tags":["profiles"],"summary":"Get Profile","description":"Get a specific fidelity profile by ID (must belong to the caller).","operationId":"get_profile_v1_profiles__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"integer","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["profiles"],"summary":"Update Profile","description":"Update a fidelity profile. Only fields present in the body are changed.","operationId":"update_profile_v1_profiles__profile_id__put","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"integer","title":"Profile Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["profiles"],"summary":"Delete Profile","description":"Delete a fidelity profile (must belong to the caller).","operationId":"delete_profile_v1_profiles__profile_id__delete","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"integer","title":"Profile Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/referrals/generate":{"post":{"tags":["referrals"],"summary":"Generate Referral Code","description":"Return the caller's referral code, creating one if it doesn't exist yet.\n\nIdempotent: calling this multiple times always returns the same code.","operationId":"generate_referral_code_v1_referrals_generate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateReferralResponse"}}}}}}},"/v1/referrals":{"get":{"tags":["referrals"],"summary":"List Referrals","description":"List all referrals created by the authenticated user.","operationId":"list_referrals_v1_referrals_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralListResponse"}}}}}}},"/v1/referrals/stats":{"get":{"tags":["referrals"],"summary":"Get Referral Stats","description":"Return aggregate referral stats for the authenticated user.","operationId":"get_referral_stats_v1_referrals_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralStatsResponse"}}}}}}},"/v1/referrals/claim":{"post":{"tags":["referrals"],"summary":"Claim Referral","description":"Manual fallback for claiming a referral code.\n\nThe primary auto-claim path runs inside the Clerk ``user.created`` webhook\n(``api/app/webhooks/clerk.py::_auto_claim_referral``), which fires whenever\nsignup metadata carries ``referral_code`` / ``ref``. This endpoint remains\nfor admin tools and for signup flows that do not pass the code through\nClerk metadata — callers must authenticate as the *referred* user.","operationId":"claim_referral_v1_referrals_claim_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimReferralRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimReferralResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects":{"get":{"tags":["projects"],"summary":"List Projects","description":"List all projects for the authenticated user, newest first.\n\nSelf-healing get-or-create: if the authenticated user has ZERO projects\n(new signup or migration-era gap), a Default project is auto-created before\nthe list is returned. This is idempotent and plan-agnostic — the Default\nproject is a system invariant required by the dashboard and Knowledge Hub.\n\nF22 (v1.22.2): each row includes ``current_period_compressions`` — the\ncount of usage events for the current calendar month attributed to that\nproject. Computed in ONE query (GROUP BY project_id) so we never do N+1\nlookups regardless of project count. Cap at LIMIT 100 via the existing\nordering; projects beyond 100 will not appear in the response.","operationId":"list_projects_v1_projects_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}}}},"post":{"tags":["projects"],"summary":"Create Project","description":"Create a new project for the authenticated user.\n\nRequires a plan that supports projects (team or enterprise).","operationId":"create_project_v1_projects_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}":{"get":{"tags":["projects"],"summary":"Get Project","description":"Get a specific project with aggregated usage stats.","operationId":"get_project_v1_projects__project_id__get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["projects"],"summary":"Update Project","description":"Update a project. Only fields present in the body are changed.","operationId":"update_project_v1_projects__project_id__put","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["projects"],"summary":"Delete Project","description":"Delete a project (must belong to the caller).","operationId":"delete_project_v1_projects__project_id__delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Project V1 Projects Project Id Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/payments/reconciliation":{"get":{"tags":["payments"],"summary":"Get Reconciliation","description":"Return payment-stamped usage_events for the date window.\n\nResponse shape:\n {\n \"events\": [\n {\n \"id\": \"\",\n \"user_id\": \"\",\n \"project_id\": \"\",\n \"facilitator\": \"nevermined\",\n \"settlement_status\": \"settled\",\n \"payment_id\": \"\",\n \"amount_charged_micros\": 12345,\n \"tokens_saved\": 8421,\n \"created_at\": \"2026-05-16T12:34:56Z\"\n },\n ...\n ],\n \"count\": ,\n \"window\": {\"from\": \"...\", \"to\": \"...\"}\n }\n\nUsed by ops + finance to reconcile gotcontext-side audit rows with the\nfacilitator's own ledger. Council Rule E: gotcontext holds NO funds —\nany drift between this surface and the facilitator's ledger is reported\nto the facilitator, not to gotcontext.","operationId":"get_reconciliation_v1_payments_reconciliation_get","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC start","title":"From"},"description":"ISO-8601 UTC start"},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC end","title":"To"},"description":"ISO-8601 UTC end"},{"name":"facilitator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to nevermined|skyfire|x402","title":"Facilitator"},"description":"Filter to nevermined|skyfire|x402"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items":{"post":{"tags":["knowledge"],"summary":"Ingest Item","description":"Ingest text or a URL into the project's Knowledge Hub.","operationId":"ingest_item_v1_projects__project_id__knowledge_items_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__app__routers__v1__knowledge__IngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["knowledge"],"summary":"List Items","description":"List Knowledge Hub items for the project (cursor-paginated).\n\nPhase 4 audit BLOCKER-1 fix: metadata_filter is plumbed through to the\nservice layer (was silently dropped in the initial Phase 4 build).","operationId":"list_items_v1_projects__project_id__knowledge_items_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"metadata_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON-encoded JSONB containment filter. URL-encode the JSON. Example: ?metadata_filter=%7B%22tag%22%3A%22alpha%22%7D for {\"tag\":\"alpha\"}.","title":"Metadata Filter"},"description":"JSON-encoded JSONB containment filter. URL-encode the JSON. Example: ?metadata_filter=%7B%22tag%22%3A%22alpha%22%7D for {\"tag\":\"alpha\"}."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListItemsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}":{"get":{"tags":["knowledge"],"summary":"Get Item","description":"Fetch a single Knowledge Hub item by ID.","operationId":"get_item_v1_projects__project_id__knowledge_items__item_id__get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["knowledge"],"summary":"Edit Item","description":"Replace item content with a new version, or rename/toggle without creating a new version.\n\nWhen only ``name`` is provided (no ``content``), updates the item name in-place\nwithout creating a new content version — ``current_version_id`` is unchanged.\n\nWhen ``content`` is provided, a new version is created (optimistic concurrency via\n``base_version_id``). ``name`` is also updated if provided.\n\nWhen only ``mcp_exposed`` is provided, toggles the per-source MCP-exposure flag\nwithout touching content or name.","operationId":"edit_item_v1_projects__project_id__knowledge_items__item_id__patch","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["knowledge"],"summary":"Delete Item","description":"Soft-delete a Knowledge Hub item.","operationId":"delete_item_v1_projects__project_id__knowledge_items__item_id__delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/query":{"post":{"tags":["knowledge"],"summary":"Query Items","description":"Vector search the project's Knowledge Hub chunks.","operationId":"query_items_v1_projects__project_id__knowledge_query_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/diff":{"get":{"tags":["knowledge"],"summary":"Diff Versions","description":"Compute a unified diff between two versions of a Knowledge Hub item.","operationId":"diff_versions_v1_projects__project_id__knowledge_items__item_id__diff_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"from_version_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"From Version Id"}},{"name":"to_version_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"To Version Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/uploads":{"post":{"tags":["knowledge"],"summary":"Issue Upload","description":"Issue a signed URL for a file upload. Idempotent on idempotency_key.","operationId":"issue_upload_v1_projects__project_id__knowledge_uploads_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueUploadRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/uploads/{upload_id}/complete":{"post":{"tags":["knowledge"],"summary":"Mark Upload Complete","description":"Notify the server that a file upload has completed.","operationId":"mark_upload_complete_v1_projects__project_id__knowledge_uploads__upload_id__complete_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Upload Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkUploadCompleteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadCompleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/reindex":{"post":{"tags":["knowledge"],"summary":"Reindex Item","description":"Re-trigger compression + embedding for an existing item's current version.\n\nUse when an item shows status='FAILED' (chunk_count == 0 despite having a\ncurrent_version_id). Returns 202 Accepted with the new version_id.\n\nThe caller must own the project (gated via _resolve_project_or_404 which\nreturns 404 for non-owner projects, same as all other KB endpoints).","operationId":"reindex_item_v1_projects__project_id__knowledge_items__item_id__reindex_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReindexResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/shares":{"get":{"tags":["shares"],"summary":"List Shares","description":"List outbound external shares for a project.\n\nOptional ``peer_id`` query param narrows to shares with one peer.","operationId":"list_shares_v1_projects__project_id__shares_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"peer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Peer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSharesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["shares"],"summary":"Create Share","description":"Grant (or refresh) an external A2A peer share for a KB item.","operationId":"create_share_v1_projects__project_id__shares_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantShareRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/shares/{share_id}":{"delete":{"tags":["shares"],"summary":"Delete Share","description":"Revoke an outbound share grant.","operationId":"delete_share_v1_projects__project_id__shares__share_id__delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Share Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/share-requests":{"get":{"tags":["shares"],"summary":"List Share Requests","description":"List inbound share requests for a project.\n\nOptional ``status`` query param filters by status (e.g. ``pending``).","operationId":"list_share_requests_v1_projects__project_id__share_requests_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListInboxResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/share-requests/{req_id}/decide":{"post":{"tags":["shares"],"summary":"Decide Share Request","description":"Approve or deny a pending inbound share request.\n\n``decision`` must be ``\"approve\"`` or ``\"deny\"``. On approval an outbound\n``kb_share_external`` row is created automatically if ``requested_resource``\nis a valid item UUID in the project.","operationId":"decide_share_request_v1_projects__project_id__share_requests__req_id__decide_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"req_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Req Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a2a/v1/share-requests":{"post":{"tags":["shares-a2a"],"summary":"Receive Inbound Share Request","description":"Accept an inbound A2A share request from an external peer.\n\nThe ``request_jws`` is verified against the peer's registered public key.\n``requested_at`` inside the JWS must be within ±5 minutes of server time.\n\nAll invalid / unverifiable requests return 400 ``{detail: \"invalid_request\"}``\nregardless of the failure reason (no peer-existence leakage).","operationId":"receive_inbound_share_request_a2a_v1_share_requests_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShareRequestPayload"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Receive Inbound Share Request A2A V1 Share Requests Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/governance/audit":{"get":{"tags":["governance"],"summary":"Get Audit Log","description":"Paginated audit log from kb_audit_events.","operationId":"get_audit_log_v1_governance_audit_get","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id"}},{"name":"item_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Item Id"}},{"name":"actor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor"}},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__app__routers__v1__governance__AuditLogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/governance/audit/export":{"get":{"tags":["governance"],"summary":"Export Audit Log","description":"Stream audit events as CSV.\n\nResponse has Content-Type: text/csv and Content-Disposition:\nattachment; filename=\"audit_log.csv\".","operationId":"export_audit_log_v1_governance_audit_export_get","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id"}},{"name":"item_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Item Id"}},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/governance/retention":{"get":{"tags":["governance"],"summary":"Get Project Retention","description":"Get the retention policy for a project.","operationId":"get_project_retention_v1_projects__project_id__governance_retention_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["governance"],"summary":"Set Project Retention","description":"Create or replace the retention policy for a project.","operationId":"set_project_retention_v1_projects__project_id__governance_retention_put","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["governance"],"summary":"Delete Project Retention","description":"Clear the retention policy for a project (no-limit semantics).","operationId":"delete_project_retention_v1_projects__project_id__governance_retention_delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/approvals":{"post":{"tags":["governance"],"summary":"Submit Approval","description":"Record an approval decision for a KB item.\n\nkb_approvals is append-only — to change a decision, submit a new one.\nThe item's status is updated atomically: 'approved' decision sets status\nto 'approved'; 'rejected' sets it to 'rejected'.","operationId":"submit_approval_v1_projects__project_id__knowledge_items__item_id__approvals_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDecisionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["governance"],"summary":"Get Approvals","description":"List approval history for a KB item, newest first.","operationId":"get_approvals_v1_projects__project_id__knowledge_items__item_id__approvals_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/status":{"patch":{"tags":["governance"],"summary":"Patch Item Status","description":"Transition a KB item's approval status.\n\nValid transitions:\n draft → in_review\n in_review → approved\n in_review → rejected\n rejected → in_review (resubmission)\n\nReturns 409 for invalid transitions; 404 if item not found.","operationId":"patch_item_status_v1_projects__project_id__knowledge_items__item_id__status_patch","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusTransitionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusTransitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/memberships":{"get":{"tags":["knowledge-memberships"],"summary":"List projects this item is shared to","description":"Return all non-owner projects that have membership access to this item.\n\nThe ``{project_id}`` in the URL MUST be the owner project of the item.\nCallers who own only a member project receive 404 (project not found)\nbecause ``_resolve_project_or_404`` returns 404 for un-owned projects.","operationId":"list_item_memberships_v1_projects__project_id__knowledge_items__item_id__memberships_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMembershipsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["knowledge-memberships"],"summary":"Add member projects to this item","description":"Grant one or more projects membership access to a KB item.\n\nIdempotent: project IDs already present are returned in ``skipped`` rather\nthan raising a 409.\n\nError shapes:\n- 404 ``item_not_found`` — item doesn't exist or is soft-deleted in this project\n- 400 ``self_membership`` — project_ids contains the owner project itself\n- 404 ``member_project_not_found`` — a target project_id doesn't exist\n- 400 ``cap_exceeded`` — item would exceed 100 member-project limit","operationId":"add_item_memberships_v1_projects__project_id__knowledge_items__item_id__memberships_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMembershipsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMembershipsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/memberships/{member_project_id}":{"delete":{"tags":["knowledge-memberships"],"summary":"Remove a member project from this item","description":"Remove a single project's membership access from a KB item.\n\nOnly the owner project can remove memberships. A member project removing\nitself from an item it doesn't own should use the same endpoint — the\nowner-check at ``_resolve_project_or_404`` will return 404.\n\nError shapes:\n- 404 ``membership_not_found`` — the membership row does not exist","operationId":"remove_item_membership_v1_projects__project_id__knowledge_items__item_id__memberships__member_project_id__delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"member_project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Member Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveMembershipResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/visibility":{"patch":{"tags":["knowledge"],"summary":"Update item visibility","description":"Set the visibility level for a KB item. 'org' and 'external' values return **501** until Clerk org webhook integration lands in v1.39.","operationId":"patch_item_visibility_v1_projects__project_id__knowledge_items__item_id__visibility_patch","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Patch Item Visibility V1 Projects Project Id Knowledge Items Item Id Visibility Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/items/{item_id}/classification":{"patch":{"tags":["knowledge"],"summary":"Update item classification","description":"Set the sensitivity classification level for a KB item.","operationId":"patch_item_classification_v1_projects__project_id__knowledge_items__item_id__classification_patch","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Patch Item Classification V1 Projects Project Id Knowledge Items Item Id Classification Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/knowledge/policy":{"get":{"tags":["knowledge"],"summary":"Get classification policy","description":"Return the project's classification policy. If no policy has been set, returns the permissive default (all four levels allowed, default='internal', required=false).","operationId":"get_classification_policy_v1_projects__project_id__knowledge_policy_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationPolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["knowledge"],"summary":"Create or replace classification policy","description":"Upsert the classification policy for a project. Only the project owner may configure this. ``default_classification`` must be present in ``allowed_classifications``.","operationId":"put_classification_policy_v1_projects__project_id__knowledge_policy_put","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationPolicyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationPolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kb/items":{"post":{"tags":["knowledge-hub"],"summary":"Ingest text or URL into the Knowledge Hub","description":"Ingest text or a URL into the project's Knowledge Hub.\n\nThe project is resolved from the gc_ API key binding. Mirrors ``gc_kb_ingest``.","operationId":"kb_ingest_v1_kb_items_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbIngestRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["knowledge-hub"],"summary":"List Knowledge Hub items (cursor-paginated)","description":"List all non-deleted KB items for the project bound to this API key.\n\nMirrors ``gc_kb_list``.","operationId":"kb_list_items_v1_kb_items_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from previous response.","title":"Cursor"},"description":"Opaque cursor from previous response."},{"name":"metadata_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON-encoded JSONB containment filter. URL-encode the JSON. Example: ?metadata_filter=%7B%22tag%22%3A%22alpha%22%7D for {\"tag\":\"alpha\"}.","title":"Metadata Filter"},"description":"JSON-encoded JSONB containment filter. URL-encode the JSON. Example: ?metadata_filter=%7B%22tag%22%3A%22alpha%22%7D for {\"tag\":\"alpha\"}."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kb/items/{item_id}":{"get":{"tags":["knowledge-hub"],"summary":"Fetch a single Knowledge Hub item","description":"Fetch metadata for a single KB item by its UUID.\n\nMirrors ``gc_kb_get``.","operationId":"kb_get_item_v1_kb_items__item_id__get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["knowledge-hub"],"summary":"Edit a Knowledge Hub item (optimistic concurrency)","description":"Replace item content, creating a new version.\n\nPass ``base_version_id`` equal to the current version UUID. On stale\n``base_version_id``, returns 409 with ``current_version_id`` so the caller\ncan retry with the fresh id. Mirrors ``gc_kb_edit``.","operationId":"kb_edit_item_v1_kb_items__item_id__patch","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbEditRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbEditResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["knowledge-hub"],"summary":"Soft-delete a Knowledge Hub item","description":"Soft-delete a KB item.\n\nThe item is marked deleted and excluded from queries / listings, but data\nis retained for audit purposes. Returns 204 No Content on success.\nMirrors ``gc_kb_delete``.","operationId":"kb_delete_item_v1_kb_items__item_id__delete","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kb/items/{item_id}/versions":{"get":{"tags":["knowledge-hub"],"summary":"List version history for a Knowledge Hub item","description":"Return the full version history for a KB item.\n\nEach entry includes the diff between consecutive versions (from_version_id,\nto_version_id, unified_diff). Mirrors ``gc_kb_diff`` iterated over all\nversion pairs.","operationId":"kb_list_versions_v1_kb_items__item_id__versions_get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbVersionsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kb/query":{"post":{"tags":["knowledge-hub"],"summary":"Semantic + BM25 hybrid search of Knowledge Hub chunks","description":"Vector-search the project's Knowledge Hub.\n\nReturns the top-k semantically similar chunks with source item IDs, scores,\nand optional raw text. Mirrors ``gc_kb_query``.","operationId":"kb_query_v1_kb_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbQueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbQueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/context/frameworks":{"get":{"tags":["context_hub"],"summary":"List Frameworks","description":"Return all supported frameworks in the Agent Context Hub.","operationId":"list_frameworks_api_context_frameworks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrameworkListResponse"}}}}}}},"/api/context/frameworks/{slug}":{"get":{"tags":["context_hub"],"summary":"Get Framework","description":"Return a single framework by slug.","operationId":"get_framework_api_context_frameworks__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrameworkResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/context/frameworks/{slug}/ingest":{"post":{"tags":["context_hub"],"summary":"Ingest Framework Endpoint","description":"Trigger doc ingestion for a single framework (admin only).\n\nFetches the framework's docs_url, chunks the content, embeds it, and\nstores the chunks in the system KnowledgeBase so gc_lookup can retrieve\nthem.","operationId":"ingest_framework_endpoint_api_context_frameworks__slug__ingest_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__app__routers__v1__context_hub__IngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/usage":{"get":{"tags":["projects-finops"],"summary":"Get Project Usage","description":"Return usage statistics for a project scoped to the current calendar month.\n\nOnly events with ``usage_events.project_id = project_id`` are included.\nHistorical events (pre-v1.22.0, before keys were bound) show up as\n``project_id=NULL`` in the global /v1/usage rollup but never here — the\nproject-specific view is forward-looking.\n\nF22 (v1.22.2): response now includes ``plan``, ``compressions_limit``, and\n``models`` so the per-project page can render Model Mix + plan-aware UI\nwithout an extra /v1/usage round-trip.","operationId":"get_project_usage_v1_projects__project_id__usage_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/budget":{"get":{"tags":["projects-finops"],"summary":"Get Project Budget","description":"Return the current budget configuration for a project.\n\nReturns 404 when no budget has been set (use PUT to create one).","operationId":"get_project_budget_v1_projects__project_id__budget_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["projects-finops"],"summary":"Upsert Project Budget","description":"Create or replace the budget configuration for a project.\n\nIdempotent — calling PUT again with different values replaces the budget.\nSetting a new budget does NOT reset ``last_alerted_threshold`` (the cron\nsweep compares against the budget in the same period; a manual update mid-\nperiod keeps the dedup state intact).","operationId":"upsert_project_budget_v1_projects__project_id__budget_put","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetConfig"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["projects-finops"],"summary":"Delete Project Budget","description":"Remove the budget configuration for a project (alerts disabled).\n\nReturns 404 when no budget exists. Does not affect the project itself or\nits usage history.","operationId":"delete_project_budget_v1_projects__project_id__budget_delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Project Budget V1 Projects Project Id Budget Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/tool-allowlist":{"get":{"tags":["projects-finops"],"summary":"Get Project Tool Allowlist","description":"Return the current tool allowlist for a project.\n\n``tool_allowlist: null`` means no filter is active — the project uses the\nplan/profile default tool surface. A non-null list means only those tools\n(intersected with the plan/profile allowlist) are available to agents\nconnecting with this project's gc_ key.","operationId":"get_project_tool_allowlist_v1_projects__project_id__tool_allowlist_get","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolAllowlistResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["projects-finops"],"summary":"Set Project Tool Allowlist","description":"Set the tool allowlist for a project.\n\nPro+ only — Free tier users get the 17-tool surface by plan default and\ncannot customise per-project allowlists.\n\nThe allowlist is intersected with the plan/profile allowlist at gateway\ntime — setting a tool that your plan doesn't include has no effect.","operationId":"set_project_tool_allowlist_v1_projects__project_id__tool_allowlist_put","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolAllowlistBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolAllowlistResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["projects-finops"],"summary":"Delete Project Tool Allowlist","description":"Reset the tool allowlist to NULL (plan/profile default).\n\nAfter this call, agents connecting with this project's gc_ key see the\nfull plan/profile tool surface rather than a project-scoped subset.","operationId":"delete_project_tool_allowlist_v1_projects__project_id__tool_allowlist_delete","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Project Tool Allowlist V1 Projects Project Id Tool Allowlist Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/projects/{project_id}/tool-allowlist/apply-starter":{"post":{"tags":["projects-finops"],"summary":"Apply Starter Tool Allowlist","description":"Apply the recommended 25-tool starter set as the project's allowlist.\n\nConvenience endpoint — equivalent to PUT with the curated list. Idempotent.\nPro+ only.","operationId":"apply_starter_tool_allowlist_v1_projects__project_id__tool_allowlist_apply_starter_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolAllowlistResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/runs":{"post":{"tags":["benchmarks"],"summary":"Submit Benchmark Run","description":"Submit a new AI inference benchmark measurement.\n\nAuth (precedence: Bearer first, then Turnstile):\n1. ``Authorization: Bearer gc_`` — preferred path (20 runs/hour).\n The global ``AuthMiddleware`` resolves the bearer token and sets\n ``request.state.user_id``; if a valid bearer is presented, this handler\n attributes the submission to that user and skips the Turnstile check.\n2. Anonymous via Cloudflare Turnstile (5 runs/hour per IP) — supply EITHER:\n - ``cf-turnstile-response`` request header (preferred), or\n - ``cf_turnstile_response`` field in the JSON body (fallback for\n clients that cannot set arbitrary headers).\n The header takes precedence when both are supplied. The token is\n verified against Cloudflare's siteverify endpoint\n (``TURNSTILE_SECRET`` env var). When ``TURNSTILE_SECRET`` is unset the\n service accepts only Cloudflare's dev-sentinel token.\n\nDev escape: ``TURNSTILE_DEV_BYPASS=1`` (env var) skips Turnstile\nverification for anonymous submissions. Local-dev only — never enable in\nproduction.\n\nOn missing auth (neither Bearer nor Turnstile token): HTTP 401 with a\ndetail message naming both options.","operationId":"submit_benchmark_run_v1_benchmarks_runs_post","parameters":[{"name":"cf-turnstile-response","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cf-Turnstile-Response"}},{"name":"x-submitted-by-agent","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Submitted-By-Agent"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRunCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/runs/{id_or_slug}":{"get":{"tags":["benchmarks"],"summary":"Get Benchmark Run","description":"Fetch a single benchmark run by UUID or public_slug.\n\nNo auth required. Cache-Control: public, max-age=300.","operationId":"get_benchmark_run_v1_benchmarks_runs__id_or_slug__get","parameters":[{"name":"id_or_slug","in":"path","required":true,"schema":{"type":"string","title":"Id Or Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/leaderboard":{"get":{"tags":["benchmarks"],"summary":"Get Leaderboard","description":"Multi-axis leaderboard with cursor pagination.\n\nLenses:\n- ``tokens_per_sec``: raw output speed (default)\n- ``tokens_per_sec_per_dollar``: efficiency per $/Mtok (model price lookup)\n- ``tokens_per_sec_per_watt``: efficiency per TDP watt (from hardware metadata)\n- ``value_composite``: ``(tps * verified_boost) / sqrt(price_per_mtok)``","operationId":"get_leaderboard_v1_benchmarks_leaderboard_get","parameters":[{"name":"model_text","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by model","title":"Model Text"},"description":"Filter by model"},{"name":"hardware_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by hardware SKU","title":"Hardware Id"},"description":"Filter by hardware SKU"},{"name":"hardware_class","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by hardware class — one of ['amd_rocm', 'apple_silicon', 'cpu_only', 'intel_arc', 'nvidia_cuda', 'other']","title":"Hardware Class"},"description":"Filter by hardware class — one of ['amd_rocm', 'apple_silicon', 'cpu_only', 'intel_arc', 'nvidia_cuda', 'other']"},{"name":"lens","in":"query","required":false,"schema":{"type":"string","description":"Ranking lens","default":"tokens_per_sec","title":"Lens"},"description":"Ranking lens"},{"name":"verified_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only show verified runs","default":false,"title":"Verified Only"},"description":"Only show verified runs"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor (opaque base64)","title":"Cursor"},"description":"Pagination cursor (opaque base64)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/runs/{run_id}/flag":{"post":{"tags":["benchmarks"],"summary":"Flag Benchmark Run","description":"Flag a benchmark run for review (requires gc_ key auth).\n\nIdempotent per (run_id, flagger_user_id). When flag_count reaches 3\nthe run is automatically set to verified_status='flagged'.","operationId":"flag_benchmark_run_v1_benchmarks_runs__run_id__flag_post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Flag Benchmark Run V1 Benchmarks Runs Run Id Flag Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/hardware":{"get":{"tags":["benchmarks"],"summary":"List Hardware","description":"List hardware SKUs ordered by canonical then vendor+model.","operationId":"list_hardware_v1_benchmarks_hardware_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Substring search on vendor+model","title":"Q"},"description":"Substring search on vendor+model"},{"name":"canonical_only","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Canonical Only"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HardwareResponse"},"title":"Response List Hardware V1 Benchmarks Hardware Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["benchmarks"],"summary":"Create Hardware","description":"Submit a new hardware SKU (user-submitted, canonical=False).\n\nIdempotent on (vendor_text, model_text) — returns the existing row\nif already present.\n\nRequires gc_ key auth.","operationId":"create_hardware_v1_benchmarks_hardware_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardwareCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardwareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/hardware/{hardware_id}/promote":{"post":{"tags":["benchmarks"],"summary":"Promote Hardware","description":"Mark a user-submitted hardware SKU as canonical (admin only).\n\nIdempotent: if the row is already canonical, returns 200 with a message.\nConflict (409): if another row is already canonical for the same\n(vendor_text, model_text) pair.","operationId":"promote_hardware_v1_benchmarks_hardware__hardware_id__promote_post","parameters":[{"name":"hardware_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Hardware Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["benchmarks"],"summary":"Revoke Hardware Canonical","description":"Revoke the canonical flag from a hardware SKU (admin only).\n\nRare — used to clean up erroneous promotions. Idempotent when already\nnon-canonical.","operationId":"revoke_hardware_canonical_v1_benchmarks_hardware__hardware_id__promote_delete","parameters":[{"name":"hardware_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Hardware Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/runs/{run_id}/comments":{"post":{"tags":["benchmarks"],"summary":"Post Benchmark Comment","description":"Submit a comment on a benchmark run.\n\nRequires authentication (gc_ key or Clerk JWT). Comment is classified\ninline by the AI moderation layer and returns its resolved status:\n - approved : visible to everyone immediately\n - pending : awaiting final classification (transient — rare)\n - needs_review: flagged for human moderator review\n - rejected : content policy violation (hidden)\n\nThe caller can poll GET /comments to see the current visibility state.","operationId":"post_benchmark_comment_v1_benchmarks_runs__run_id__comments_post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentCreateRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["benchmarks"],"summary":"List Benchmark Comments","description":"List threaded comments for a benchmark run.\n\nPublic endpoint (no auth required for approved comments).\nAuthenticated callers also see their own pending/needs_review comments.\nRejected comments are never returned.","operationId":"list_benchmark_comments_v1_benchmarks_runs__run_id__comments_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/runs/{run_id}/percentile":{"get":{"tags":["benchmarks"],"summary":"Get Benchmark Run Percentile","description":"Return percentile context for a run's metric value.\n\nUses a fallback hierarchy per council D3:\n 1. Exact config distribution (same model × hardware × quant)\n 2. Model/hardware tier distribution\n 3. All-results distribution\n\nReturns null when insufficient data exists (<5 results at any tier).\n\nThe ``metric_value`` query parameter is optional — when omitted the\nhandler looks up the run's own stored value.","operationId":"get_benchmark_run_percentile_v1_benchmarks_runs__run_id__percentile_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"metric_name","in":"query","required":false,"schema":{"type":"string","default":"tokens_per_sec_output","title":"Metric Name"}},{"name":"metric_value","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Metric Value"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PercentileResponse"},{"type":"null"}],"title":"Response Get Benchmark Run Percentile V1 Benchmarks Runs Run Id Percentile Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/moderation-queue":{"get":{"tags":["benchmarks"],"summary":"Get Moderation Queue","description":"Admin: list benchmark comments awaiting human review (status=needs_review).\n\nReturns comments in chronological order (oldest first — work through\nthe queue FIFO to minimise comment authors waiting).","operationId":"get_moderation_queue_v1_benchmarks_moderation_queue_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationQueueResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/benchmarks/comments/{comment_id}/moderate":{"post":{"tags":["benchmarks"],"summary":"Moderate Benchmark Comment","description":"Admin: approve or reject a needs_review benchmark comment.\n\naction: \"approve\" | \"reject\"\n\nSets status to \"approved\" or \"rejected\" respectively. Only callable\nby admins (ADMIN_USER_IDS / ADMIN_EMAILS / @gotcontext.ai suffix).","operationId":"moderate_benchmark_comment_v1_benchmarks_comments__comment_id__moderate_post","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/items":{"post":{"tags":["news-admin"],"summary":"Ingest News Items","description":"Idempotent ingest of raw news items from n8n.\n\nAccepts either a single item or a batch (``{items: [...]}``).\n\nDedup via UNIQUE(source_slug, external_id) — same item submitted twice\nappears in ``duplicates``, not ``created``. The caller's ``gc_`` key\nmust resolve to an admin user (ADMIN_USER_IDS / ADMIN_EMAILS / @gotcontext.ai).\n\nv1.34.18 — validates that source_slug exists in news_sources with active=true\nbefore accepting the ingest payload. Rejects with 422 + error:\n\"unknown_source_slug\" if not. Prevents phantom source slugs from polluting\nthe news_items table (e.g. 'smoketest' from automated testing).","operationId":"ingest_news_items_v1_news_items_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SingleItemIngestRequest"},{"$ref":"#/components/schemas/BatchItemIngestRequest"}],"title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__app__routers__v1__news_admin__IngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/articles":{"post":{"tags":["news-admin"],"summary":"Publish News Article","description":"Publish a news article from n8n after Telegram approval.\n\nAuto-generates a slug from ``title`` if ``slug`` is not provided.\nReturns 409 on explicit slug collision so the caller can retry with a\ndifferent slug.\n\nWrites one ``news_article_revisions`` row with ``change_kind='created'``.","operationId":"publish_news_article_v1_news_articles_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishArticleRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/articles/{article_id}":{"patch":{"tags":["news-admin"],"summary":"Edit News Article","description":"Edit an existing article.\n\nAccepted fields: title, body_md, category, hero_image_url, excerpt,\nsource_url, source_attribution, status, metadata.\n\nWrites one ``news_article_revisions`` row with ``change_kind='edited'``.","operationId":"edit_news_article_v1_news_articles__article_id__patch","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditArticleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditArticleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/articles/{article_id}/withdraw":{"post":{"tags":["news-admin"],"summary":"Withdraw News Article","description":"Withdraw an article (DMCA or other takedown).\n\nSets ``status='withdrawn'`` on the article.\nWrites one revision with ``change_kind='dmca_withdrawn'`` (when ``dmca=True``)\nor ``change_kind='withdrawn'`` (otherwise).\n\nWithdrawn articles return 410 on the public GET /v1/news/{slug} endpoint.","operationId":"withdraw_news_article_v1_news_articles__article_id__withdraw_post","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/admin/drafts":{"get":{"tags":["news-drafts"],"summary":"List Draft Items","description":"List news_items by draft_status (admin only).\n\nDefault: status=drafted (pending approval).\nAllowed values: undrafted, drafting, drafted, approved, rejected, published.\n\nEmpty list when no items match — never raises 404.","operationId":"list_draft_items_v1_news_admin_drafts_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Filter by draft_status","default":"drafted","title":"Status"},"description":"Filter by draft_status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Max results","default":50,"title":"Limit"},"description":"Max results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DraftItemResponse"},"title":"Response List Draft Items V1 News Admin Drafts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/admin/drafts/{item_id}":{"patch":{"tags":["news-drafts"],"summary":"Patch Draft Item","description":"Edit draft fields before approve.\n\nRe-runs Tier-1 kill-word and forbidden-pattern check. Returns 400 if\nany kill word or pattern is found in the patched content — surface this\nin the UI with the exact word/pattern that triggered the rejection.\n\nAccepted fields: draft_title, draft_body_md, draft_excerpt, draft_category.","operationId":"patch_draft_item_v1_news_admin_drafts__item_id__patch","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDraftRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDraftResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/admin/drafts/{item_id}/approve":{"post":{"tags":["news-drafts"],"summary":"Approve Draft Item","description":"Promote a draft to a published news_articles row.\n\nInternally calls the existing publish_article helper (DRY) and fills the\npublished_article_id FK back on the news_items row.\n\nReturns 404 if item not found.\nReturns 409 if item is not in 'drafted' status.","operationId":"approve_draft_item_v1_news_admin_drafts__item_id__approve_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/admin/drafts/{item_id}/reject":{"post":{"tags":["news-drafts"],"summary":"Reject Draft Item","description":"Manually reject a draft with a reason.\n\nPreserves the news_items row for provenance; does not delete anything.\nReturns 404 if item not found.","operationId":"reject_draft_item_v1_news_admin_drafts__item_id__reject_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/categories":{"get":{"tags":["news"],"summary":"Get News Categories","description":"Return distinct published categories with article counts.\n\nExample response::\n\n [\n {\"category\": \"Models\", \"count\": 14},\n {\"category\": \"Tools\", \"count\": 9}\n ]","operationId":"get_news_categories_v1_news_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NewsCategoryItem"},"type":"array","title":"Response Get News Categories V1 News Categories Get"}}}}}}},"/v1/news":{"get":{"tags":["news"],"summary":"List News Articles","description":"Return paginated published articles, newest-first.\n\nCursor-based pagination: the ``next_cursor`` value from one response is\npassed as ``cursor`` on the next request. When ``next_cursor`` is null,\nthere are no more pages.\n\nOnly ``status='published'`` articles are returned.","operationId":"list_news_articles_v1_news_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by category","title":"Category"},"description":"Filter by category"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size","default":20,"title":"Limit"},"description":"Page size"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor","title":"Cursor"},"description":"Opaque pagination cursor"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/subscribe":{"post":{"tags":["news"],"summary":"Subscribe To Newsletter","description":"Capture an email for the /news weekly digest.\n\nSingle-opt-in per council 2/3 vote. CAN-SPAM compliant via the existing\n/v1/unsubscribe one-click flow.\n\nStatus codes:\n 200 — email captured (or honeypot triggered — silent success)\n 400 — invalid source value\n 422 — invalid email (Pydantic EmailStr validation)","operationId":"subscribe_to_newsletter_v1_news_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSubscribeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSubscribeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/news/{slug}":{"get":{"tags":["news"],"summary":"Get News Article","description":"Return full article by slug.\n\nStatus codes:\n 200 — article found and published\n 404 — slug not found ({detail, error: \"not_found\"})\n 410 — article withdrawn / DMCA ({detail, error: \"withdrawn\"})","operationId":"get_news_article_v1_news__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsArticleDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feed":{"get":{"tags":["feed"],"summary":"Read Feed","description":"Return a keyset-paginated page of the unified community feed.\n\n``sort`` = hot | new | top (default hot); ``filter`` = all | news | blog |\nbenchmark. ``user_vote`` is attached per item when the request carries a\nvalid Bearer token.","operationId":"read_feed_v1_feed_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"hot","title":"Sort"}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Filter"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feed/vote":{"post":{"tags":["feed"],"summary":"Cast Vote","description":"Cast (+1/-1) or retract (0) a vote on a feed item. Auth required.","operationId":"cast_vote_v1_feed_vote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feed/items/{item_id}/comments":{"post":{"tags":["feed"],"summary":"Post Comment","description":"Add a top-level or reply comment to a feed item. Auth required.","operationId":"post_comment_v1_feed_items__item_id__comments_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["feed"],"summary":"List Comments","description":"Return a flat, thread-ordered comment list for a feed item. Public.","operationId":"list_comments_v1_feed_items__item_id__comments_get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentsPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feed/comments/{comment_id}":{"patch":{"tags":["feed"],"summary":"Patch Comment","description":"Edit the body of the caller's own comment (Forum slice 3). Auth required.","operationId":"patch_comment_v1_feed_comments__comment_id__patch","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditCommentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["feed"],"summary":"Remove Comment","description":"Soft-delete the caller's own comment (Forum slice 4). Auth required.","operationId":"remove_comment_v1_feed_comments__comment_id__delete","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feed/comments/{comment_id}/report":{"post":{"tags":["feed"],"summary":"Report Comment","description":"File a content report on a comment. Auth required. Idempotent per (reporter, comment).","operationId":"report_comment_v1_feed_comments__comment_id__report_post","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCommentRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Report Comment V1 Feed Comments Comment Id Report Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/users/{username}/follow":{"post":{"tags":["follows"],"summary":"Follow","description":"Follow the user identified by ``username``.\n\nIdempotent — a second call for an existing follow is a no-op.\nReturns ``{ok: true}`` on success.\nRejects self-follow with 400.\nRejects unknown username with 404.","operationId":"follow_v1_users__username__follow_post","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Follow V1 Users Username Follow Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["follows"],"summary":"Unfollow","description":"Unfollow the user identified by ``username``.\n\nNo-op if the relationship does not exist.\nReturns ``{ok: true}`` on success.\nRejects self-unfollow with 400.\nRejects unknown username with 404.","operationId":"unfollow_v1_users__username__follow_delete","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Unfollow V1 Users Username Follow Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/users/{username}/follow-status":{"get":{"tags":["follows"],"summary":"Follow Status","description":"Return follow relationship status + counts for the target user.\n\n``following`` is False when the request is unauthenticated.\nReturns 404 if ``username`` is not found.","operationId":"follow_status_v1_users__username__follow_status_get","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","title":"Username"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/content/report":{"post":{"tags":["moderation"],"summary":"Report Content","description":"Flag any content for moderation review.\n\nAuth required. Idempotent per (reporter, target_type, target_id).\nSilenced users receive 403.\n\nReturns ``{id, status, created_at}`` -- matches the existing\n``POST /v1/feed/comments/{id}/report`` response shape.","operationId":"report_content_v1_content_report_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentReportRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Report Content V1 Content Report Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-queue":{"post":{"tags":["batch-queue"],"summary":"Create Batch Queue Job","description":"Create a new batch compression job.\n\nAccepts up to 200 items.\n\n**Small jobs (≤ 5 items):** processed inline and return HTTP 200 with\n``status=\"completed\"`` immediately.\n\n**Large jobs (> 5 items):** queued asynchronously and return HTTP 202\nwith ``status=\"queued\"``. The `/v1/cron/batch-queue-sweep` endpoint\npicks up any large job that gets interrupted (e.g. Fly auto-suspend)\nand reprocesses it within the next cron cycle (≤ 5 min delay).","operationId":"create_batch_queue_job_v1_batch_queue_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQueueRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQueueCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["batch-queue"],"summary":"List Batch Queue Jobs","description":"List the authenticated user's batch queue jobs, newest first.","operationId":"list_batch_queue_jobs_v1_batch_queue_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQueueListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-queue/stream":{"get":{"tags":["batch-queue"],"summary":"Stream Batch Jobs","description":"SSE endpoint for real-time batch job status updates.\n\nEmits:\n * ``init`` — one-shot snapshot of the user's latest 50 jobs on connect\n * ``job.updated`` — whenever a job row's serialized form changes between polls\n * ``job.removed`` — whenever a previously-seen job falls out of the snapshot\n * ``heartbeat`` — approximately every 15s (keeps proxies from dropping the connection)\n\nUpstash Redis is REST-only (no pubsub), so we poll the jobs table at\n``_STREAM_POLL_SECONDS`` intervals and diff snapshots in-memory. One extra\nDB read per active connection per second is cheap on Supabase and works\nacross any number of Fly instances.\n\nRequires ``Authorization: Bearer `` (standard auth\nmiddleware populates ``request.state.user_id``).","operationId":"stream_batch_jobs_v1_batch_queue_stream_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/batch-queue/{job_id}":{"get":{"tags":["batch-queue"],"summary":"Get Batch Queue Job","description":"Get the status of a specific batch queue job.","operationId":"get_batch_queue_job_v1_batch_queue__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQueueJobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-queue/{job_id}/results":{"get":{"tags":["batch-queue"],"summary":"Get Batch Queue Results","description":"Get all items and their compressed results for a batch job.","operationId":"get_batch_queue_results_v1_batch_queue__job_id__results_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchQueueResultsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/summary":{"get":{"tags":["analytics"],"summary":"Analytics Summary","description":"Per-project compression summary with an 'Unassigned' bucket for\nevents that have no project_id.\n\n``days`` (optional, 1–365): when provided, filters to the trailing\n``days``-day window. When omitted, returns a lifetime aggregate so\nexisting API consumers see no breaking change.","operationId":"analytics_summary_v1_analytics_summary_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummary"},"title":"Response Analytics Summary V1 Analytics Summary Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/trends":{"get":{"tags":["analytics"],"summary":"Analytics Trends","description":"Aggregate compression events by date bucket.","operationId":"analytics_trends_v1_analytics_trends_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(daily|weekly)$","default":"daily","title":"Period"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":7,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TrendPoint"},"title":"Response Analytics Trends V1 Analytics Trends Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/export":{"get":{"tags":["analytics"],"summary":"Analytics Export","description":"Export the last 90 days of usage events as a CSV download.","operationId":"analytics_export_v1_analytics_export_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/savings":{"get":{"tags":["analytics"],"summary":"Get Savings","description":"Cumulative all-time savings. ``?model=`` sets the rate for the\n``estimated_cost_saved_usd`` field and is echoed back in ``model``.","operationId":"get_savings_v1_savings_get","parameters":[{"name":"model","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Canonical model name for cost estimation (e.g. ``claude-sonnet-4.6``, ``claude-opus-4.6``, ``gpt-5.4``, ``gemini-3.1-pro-preview``). Unknown models fall back to a blended default. If omitted, the blended default is used.","title":"Model"},"description":"Canonical model name for cost estimation (e.g. ``claude-sonnet-4.6``, ``claude-opus-4.6``, ``gpt-5.4``, ``gemini-3.1-pro-preview``). Unknown models fall back to a blended default. If omitted, the blended default is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/settings/semantic-cache-threshold":{"get":{"tags":["settings"],"summary":"Get Threshold","operationId":"get_threshold_v1_settings_semantic_cache_threshold_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThresholdResponse"}}}}}},"put":{"tags":["settings"],"summary":"Put Threshold","operationId":"put_threshold_v1_settings_semantic_cache_threshold_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThresholdPutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThresholdResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/global-savings":{"get":{"tags":["analytics"],"summary":"Global Savings","description":"Return aggregate compression savings across the whole platform.","operationId":"global_savings_v1_global_savings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Global Savings V1 Global Savings Get"}}}}}}},"/v1/teams":{"get":{"tags":["teams"],"summary":"List Teams","description":"List teams where the caller is a member or has a pending invite.","operationId":"list_teams_v1_teams_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamListResponse"}}}}}},"post":{"tags":["teams"],"summary":"Create Team","description":"Create a team and auto-add the caller as its owner.","operationId":"create_team_v1_teams_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTeamRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamWithMembershipResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/invites":{"post":{"tags":["teams"],"summary":"Invite Team Member","description":"Invite a member to a team by email and send a Resend email.","operationId":"invite_team_member_v1_teams__team_id__invites_post","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteTeamMemberRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamInviteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/members":{"get":{"tags":["teams"],"summary":"Get Team Members","description":"Return the full member roster for any active team member.","operationId":"get_team_members_v1_teams__team_id__members_get","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamMembersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/accept":{"post":{"tags":["teams"],"summary":"Accept Team Invite","description":"Accept the caller's pending invite for the requested team.","operationId":"accept_team_invite_v1_teams__team_id__accept_post","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptTeamInviteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/invites/{invite_id}":{"delete":{"tags":["teams"],"summary":"Revoke Team Invite","description":"Revoke a pending team invite.","operationId":"revoke_team_invite_v1_teams__team_id__invites__invite_id__delete","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/members/{member_user_id}":{"delete":{"tags":["teams"],"summary":"Remove Team Member","description":"Remove a user from a team.","operationId":"remove_team_member_v1_teams__team_id__members__member_user_id__delete","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}},{"name":"member_user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Member User Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/transfer":{"post":{"tags":["teams"],"summary":"Transfer Team Ownership","description":"Transfer team ownership to an existing active member.","operationId":"transfer_team_ownership_v1_teams__team_id__transfer_post","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferTeamOwnershipRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamTransferResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/members/{member_user_id}/role":{"patch":{"tags":["teams"],"summary":"Change Member Role","description":"Change the role of an active team member.","operationId":"change_member_role_v1_teams__team_id__members__member_user_id__role_patch","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}},{"name":"member_user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Member User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRoleRequest"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/invites/{invite_id}/resend":{"post":{"tags":["teams"],"summary":"Resend Team Invite","description":"Re-send the invite email for a pending team invite.","operationId":"resend_team_invite_v1_teams__team_id__invites__invite_id__resend_post","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/activity":{"get":{"tags":["teams"],"summary":"Get Team Activity","description":"Return the paginated audit log for a team (owners and admins only).","operationId":"get_team_activity_v1_teams__team_id__activity_get","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamActivityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/teams/{team_id}/usage":{"get":{"tags":["teams"],"summary":"Get Team Usage","description":"Return team-wide usage aggregates for owners and admins.","operationId":"get_team_usage_v1_teams__team_id__usage_get","parameters":[{"name":"team_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Team Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List Webhooks","description":"List the caller's configured webhooks (active + inactive; excludes soft-deleted).","operationId":"list_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}}}},"post":{"tags":["webhooks"],"summary":"Create Webhook","description":"Create a webhook owned by the authenticated user.","operationId":"create_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}":{"delete":{"tags":["webhooks"],"summary":"Delete Webhook","description":"Soft-delete one of the caller's webhooks.\n\nSets deleted_at to now() instead of a hard DELETE. The row is hidden\nfrom list responses and ignored by the delivery service. Recoverable\nvia POST /v1/webhooks/{id}/recover within 30 days.","operationId":"delete_webhook_v1_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/toggle":{"patch":{"tags":["webhooks"],"summary":"Toggle Webhook","description":"Toggle the enabled/disabled state of one of the caller's webhooks.","operationId":"toggle_webhook_v1_webhooks__webhook_id__toggle_patch","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/recover":{"post":{"tags":["webhooks"],"summary":"Recover Webhook","description":"Recover a soft-deleted webhook within 30 days of deletion.","operationId":"recover_webhook_v1_webhooks__webhook_id__recover_post","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/test":{"post":{"tags":["webhooks"],"summary":"Test Webhook","description":"Deliver a synchronous test ping to a webhook.","operationId":"test_webhook_v1_webhooks__webhook_id__test_post","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["webhooks"],"summary":"Get Webhook Deliveries","description":"Return paginated delivery history for an owned webhook.","operationId":"get_webhook_deliveries_v1_webhooks__webhook_id__deliveries_get","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveriesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/filter-cli":{"post":{"tags":["compression"],"summary":"Filter Cli","description":"Filter and compress CLI output.\n\nAutomatically detects the command type (git diff, pytest, npm install, etc.)\nand applies type-specific compression. Typical savings: 80-99 % on verbose output.","operationId":"filter_cli_v1_filter_cli_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterCliRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterCliResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compress/tool-output":{"post":{"tags":["compression"],"summary":"Compress Tool Output","description":"Compress a large tool/command/MCP output blob with identifier preservation.\n\nUses the same CLI output optimizer engine as ``filter_cli_output`` but\nadds an identifier-preservation guarantee: execution-critical tokens\n(file paths with line/col, error codes, symbols, stack frame locations,\nURLs, UUIDs, env var names) are force-kept so a downstream agent can act\non the compressed output WITHOUT re-running the original tool.\n\nTypical savings: 80–99% on verbose output, identical to filter_cli_output,\nwith near-zero amnesia risk on critical tokens.","operationId":"compress_tool_output_v1_compress_tool_output_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressToolOutputRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompressToolOutputResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/github/webhook":{"post":{"tags":["integrations"],"summary":"Github Webhook","description":"Receive GitHub webhook events with per-tenant HMAC routing.\n\nSecurity contract\n-----------------\n1. Parse ``repository.full_name`` from the (still-unverified) payload —\n used ONLY as a lookup key, never trusted for auth decisions.\n2. Look up ``Integration`` rows for ``service=\"github\"`` whose stored\n ``config.repo_url`` normalises to the same ``owner/repo`` slug.\n3. **Verify HMAC** against that Integration's ``config.webhook_secret``\n BEFORE any dispatch. Dispatch ONLY on a verified payload.\n4. If no Integration matches → fall back to the global\n ``GITHUB_WEBHOOK_SECRET`` env-var verify + acknowledge-only (no\n dispatch, no regression for repos not yet integrated).\n5. If an Integration matches but signature check fails → same generic\n response as today (no tenant/secret existence leak, no dispatch).\n\nDispatch runs as a ``BackgroundTasks`` fire-and-forget so we return 200\nwithin GitHub's ~10 s timeout. Note: Fly ``auto_stop=suspend`` can\nterminate the machine before the task completes; GitHub won't retry a\n2xx. This is acceptable for a growth analytics feature — if guaranteed\ndelivery is required in future, move to a durable queue.","operationId":"github_webhook_v1_integrations_github_webhook_post","parameters":[{"name":"x-hub-signature-256","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Hub-Signature-256"}},{"name":"x-github-event","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Github-Event"}},{"name":"x-github-delivery","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Github-Delivery"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/github/configure":{"get":{"tags":["integrations"],"summary":"Get Github Config","description":"Get current GitHub integration settings (token redacted).","operationId":"get_github_config_v1_integrations_github_configure_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["integrations"],"summary":"Configure Github","description":"Save GitHub integration settings for the authenticated user.","operationId":"configure_github_v1_integrations_github_configure_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GithubIntegrationConfig"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["integrations"],"summary":"Delete Github Config","description":"Remove GitHub integration.","operationId":"delete_github_config_v1_integrations_github_configure_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/agents/mcp-clients":{"get":{"tags":["agents"],"summary":"Get Mcp Clients","description":"List gc_ keys owned by the caller with 30-day MCP activity stats.","operationId":"get_mcp_clients_v1_agents_mcp_clients_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMcpClientsResponse"}}}}}}},"/v1/agents/a2a-peers":{"get":{"tags":["agents"],"summary":"List A2A Peers","description":"List registered A2A peers owned by the caller.","operationId":"list_a2a_peers_v1_agents_a2a_peers_get","parameters":[{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean","description":"Include revoked peers (admin use)","default":false,"title":"Include Revoked"},"description":"Include revoked peers (admin use)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListA2APeersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["agents"],"summary":"Register A2A Peer","description":"Register a new A2A peer. Returns 409 if the same base_url is already registered.","operationId":"register_a2a_peer_v1_agents_a2a_peers_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/A2APeerRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/A2APeerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/a2a-peers/{peer_id}":{"patch":{"tags":["agents"],"summary":"Patch A2A Peer","description":"Update peer name, status, or public_key_jws.","operationId":"patch_a2a_peer_v1_agents_a2a_peers__peer_id__patch","parameters":[{"name":"peer_id","in":"path","required":true,"schema":{"type":"string","title":"Peer Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/A2APeerPatchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/A2APeerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["agents"],"summary":"Delete A2A Peer","description":"Revoke an A2A peer (soft-delete, sets status='revoked').","operationId":"delete_a2a_peer_v1_agents_a2a_peers__peer_id__delete","parameters":[{"name":"peer_id","in":"path","required":true,"schema":{"type":"string","title":"Peer Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/activity":{"get":{"tags":["agents"],"summary":"Get Activity","description":"Reverse-chronological sampled MCP call log. Supports cursor pagination.","operationId":"get_activity_v1_agents_activity_get","parameters":[{"name":"token_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by api_key_id (key_id field)","title":"Token Id"},"description":"Filter by api_key_id (key_id field)"},{"name":"tool_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by exact tool name","title":"Tool Name"},"description":"Filter by exact tool name"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-format cursor from previous page","title":"Cursor"},"description":"ISO-format cursor from previous page"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit-cache":{"post":{"tags":["optimization"],"summary":"Audit Cache","description":"Audit how cache-friendly a prompt is for a specific AI provider.","operationId":"audit_cache_v1_audit_cache_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditCacheRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditCacheResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/check-budget":{"post":{"tags":["analytics"],"summary":"Check Budget","description":"Check how much of the context budget a text would consume.","operationId":"check_budget_v1_check_budget_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/detect-issues":{"post":{"tags":["quality"],"summary":"Detect Issues","description":"Detect hallucinations and blind spots in compressed output.\n\nCompares compressed text against the original to find:\n- **Hallucinations**: claims in the compressed text not supported by the original\n- **Blind spots**: critical information in the original that was lost\n\nEnterprise feature — requires Pro or Enterprise plan.","operationId":"detect_issues_v1_detect_issues_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectIssuesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectIssuesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/notifications":{"get":{"tags":["notifications"],"summary":"Get Notifications","description":"Return active notifications for the current user.\n\nFilters by:\n- Current time between starts_at and expires_at (if set)\n- Target matches: 'all', user's plan, or user's specific ID","operationId":"get_notifications_v1_notifications_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/UserNotification"},"type":"array","title":"Response Get Notifications V1 Notifications Get"}}}}}}},"/v1/activity":{"get":{"tags":["activity"],"summary":"Read Activity","description":"Return a merged chronological activity timeline (own comments + notifications).","operationId":"read_activity_v1_activity_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":40,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/activity/notifications":{"get":{"tags":["activity"],"summary":"Read Notifications","description":"Return in-app notifications for the current user + unread count.","operationId":"read_notifications_v1_activity_notifications_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":40,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/activity/notifications/read-all":{"post":{"tags":["activity"],"summary":"Read All Notifications","description":"Mark all unread notifications read. Returns {\"updated\": N}.","operationId":"read_all_notifications_v1_activity_notifications_read_all_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Read All Notifications V1 Activity Notifications Read All Post"}}}}}}},"/v1/activity/notifications/{notification_id}/read":{"post":{"tags":["activity"],"summary":"Read Notification","description":"Mark a single notification as read. Returns {\"ok\": true/false}.","operationId":"read_notification_v1_activity_notifications__notification_id__read_post","parameters":[{"name":"notification_id","in":"path","required":true,"schema":{"type":"string","title":"Notification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Notification V1 Activity Notifications Notification Id Read Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/push/subscribe":{"post":{"tags":["push"],"summary":"Subscribe Push","description":"Upsert a W3C PushSubscription for the authenticated user.\n\nIf the (user_id, endpoint) pair already exists, updates p256dh + auth\nin place (handles browser key rotation after re-subscribe).\n\nReturns {\"status\": \"subscribed\"} on success.","operationId":"subscribe_push_v1_push_subscribe_post","parameters":[{"name":"user-agent","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User-Agent"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushSubscribeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["push"],"summary":"Unsubscribe Push","description":"Remove a push subscription for the authenticated user.\n\nIdempotent — returns {\"status\": \"unsubscribed\"} even if no row matched.","operationId":"unsubscribe_push_v1_push_subscribe_delete","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushUnsubscribeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsubscribeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/push/vapid-public-key":{"get":{"tags":["push"],"summary":"Get Vapid Public Key","description":"Return the VAPID public key so the client can call pushManager.subscribe().\n\nPublic endpoint — no auth required (the key is not secret).\nReturns 503 when VAPID_PUBLIC_KEY env var is not set (push not yet enabled).","operationId":"get_vapid_public_key_v1_push_vapid_public_key_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VapidPublicKeyResponse"}}}}}}},"/v1/push/test":{"post":{"tags":["push"],"summary":"Test Push Notification","description":"Send a test push notification to every registered browser for the caller.\n\nAuth required — same pattern as subscribe_push (_resolve_user_uuid).\n\nResponse:\n sent=N, status=\"ok\" — push attempted to N subscriptions.\n sent=0, status=\"no_subscriptions\" — user has no registered subscriptions.\n sent=0, status=\"push_disabled\" — VAPID key unset; send_web_push no-ops.\n\nIdempotent and best-effort: individual delivery failures are logged at ERROR\n(Sentry-visible) by send_web_push but never surfaced as 5xx to the caller.","operationId":"test_push_notification_v1_push_test_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestPushResponse"}}}}}}},"/v1/admin/notifications":{"get":{"tags":["admin"],"summary":"List Notifications","description":"List all notifications (admin only).","operationId":"list_notifications_v1_admin_notifications_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NotificationResponse"},"type":"array","title":"Response List Notifications V1 Admin Notifications Get"}}}}}},"post":{"tags":["admin"],"summary":"Create Notification","description":"Create a system notification (admin only).","operationId":"create_notification_v1_admin_notifications_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotificationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/notifications/{notification_id}":{"delete":{"tags":["admin"],"summary":"Delete Notification","description":"Delete a notification (admin only).","operationId":"delete_notification_v1_admin_notifications__notification_id__delete","parameters":[{"name":"notification_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Notification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/opus-delta/preview":{"get":{"tags":["admin"],"summary":"Opus Delta Preview","description":"Return the list of users who would be emailed + projected savings (read-only).","operationId":"opus_delta_preview_v1_admin_opus_delta_preview_get","parameters":[{"name":"plan","in":"query","required":false,"schema":{"type":"string","pattern":"^(pro|team|enterprise)$","default":"pro","title":"Plan"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/opus-delta/dispatch":{"post":{"tags":["admin"],"summary":"Opus Delta Dispatch","description":"Send the Opus 4.7 savings campaign email.\n\nSafety rails:\n- Intersects user_ids with OPUS_EMAIL_ALLOWLIST_CSV env var (first controlled send gate).\n- Skips email_opt_out users.\n- Idempotent: Redis NX key prevents double-sending within 90 days.\n- dry_run=True returns rendered bodies + recipient list without sending.","operationId":"opus_delta_dispatch_v1_admin_opus_delta_dispatch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/stats/overview":{"get":{"tags":["admin"],"summary":"Admin Stats Overview","description":"Return high-level KPIs: MRR, user counts, usage totals, churn.","operationId":"admin_stats_overview_v1_admin_stats_overview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/stats/usage-chart":{"get":{"tags":["admin"],"summary":"Admin Usage Chart","description":"Return daily compression volume for the chart.","operationId":"admin_usage_chart_v1_admin_stats_usage_chart_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":7,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/stats/signups-chart":{"get":{"tags":["admin"],"summary":"Admin Signups Chart","description":"Return daily signup counts.","operationId":"admin_signups_chart_v1_admin_stats_signups_chart_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":7,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/stats/top-users":{"get":{"tags":["admin"],"summary":"Admin Top Users","description":"Return top users by token usage.","operationId":"admin_top_users_v1_admin_stats_top_users_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":5,"default":15,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/stats/users":{"get":{"tags":["admin"],"summary":"Admin Users List","description":"Searchable, filterable user list.","operationId":"admin_users_list_v1_admin_stats_users_get","parameters":[{"name":"plan","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":5,"default":25,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/stats/leads":{"get":{"tags":["admin"],"summary":"Admin Leads List","description":"Return all enterprise leads.","operationId":"admin_leads_list_v1_admin_stats_leads_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/stats/referrals":{"get":{"tags":["admin"],"summary":"Admin Referrals List","description":"Return referral program stats.","operationId":"admin_referrals_list_v1_admin_stats_referrals_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/trials":{"get":{"tags":["admin"],"summary":"Admin Trials List","description":"#37 — trial funnel + currently-trialing roster for the admin dashboard.\n\nReads the ``subscriptions`` table populated by the Polar trial lifecycle\nwebhooks: status flips ``trialing`` on create, ``active`` on first charge, or\n``canceled`` if the user cancels in-trial (``started_as_trial`` marks the row\nas trial-originated for life). Dormant-empty until the trial product is live\n(GATE-A), so every count is 0 / list empty until then — by design.","operationId":"admin_trials_list_v1_admin_trials_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/stats/infrastructure":{"get":{"tags":["admin"],"summary":"Get Infrastructure","description":"Return real-time usage vs limits for every external service.","operationId":"get_infrastructure_v1_admin_stats_infrastructure_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/scaling":{"get":{"tags":["admin"],"summary":"Get Scaling","description":"Return the read-only autoscaling + rate-limit snapshot for the admin UI.","operationId":"get_scaling_v1_admin_scaling_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/price-audit":{"get":{"tags":["admin"],"summary":"Get Price Audit","description":"Return the live price-drift snapshot between our catalog and OpenRouter.","operationId":"get_price_audit_v1_admin_price_audit_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Price Audit V1 Admin Price Audit Get"}}}}}}},"/v1/admin/moderation/reports":{"get":{"tags":["moderation"],"summary":"Get Report Queue","description":"Return the moderation report queue. Mod/admin gated.","operationId":"get_report_queue_v1_admin_moderation_reports_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","pattern":"^(pending|resolved|ignored)$","default":"pending","title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Get Report Queue V1 Admin Moderation Reports Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/comments/{comment_id}/remove":{"post":{"tags":["moderation"],"summary":"Mod Remove Comment","description":"Remove a comment (soft-delete + replace body). Mod/admin gated.","operationId":"mod_remove_comment_v1_admin_moderation_comments__comment_id__remove_post","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeratorReasonBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Remove Comment V1 Admin Moderation Comments Comment Id Remove Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/comments/{comment_id}/restore":{"post":{"tags":["moderation"],"summary":"Mod Restore Comment","description":"Restore a previously removed comment. Mod/admin gated.","operationId":"mod_restore_comment_v1_admin_moderation_comments__comment_id__restore_post","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeratorReasonBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Restore Comment V1 Admin Moderation Comments Comment Id Restore Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/reports/{report_id}/resolve":{"post":{"tags":["moderation"],"summary":"Mod Resolve Report","description":"Resolve or ignore a content report. Mod/admin gated.","operationId":"mod_resolve_report_v1_admin_moderation_reports__report_id__resolve_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveReportBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Resolve Report V1 Admin Moderation Reports Report Id Resolve Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/feed-items/{item_id}/remove":{"post":{"tags":["moderation"],"summary":"Mod Remove Feed Item","description":"Remove a feed item from the feed (soft-delete via deleted_at). Mod/admin gated.\n\nCovers news, blog, and benchmark rows that live in feed_items.\nWrites a mod_actions row with target_type='feed_item'.","operationId":"mod_remove_feed_item_v1_admin_moderation_feed_items__item_id__remove_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeratorReasonBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Remove Feed Item V1 Admin Moderation Feed Items Item Id Remove Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/feed-items/{item_id}/restore":{"post":{"tags":["moderation"],"summary":"Mod Restore Feed Item","description":"Restore a previously removed feed item (clears deleted_at). Mod/admin gated.\n\nWrites a mod_actions row with target_type='feed_item'.","operationId":"mod_restore_feed_item_v1_admin_moderation_feed_items__item_id__restore_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeratorReasonBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Restore Feed Item V1 Admin Moderation Feed Items Item Id Restore Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/users/{user_id}/grant-moderator":{"post":{"tags":["moderation"],"summary":"Admin Grant Moderator","description":"Grant moderator role to a user. ADMIN-ONLY (not plain moderator).","operationId":"admin_grant_moderator_v1_admin_moderation_users__user_id__grant_moderator_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantModeratorBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Admin Grant Moderator V1 Admin Moderation Users User Id Grant Moderator Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/users/{user_id}/revoke-moderator":{"post":{"tags":["moderation"],"summary":"Admin Revoke Moderator","description":"Revoke moderator role from a user. ADMIN-ONLY (not plain moderator).","operationId":"admin_revoke_moderator_v1_admin_moderation_users__user_id__revoke_moderator_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantModeratorBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Admin Revoke Moderator V1 Admin Moderation Users User Id Revoke Moderator Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/users/{user_id}/silence":{"post":{"tags":["moderation"],"summary":"Mod Silence User","description":"Silence a user (prevent posting comments, votes, and reports). Mod/admin gated.\n\n``duration_hours`` is optional; omit for an indefinite silence.\nWrites a ``mod_actions`` row with action_type ``'silence'``.","operationId":"mod_silence_user_v1_admin_moderation_users__user_id__silence_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SilenceUserBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Silence User V1 Admin Moderation Users User Id Silence Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/moderation/users/{user_id}/unsilence":{"post":{"tags":["moderation"],"summary":"Mod Unsilence User","description":"Clear a user's silence (re-enable posting). Mod/admin gated.\n\nWrites a ``mod_actions`` row with action_type ``'unsilence'``.","operationId":"mod_unsilence_user_v1_admin_moderation_users__user_id__unsilence_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeratorReasonBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mod Unsilence User V1 Admin Moderation Users User Id Unsilence Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/test-keys":{"get":{"tags":["admin"],"summary":"List Test Keys","operationId":"list_test_keys_v1_admin_test_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTestKeysResponse"}}}}}},"post":{"tags":["admin"],"summary":"Create Test Key","description":"Mint a plan-stamped ``gc_`` API key attributed to the synthetic user.\n\nReturns the raw key exactly once. Store it immediately — the server\nnever exposes it again.","operationId":"create_test_key_v1_admin_test_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestKeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/test-keys/{key_id}":{"delete":{"tags":["admin"],"summary":"Delete Test Key","operationId":"delete_test_key_v1_admin_test_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/test-keys/{key_id}/usage":{"get":{"tags":["admin"],"summary":"Get Test Key Usage","operationId":"get_test_key_usage_v1_admin_test_keys__key_id__usage_get","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestKeyUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/mcp/reload":{"post":{"tags":["admin"],"summary":"Hot-reload the MCP tool catalog (F1)","description":"Performs a transactional copy-on-write swap of the live MCP tool catalog without a process restart. Requires admin privileges. Rate-limited to ≤1 reload per hour (R7). Disabled unless MCP_RELOAD_ENABLED=1 (R10).","operationId":"post_mcp_reload_v1_admin_mcp_reload_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpReloadResponse"}}}}}}},"/v1/admin/users":{"get":{"tags":["admin"],"summary":"List Users","description":"List users, optionally filtered by ``status``.\n\nSorted newest-first. Includes a 30-day compression count for each\nuser so the admin dashboard can render the abuse-signal column\nwithout an N+1 client-side fetch.","operationId":"list_users_v1_admin_users_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["active","flagged","disabled"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListUsersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/{clerk_id}/disable":{"post":{"tags":["admin"],"summary":"Disable User","operationId":"disable_user_v1_admin_users__clerk_id__disable_post","parameters":[{"name":"clerk_id","in":"path","required":true,"schema":{"type":"string","title":"Clerk Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/{clerk_id}/flag":{"post":{"tags":["admin"],"summary":"Flag User","operationId":"flag_user_v1_admin_users__clerk_id__flag_post","parameters":[{"name":"clerk_id","in":"path","required":true,"schema":{"type":"string","title":"Clerk Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/{clerk_id}/reactivate":{"post":{"tags":["admin"],"summary":"Reactivate User","operationId":"reactivate_user_v1_admin_users__clerk_id__reactivate_post","parameters":[{"name":"clerk_id","in":"path","required":true,"schema":{"type":"string","title":"Clerk Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/v2":{"get":{"tags":["admin"],"summary":"List Users V2","description":"Paginated, searchable, filterable user list with kind classification.","operationId":"list_users_v2_v1_admin_users_v2_get","parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ILIKE search against email and clerk_id.","title":"Search"},"description":"ILIKE search against email and clerk_id."},{"name":"plan","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by plan (free/pro/team/enterprise).","title":"Plan"},"description":"Filter by plan (free/pro/team/enterprise)."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status (active/flagged/disabled).","title":"Status"},"description":"Filter by status (active/flagged/disabled)."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by kind (real/test/internal).","title":"Kind"},"description":"Filter by kind (real/test/internal)."},{"name":"stage","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by funnel stage: signup (no keys, no events), keyed (has >=1 real key), activated (has >=1 usage event).","title":"Stage"},"description":"Filter by funnel stage: signup (no keys, no events), keyed (has >=1 real key), activated (has >=1 usage event)."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort field: created_at | email | plan.","default":"created_at","title":"Sort"},"description":"Sort field: created_at | email | plan."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":25,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/v2/{user_id}":{"get":{"tags":["admin"],"summary":"Get User Detail","description":"Return full profile + key counts + usage event count for one user.","operationId":"get_user_detail_v1_admin_users_v2__user_id__get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["admin"],"summary":"Patch User","description":"Change a user's plan and/or status.\n\nRefuses (HTTP 403) if the target is a protected admin account\n(@gotcontext.ai, ADMIN_EMAILS, or ADMIN_USER_IDS).","operationId":"patch_user_v1_admin_users_v2__user_id__patch","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchUserBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin"],"summary":"Delete User","description":"Permanently delete a user and cascade their api_keys + usage_events.\n\nProtected-account guard: refuses HTTP 403 on @gotcontext.ai /\nADMIN_EMAILS / ADMIN_USER_IDS targets.","operationId":"delete_user_v1_admin_users_v2__user_id__delete","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete User V1 Admin Users V2 User Id Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/users/v2/bulk-delete":{"post":{"tags":["admin"],"summary":"Bulk Delete Users","description":"Bulk-delete users by kind.\n\nPhase 1 only supports kind='test', which deletes all users whose\nemail ends with '@test.invalid'. Any other value is rejected with\nHTTP 400 to bound blast radius.\n\nReturns the count of deleted users.","operationId":"bulk_delete_users_v1_admin_users_v2_bulk_delete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/username":{"get":{"tags":["account"],"summary":"Get Username","description":"Return the current username for the authenticated user (null if unset).","operationId":"get_username_v1_account_username_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameResponse"}}}}}},"patch":{"tags":["account"],"summary":"Set Username","description":"Set or update the authenticated user's display username.\n\nConstraints:\n- 3–32 chars, alphanumeric + _ and -.\n- Case-insensitive unique across all users.\n- Reserved names blocked (with basic leetspeak fold).\n- Maximum one change per 30-day window (cooldown does not apply to first-time set\n or to re-submitting the same username).","operationId":"set_username_v1_account_username_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/export":{"get":{"tags":["account"],"summary":"Export Data","description":"Export all user data in a machine-readable format (GDPR Article 20).\n\nReturns a JSON document containing all data associated with the\nauthenticated user: usage events, API keys (masked), fidelity\nprofiles, and referral codes. No team data is included (that\nbelongs to the team, not the individual).","operationId":"export_data_v1_account_export_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExportResponse"}}}}}}},"/v1/account":{"delete":{"tags":["account"],"summary":"Delete Account","description":"Delete all user data (GDPR Article 17 — right to erasure).\n\nPermanently deletes: usage events, API keys, fidelity profiles,\nand referral codes. Does NOT delete the Clerk identity (user must\ndelete that separately from their Clerk settings).\n\nThis action is irreversible.","operationId":"delete_account_v1_account_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/email-preferences":{"get":{"tags":["account"],"summary":"Get Email Preferences","description":"Return the current email opt-out preference for the authenticated user.\n\nA value of ``true`` means all marketing, digest, and alert emails are\nsuppressed. Transactional emails (license keys, auth) are never gated.","operationId":"get_email_preferences_v1_account_email_preferences_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailPreferencesResponse"}}}}}},"patch":{"tags":["account"],"summary":"Patch Email Preferences","description":"Update the email opt-out preference for the authenticated user.\n\nPass ``{\"email_opt_out\": true}`` to suppress marketing/digest/alert emails.\nPass ``{\"email_opt_out\": false}`` to re-enable them.","operationId":"patch_email_preferences_v1_account_email_preferences_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailPreferencesPatch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailPreferencesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/alert-webhook":{"get":{"tags":["account"],"summary":"Get Alert Webhook","description":"Return the configured Discord-compatible alert webhook URL.\n\nReturns ``{\"alert_webhook_url\": null}`` when no webhook is set.","operationId":"get_alert_webhook_v1_account_alert_webhook_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertWebhookResponse"}}}}}},"patch":{"tags":["account"],"summary":"Patch Alert Webhook","description":"Set or clear the Discord-compatible alert webhook URL.\n\nValidates the URL via ``services.discord_alerts.is_valid_discord_webhook_url``\nso callers can't write an arbitrary URL that would later be POSTed\nby the cron sweep.","operationId":"patch_alert_webhook_v1_account_alert_webhook_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertWebhookPatch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/avatar":{"get":{"tags":["account"],"summary":"Get Avatar","description":"Return the current avatar shortcode for the authenticated user (null if unset).","operationId":"get_avatar_v1_account_avatar_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarResponse"}}}}}},"patch":{"tags":["account"],"summary":"Set Avatar","description":"Set or reset the authenticated user's curated avatar.\n\nPass a shortcode from the allowlist (e.g. ``\"preset:fox\"``) to set a\ncurated avatar. Pass ``null`` / ``None`` to reset to the auto-generated\nidenticon. The identicon is computed client-side from the username — no\nserver-side data is stored for it.","operationId":"set_avatar_v1_account_avatar_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/unsubscribe":{"get":{"tags":["unsubscribe"],"summary":"Unsubscribe","description":"Verify the token, opt the user out, and return an HTML confirmation page.","operationId":"unsubscribe_v1_unsubscribe_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"HMAC-signed unsubscribe token","title":"Token"},"description":"HMAC-signed unsubscribe token"}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit-logs":{"get":{"tags":["audit"],"summary":"List Audit Logs","description":"List audit log entries for the authenticated user's organization.\n\nEnterprise plan required. Returns paginated, filterable audit entries.","operationId":"list_audit_logs_v1_audit_logs_get","parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action","title":"Action"},"description":"Filter by action"},{"name":"actor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by actor","title":"Actor Id"},"description":"Filter by actor"},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by target type","title":"Target Type"},"description":"Filter by target type"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__app__routers__v1__audit_logs__AuditLogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit-logs/export":{"get":{"tags":["audit"],"summary":"Export Audit Logs Ndjson","description":"Stream all matching audit log entries as NDJSON (one JSON object per line).\n\nDesigned for bulk export to customer SIEMs. No pagination — the response is a\nstreaming generator that yields rows as they are read from the database.\nEnterprise plan required.","operationId":"export_audit_logs_ndjson_v1_audit_logs_export_get","parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action","title":"Action"},"description":"Filter by action"},{"name":"actor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by actor","title":"Actor Id"},"description":"Filter by actor"},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by target type","title":"Target Type"},"description":"Filter by target type"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 lower-bound timestamp (inclusive)","title":"Since"},"description":"ISO 8601 lower-bound timestamp (inclusive)"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 upper-bound timestamp (inclusive)","title":"Until"},"description":"ISO 8601 upper-bound timestamp (inclusive)"}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit-logs/export.csv":{"get":{"tags":["audit"],"summary":"Export Audit Logs Csv","description":"Stream all matching audit log entries as CSV.\n\nFirst row is a header. Designed for bulk export to customer SIEMs / spreadsheets.\nEnterprise plan required.","operationId":"export_audit_logs_csv_v1_audit_logs_export_csv_get","parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action","title":"Action"},"description":"Filter by action"},{"name":"actor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by actor","title":"Actor Id"},"description":"Filter by actor"},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by target type","title":"Target Type"},"description":"Filter by target type"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 lower-bound timestamp (inclusive)","title":"Since"},"description":"ISO 8601 lower-bound timestamp (inclusive)"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 upper-bound timestamp (inclusive)","title":"Until"},"description":"ISO 8601 upper-bound timestamp (inclusive)"}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/incidents":{"get":{"tags":["incidents"],"summary":"List Incidents","description":"Cluster non-success ``usage_events`` rows into hourly buckets per status.\n\nReturns clusters where ``count >= min_count`` over the trailing\n``lookback_hours`` window. Only the caller's own events are scoped\n(no cross-tenant leak).","operationId":"list_incidents_v1_incidents_get","parameters":[{"name":"lookback_hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Lookback Hours"}},{"name":"min_count","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":5,"title":"Min Count"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/saved-views":{"get":{"tags":["saved-views"],"summary":"List Saved Views","description":"List every saved view for the authenticated user, newest first.","operationId":"list_saved_views_v1_saved_views_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSavedViewsResponse"}}}}}},"post":{"tags":["saved-views"],"summary":"Create Saved View","description":"Create or overwrite (by name) a saved view.\n\nSame name → same row updated in place; this is the intended UX so\n\"Save view\" with an existing name doesn't raise 409 — it just\nre-saves the latest filters.","operationId":"create_saved_view_v1_saved_views_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedViewRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedView"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/saved-views/{view_id}":{"delete":{"tags":["saved-views"],"summary":"Delete Saved View","description":"Delete a saved view by id. 404 if not found OR if cross-tenant.","operationId":"delete_saved_view_v1_saved_views__view_id__delete","parameters":[{"name":"view_id","in":"path","required":true,"schema":{"type":"string","title":"View Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/mcp/tools":{"get":{"tags":["mcp"],"summary":"List Mcp Tools","description":"List all available MCP tools with categories and plan-gating info.\n\nReturns a list of every tool known to the MCP gateway, annotated with:\n- ``category``: derived from the tool name prefix\n- ``available``: whether the caller's current plan can invoke the tool\n\nNo authentication is strictly required (unauthenticated callers see the\nfull catalogue with ``available`` computed against the ``free`` plan).","operationId":"list_mcp_tools_v1_mcp_tools_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolsResponse"}}}}}}},"/v1/mcp/prime":{"get":{"tags":["mcp"],"summary":"Live plan-gated MCP tool list (Markdown) for plugin SessionStart","description":"Return a Markdown summary of every MCP tool available on the caller's plan.","operationId":"prime_session_v1_mcp_prime_get","parameters":[{"name":"plan","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Override the caller's auth plan. One of: free, pro, team, enterprise.","title":"Plan"},"description":"Override the caller's auth plan. One of: free, pro, team, enterprise."}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models":{"get":{"tags":["models"],"summary":"List Models","description":"Enumerate supported LLM models + their per-1k prices.","operationId":"list_models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}}}}},"/v1/demo/compress":{"post":{"tags":["demo"],"summary":"Demo Compress","description":"Compress text anonymously — for the public playground.\n\nRate-limited to 5 requests/minute per IP via Redis. No auth required.\nReturns compression result with savings statistics.","operationId":"demo_compress_v1_demo_compress_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoCompressRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoCompressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cron/weekly-digest":{"post":{"tags":["cron"],"summary":"Send Weekly Digest","description":"Send weekly usage digest emails to all users who had activity this week.\n\nTriggered by cron every Monday at 9am UTC.\nOnly sends to users who had at least 1 compression in the past 7 days.","operationId":"send_weekly_digest_v1_cron_weekly_digest_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/winback-sequence":{"post":{"tags":["cron"],"summary":"Send Winback Emails","description":"Send scheduled win-back emails (Day 14, 30, 42) to churned users.\n\nChecks subscriptions that were canceled at specific intervals and sends\nthe appropriate email in the sequence.","operationId":"send_winback_emails_v1_cron_winback_sequence_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/infra-check":{"post":{"tags":["cron"],"summary":"Infra Check","description":"Check infrastructure usage against free-tier limits and alert at 80%.","operationId":"infra_check_v1_cron_infra_check_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/rebuild-usage-cache":{"post":{"tags":["cron"],"summary":"Rebuild Usage Cache Cron","description":"Recompute every recent user's Redis daily counters from Postgres.","operationId":"rebuild_usage_cache_cron_v1_cron_rebuild_usage_cache_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/cache-sweep":{"post":{"tags":["cron"],"summary":"Semantic Cache Sweep","description":"Reclaim expired + orphaned semantic_cache_entries rows.","operationId":"semantic_cache_sweep_v1_cron_cache_sweep_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/check-key-quotas":{"post":{"tags":["cron"],"summary":"Check Key Quotas","description":"Per-key monthly-quota sweep — fire pending email + Discord alerts.","operationId":"check_key_quotas_v1_cron_check_key_quotas_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/check-project-budgets":{"post":{"tags":["cron"],"summary":"Check Project Budgets","description":"v1.22.0 — per-project token-budget alert sweep.\n\nIterates projects with a configured budget, computes period-to-date\ntoken usage (``usage_events.project_id``), compares against each\nalert threshold, and dispatches email when a threshold is crossed for\nthe first time this period (idempotent via ``last_alerted_threshold``).\n\nv1.22.5 — each budget row is processed inside a short transaction with\n``SELECT … FOR UPDATE`` so overlapping cron runs cannot double-send the\nsame threshold. Usage is aggregated once per run (GROUP BY project_id).\n\nRuns every 30 min (see cron.yml). No hard caps are applied — alerts\nonly; per the spec hard caps are a follow-up feature.","operationId":"check_project_budgets_v1_cron_check_project_budgets_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/batch-queue-sweep":{"post":{"tags":["cron"],"summary":"Batch Queue Sweep","description":"Pick up batch jobs stuck in ``queued`` or ``processing`` for > 5 minutes.\n\nFly.io ``auto_stop=suspend`` kills background tasks mid-flight. Jobs that\nwere being processed when the machine suspended are left with\n``status=\"processing\"`` and ``items_completed=0``. This cron endpoint\ndetects those stale jobs and re-invokes ``_process_batch_job_safe`` to\ncomplete them.\n\n**Staleness threshold:** Any job that has been in ``queued`` or\n``processing`` for more than ``_SWEEP_STALE_MINUTES`` (5) minutes is\nconsidered stuck and eligible for re-processing.\n\n**Idempotence:** ``_process_batch_job_safe`` re-fetches the job and\nitems from the DB. Items already in ``completed`` or ``failed`` state\nare skipped by the ``WHERE status='pending'`` filter inside the processor.\n\nTriggered every 5 minutes by cron.yml. Requires ``X-Cron-Secret`` header.\n\nReturns ``{\"swept\": N, \"failed\": M}`` — N = jobs handed to the processor,\nM = jobs where the processor itself raised an unhandled exception.","operationId":"batch_queue_sweep_v1_cron_batch_queue_sweep_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/check-key-expiry":{"post":{"tags":["cron"],"summary":"Check Key Expiry","description":"v1.20.13 — daily sweep that emails customers BEFORE their key\nexpires (T-7d / T-3d / T-1d).\n\nForward-only state machine on ``api_keys.expiry_alert_state``.\nResets when ``PATCH /v1/keys`` sets/changes/clears expires_at OR\nwhen rotation sets the predecessor's expires_at — both wired in\n``routers/v1/keys.py``, not here.\n\nTriggered by GitHub Actions cron at 09:00 UTC daily. See\n``.github/workflows/cron.yml``.","operationId":"check_key_expiry_v1_cron_check_key_expiry_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/check-trial-expiry":{"post":{"tags":["cron"],"summary":"Check Trial Expiry","description":"Daily — pre-charge reminder ~3 days before a 14-day Pro trial converts (FTC C4 /\nCalifornia ARL). Triggered by GitHub Actions cron; see .github/workflows/cron.yml.","operationId":"check_trial_expiry_v1_cron_check_trial_expiry_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-process-uploads":{"post":{"tags":["cron"],"summary":"Kb Process Uploads","description":"Process up to 100 UPLOADED kb_uploads rows across all projects.\n\nIterates every row with status='UPLOADED' (LIMIT 100, oldest-first) and\ncalls ``KnowledgeService.process_upload`` per row. Per-row failures are\nrecorded but do not abort the loop — the endpoint always returns 200 with\na summary of processed / failed counts.\n\nPer-project fan-out is capped at KB_INGEST_FAN_OUT_CAP per cycle (KB-SEC-03)\nto prevent one tenant from starving other projects.\n\nTriggered by cron scheduler (e.g. every minute via Fly.io).\nRequires the ``X-Cron-Secret`` header.","operationId":"kb_process_uploads_v1_cron_kb_process_uploads_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-expire-stale-uploads":{"post":{"tags":["cron"],"summary":"Kb Expire Stale Uploads","description":"Expire PENDING kb_uploads rows whose signed URL has passed its expiry time.\n\nRuns a single bulk UPDATE across ALL projects — does not use the\nproject-scoped service method so that no project-id iteration is required.\nReturns the count of rows transitioned to EXPIRED.\n\nTriggered by cron scheduler (e.g. every 15 minutes via Fly.io).\nRequires the ``X-Cron-Secret`` header.","operationId":"kb_expire_stale_uploads_v1_cron_kb_expire_stale_uploads_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-recover-stale-ingesting":{"post":{"tags":["cron"],"summary":"Kb Recover Stale Ingesting","description":"Sweep stuck-INGESTING kb_uploads rows → FAILED with a recovery message.\n\nA row stuck in INGESTING means the worker crashed between\n``process_upload``'s tx1 (UPLOADED → INGESTING commit) and tx2\n(→ COMPLETE/FAILED). Per CLAUDE.md O3 (Fly ``auto_stop=suspend``),\nthis can happen on machine suspend mid-ingest. The ``kb-process-uploads``\ncron never retries these rows because its WHERE filter is\n``status='UPLOADED'`` — stuck-INGESTING rows are invisible to it.\n\nIterates all projects (matching the ``_kb_process_uploads_inner``\npattern) and calls ``KnowledgeService.expire_stale_ingesting`` per\nproject. Rows older than 10 minutes (the default cutoff) are\ntransitioned to FAILED with an error_message instructing retry.\n\nSchedule: hourly at :55 (offset after kb-process-uploads).\nRequires the ``X-Cron-Secret`` header.","operationId":"kb_recover_stale_ingesting_v1_cron_kb_recover_stale_ingesting_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-purge-soft-deleted":{"post":{"tags":["cron"],"summary":"Kb Purge Soft Deleted","description":"Purge ``kb_chunks`` + ``kb_item_versions`` for items soft-deleted\n> ``KB_SOFT_DELETE_RETENTION_DAYS`` days ago.\n\nSoft-delete (``KnowledgeService.delete_item``) stamps\n``kb_items.deleted_at`` but leaves ``kb_chunks`` / ``kb_item_versions``\nintact. KB-SEC-05 closes that: this cron physically deletes chunks +\nversions for items whose ``deleted_at`` is older than the retention\nwindow (default 30 days). The ``kb_items`` row itself is RETAINED so\nthat audit trails + idempotent re-delete semantics still work.\n\nReturns ``{\"chunks_deleted\": N, \"versions_deleted\": M}``. Triggered\ndaily via Fly.io cron. Requires the ``X-Cron-Secret`` header.","operationId":"kb_purge_soft_deleted_v1_cron_kb_purge_soft_deleted_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-revocation-sweep":{"post":{"tags":["cron"],"summary":"Kb Revocation Sweep","description":"Re-invalidate Redis for any ``api_keys`` row stuck in ``status='revoked'``.\n\nBelt-and-brace for KB-SEC-07: ``revoke_key`` already raises 503 on Redis\nfailure (so admins see the problem), AND each Redis entry is now TTL-bounded\nto 5 minutes. This sweeper catches the edge case where a partial Redis\nwrite left one of (meta_key, index_key) stale. Scans revoked keys since\nthe last successful sweep and bulk-marks their Redis entries as ``revoked``.\nIdempotent.\n\nTriggered every few minutes via Fly.io cron. Requires ``X-Cron-Secret``.","operationId":"kb_revocation_sweep_v1_cron_kb_revocation_sweep_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-ingest-reddit":{"post":{"tags":["cron"],"summary":"News Ingest Reddit","description":"Pull all active RSS sources from news_sources and idempotently ingest into news_items.\n\nv1.30.0 — replaced n8n Schedule Trigger with this endpoint, hardcoded to\nr/MachineLearning.\nv1.32.10 — generalized to iterate over every active row in news_sources\nwhere kind='rss'. CEO market analysis (2026-05-21) expanded the source\nset from 1 to 8 subreddits spanning engineering practitioners\n(r/LocalLLaMA, r/LLMDevs, r/AI_Agents) + Claude-Code-specific\n(r/ClaudeCode, r/ClaudeAI) + official lab feeds (r/OpenAI, r/GeminiAI)\n+ the original r/MachineLearning research feed.\n\nHourly via .github/workflows/cron.yml at :07. Caps at 50 entries per\nsource per cycle to bound burst on infrequent Reddit RSS spikes (50 ×\n8 sources = 400 max items per cycle worst case).\n\nIdempotent: dedup via UNIQUE(source_slug, external_id) inside\ningest_news_items_batch — re-running this endpoint on the same feed is\nsafe and returns the same items as duplicates. Per-source error\nhandling: one bad feed (e.g. Reddit rate-limit on one sub) does NOT\nabort the run; the slug is recorded in the response's per_source\nbreakdown with an error message and the remaining sources continue.","operationId":"news_ingest_reddit_v1_cron_news_ingest_reddit_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-draft":{"post":{"tags":["cron"],"summary":"News Draft","description":"Draft up to NEWS_DRAFTER_BATCH_SIZE undrafted news_items via OpenRouter.\n\nRuns at :25 each hour (offset 18 min from news-ingest-reddit at :07)\nso fresh items from the ingest cycle are available.\n\nConcurrent-cron-safety: items are claimed atomically via\nUPDATE...WHERE draft_status='undrafted'...RETURNING so two simultaneous\ninvocations never draft the same item.\n\nBudget guard: skips drafting when month-to-date OpenRouter spend\nexceeds NEWS_DRAFTER_MONTHLY_BUDGET_USD (default $25).\n\nSends a single Resend notification email to the admin when drafted_count > 0.","operationId":"news_draft_v1_cron_news_draft_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-auto-publish":{"post":{"tags":["cron"],"summary":"News Auto Publish","description":"Auto-publish drafts that have been in 'drafted' state for >1 hour.\n\nCEO directive (2026-05-21): drafts that go through human review get\npublished immediately on click. Drafts that sit untouched for the\nconfigured threshold (default 60 min) get auto-promoted to news_articles\nwith actor_clerk_id='system:auto-publish' as the audit-trail sentinel.\n\nSchedule: GitHub Actions every 30 min at :15 and :45 — 20 min after\nthe :25 hourly drafter cron so newly-drafted items don't get\nauto-published in the same minute they're written.\n\nConcurrent-cron-safety: atomic UPDATE...WHERE...RETURNING +\nFOR UPDATE SKIP LOCKED on the inner SELECT, same pattern as\nclaim_undrafted_items.\n\nReturns dict with candidates_seen, published_count, error_count,\nand per-item error/slug arrays.","operationId":"news_auto_publish_v1_cron_news_auto_publish_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-slop-backfill":{"post":{"tags":["cron"],"summary":"News Slop Backfill","description":"Clean AI-slop from ALREADY-published articles (#39 Increment 2).\n\nA 2026-06-01 scan found ~600/851 published articles slop-heavy on Tier-2\nantipatterns (robust/comprehensive/seamless/em-dash overuse) that pass the\nhard Tier-1 kill-word gate. This processes a bounded batch per call: select\npublished articles not yet slop-audited, run the fact-guarded\n``_rewrite_for_voice``, and if it LOWERS the slop score, persist via\n``edit_article`` (which writes a revision row). Each article is flagged\n``slop_audited`` in JSONB metadata so a re-run never reprocesses it — drain\nby triggering repeatedly until ``remaining == 0``. ``?limit=N`` (default 25,\nmax 100). Manually triggered (not scheduled); each call is short, so the\nmachine stays warm and Fly auto-suspend can't kill a mid-batch run.","operationId":"news_slop_backfill_v1_cron_news_slop_backfill_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-thumbnail-backfill":{"post":{"tags":["cron"],"summary":"News Thumbnail Backfill","description":"Regenerate hero thumbnails for recently-published articles missing them.\n\nProduction 2026-05-21 measured 31% first-pass thumbnail success — most\nfailures are Gemini's safety filter returning 200 OK with no `images`\narray on Reddit-sourced titles. v1.32.12 added a category-only fallback\nprompt to `generate_thumbnail_for_draft`; this cron is the second safety\nnet for anything that still slips through (both attempts blocked, transient\n5xx, machine suspend mid-batch).\n\nSchedule: GitHub Actions every hour at :30 — 20 min after the :07\ningest, 5 min after the :25 drafter, and 15 min before the next :45\nauto-publish, so we don't collide with the active draft path.\n\nFilter: `hero_image_url IS NULL AND published_at > NOW() - INTERVAL '48h'`.\nThe 48h window keeps the monthly budget bounded ($150) and matches the\nwindow where AI Overview crawlers + social previews still benefit from\na thumbnail.\n\nBudget: same `NEWS_THUMBNAIL_MONTHLY_BUDGET_USD` cap as the inline path\n(default $150). Backfill stops silently when month-to-date spend exceeds.","operationId":"news_thumbnail_backfill_v1_cron_news_thumbnail_backfill_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-thumbnail-library-topup":{"post":{"tags":["cron"],"summary":"News Thumbnail Library Topup","description":"Top-up the news_thumbnail_library: ensure each category has ≥10 fresh\nentries available for the library-as-cache selector to pick from.\n\nFirst-run behavior = library seed. Subsequent runs = maintenance top-up.\nSame code path. See docs/strategy/2026-05-21-image-library-architecture.md.\n\nCron schedule: hourly at :43 (off-:00/:30 per cron hygiene + spaced from\nthe :30 backfill and :25 drafter). Cheap when library is well-provisioned\n(just a 4-COUNT-query roundtrip). Up to 3 generations per category per run\nwhen topping up — bounded to keep Nano Banana spend predictable.\n\nBudget: same NEWS_THUMBNAIL_MONTHLY_BUDGET_USD cap as the inline path.\nWorst case: 4 categories × 3 generations × $0.04 = $0.48/hour worst case\nduring initial seed, $0/hour at steady state.","operationId":"news_thumbnail_library_topup_v1_cron_news_thumbnail_library_topup_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-cost-of-inference-weekly":{"post":{"tags":["cron"],"summary":"News Cost Of Inference Weekly","description":"Publish a Cost-of-Inference article from deterministic pricing-catalog math.\n\nPer docs/strategy/2026-05-21-news-pipeline-strategy.md (8-seat thinktank\nsynthesis): this column is the moat. Numbers are pulled from the live\n`/v1/models` catalog and rendered with templated prose — no LLM in the\ncost-calculation path, so the numbers can never be wrong.\n\nFirst runs MANUAL via workflow_dispatch so the editorial output can be\nreviewed before scheduling. Once verified, schedule weekly Monday 09:00\nUTC (or similar) so the column publishes on a known cadence.\n\nNOT scheduled in cron.yml yet (CEO will greenlight after seeing the first\narticle). When ready, add `0 9 * * MON` to the schedule list + the case\nmap entry.\n\nIdempotency: slug is week-deterministic (`cost-of-inference-YYYY-MM-DD`)\nso calling this twice on the same date raises a UNIQUE-constraint error,\nblocking accidental double-publishing.","operationId":"news_cost_of_inference_weekly_v1_cron_news_cost_of_inference_weekly_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/news-beehiiv-sync":{"post":{"tags":["cron"],"summary":"News Beehiiv Sync","description":"Backfill: mirror unsynced news_subscribers rows to Beehiiv.\n\nScans for rows where ``beehiiv_synced_at IS NULL AND status = 'active'``\nand drives the Beehiiv add-contact API for each one. Runs every 5 minutes\nvia GitHub Actions (see cron.yml news-beehiiv-sync entry).\n\nProcesses up to 50 rows per run to stay well inside Beehiiv's 30 req/min\nfree-tier limit. Any failure is logged; the row stays NULL so the next\ncycle retries.\n\nNon-fatal: an individual Beehiiv 4xx/5xx skips that row (no exception\npropagated to the caller). A full Beehiiv outage returns a partial-sync\nsummary with the error count.","operationId":"news_beehiiv_sync_v1_cron_news_beehiiv_sync_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/kb-retention-sweep":{"post":{"tags":["cron"],"summary":"Kb Retention Sweep","description":"Soft-delete ``kb_items`` whose age exceeds the project's ``retention_days``.\n\nWalks every project where ``retention_days IS NOT NULL`` and\n``legal_hold_until`` is either NULL or in the past. Inside one bulk\nSQL round-trip per qualifying project, selects candidate\n``kb_items`` (``deleted_at IS NULL`` AND ``now() - created_at > make_interval(days => retention_days)``),\nsoft-deletes them via a bulk ``UPDATE ... WHERE id = ANY(:ids)``, and\nemits ONE bulk ``INSERT`` to ``audit_logs`` from ``unnest(...)``.\n\nPer-tick row cap is ``RETENTION_SWEEP_LIMIT`` (default 1000). This\nkeeps single-statement duration bounded so the Supabase pooler does\nnot hit its statement timeout on first-sweep backlogs. If a project\nhits the cap, the remainder will be caught on the next daily fire.\n\nDry-run mode (``RETENTION_DRY_RUN=1``): logs candidate counts AT WARN\nLEVEL so the forgotten-env-var failure mode is loud; skips both the\nUPDATE and the audit INSERT.\n\nReturns ``{\"status\": \"ok\", \"purged\": N}`` (normal) or\n``{\"status\": \"dry_run\", \"candidates\": N}`` (dry-run).\n\nTriggered daily via cron at 04:00 UTC. Requires ``X-Cron-Secret``.","operationId":"kb_retention_sweep_v1_cron_kb_retention_sweep_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/mcp-request-log-prune":{"post":{"tags":["cron"],"summary":"Mcp Request Log Prune","description":"Hard-delete ``mcp_request_log`` rows older than 90 days.\n\nSingle bulk DELETE in one transaction. Returns the rowcount. Table\nis sampled at 10% at write-time (Alembic 0066) so even at 100K calls/day\nonly ~10K rows/day land here; 90 days = ~900K rows steady-state which\nis well within Postgres's comfort zone for a sequential scan + delete.\n\nTriggered daily via cron at 04:15 UTC (offset 15 min after\nkb-retention-sweep). Requires ``X-Cron-Secret``.","operationId":"mcp_request_log_prune_v1_cron_mcp_request_log_prune_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/activation-nudge":{"post":{"tags":["cron"],"summary":"Send Activation Nudge","description":"Send a 24h activation nudge to users who have never compressed.\n\nQuery window: users created 24h–48h ago with 0 usage_events rows and\nemail_opt_out=False. Runs daily at 10:30 UTC via cron.yml.","operationId":"send_activation_nudge_v1_cron_activation_nudge_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/check-schema-parity":{"post":{"tags":["cron"],"summary":"Check Schema Parity","description":"Detect ORM-vs-deployed-schema drift and alert via Sentry + email.\n\nIterates every table in Base.metadata.sorted_tables, queries\ninformation_schema.columns for the actual deployed columns, and asserts\nthat ORM column names ⊆ actual deployed columns.\n\nTables absent from the DB are silently skipped (not-yet-migrated envs).\nPartitioned tables (e.g. kb_chunks HASH-partitioned): information_schema\nreports the parent table's columns, which is exactly what we want.\n\nAlways returns HTTP 200 — this is a report, not a gate. Drift is surfaced\nvia logger.error() (Sentry-captured) and an admin alert email.\n\nResponse body::\n\n {\n \"checked\": ,\n \"drifted\": [{\"table\": str, \"missing_columns\": [str]}, ...],\n \"ok\": \n }","operationId":"check_schema_parity_v1_cron_check_schema_parity_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cron/context-hub-reingest":{"post":{"tags":["cron"],"summary":"Context Hub Reingest","description":"Advance one incremental re-ingest step for the Context Hub gc_lookup KB.\n\nDetermines the single most-starved target framework per fire and either:\n - stages it (plan_reingest) when it has no active job at all, or\n - embeds the next _REINGEST_CHUNK sections (drain_reingest) for the\n active job with the oldest updated_at.\n\nWhen all three target frameworks are COMPLETE, returns immediately with\nstatus \"no_op\". Runs hourly at :48 via cron.yml. Requires X-Cron-Secret.","operationId":"context_hub_reingest_v1_cron_context_hub_reingest_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/clerk":{"post":{"tags":["webhooks"],"summary":"Clerk Webhook","description":"Handle incoming Clerk webhook events.\n\nVerifies the svix signature, then dispatches to the appropriate handler\nbased on the event type. Always returns HTTP 200 — processing errors are\nlogged but do not cause retries from Clerk.\n\nSupported events:\n- ``user.created`` — insert a new User row.\n- ``user.deleted`` — soft-delete the user (sets plan to \"deleted\").","operationId":"clerk_webhook_webhooks_clerk_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/polar":{"post":{"tags":["webhooks"],"summary":"Polar Webhook","description":"Handle incoming Polar billing webhook events.\n\nVerifies the svix signature (Polar uses the same svix delivery mechanism as\nClerk), then updates the User.plan field in the database. Always returns\nHTTP 200 — processing errors are logged so Polar does not retry infinitely.\n\nSupported events:\n- ``subscription.created`` — set user.plan = \"pro\", backfill polar_customer_id,\n upsert Subscription row.\n- ``subscription.updated`` — sync plan based on subscription status, update\n Subscription row.\n- ``subscription.canceled`` — set user.plan = \"free\", update Subscription row.","operationId":"polar_webhook_webhooks_polar_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/resend":{"post":{"tags":["webhooks"],"summary":"Resend Webhook","description":"Handle incoming Resend email-event webhook calls.\n\nVerifies the Svix signature, then dispatches based on event type.\nAlways returns HTTP 200 after Svix verification — processing errors are\nlogged but do not cause retries from Resend.\n\nSuppression events:\n- ``email.bounced`` with ``bounce.type == \"hard\"`` → opt-out user\n- ``email.complained`` → opt-out user\n\nIgnored events (log only):\n- ``email.bounced`` with ``bounce.type == \"soft\"``\n- ``email.delivered``, ``email.opened``, ``email.clicked``\n- ``email.sent``, ``email.failed``, ``email.delivery_delayed``\n- Any unrecognised event type","operationId":"resend_webhook_webhooks_resend_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root","description":"Root endpoint — API info and discovery links.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"A2APeerPatchRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"public_key_jws":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Key Jws"}},"type":"object","title":"A2APeerPatchRequest"},"A2APeerRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"base_url":{"type":"string","maxLength":1024,"minLength":8,"title":"Base Url"},"public_key_jws":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Key Jws"}},"type":"object","required":["name","base_url"],"title":"A2APeerRequest"},"A2APeerResponse":{"properties":{"id":{"type":"string","title":"Id"},"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"base_url":{"type":"string","title":"Base Url"},"status":{"type":"string","title":"Status"},"public_key_jws":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Key Jws"},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Synced At"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","user_id","name","base_url","status","created_at","updated_at"],"title":"A2APeerResponse"},"AcceptTeamInviteResponse":{"properties":{"team":{"$ref":"#/components/schemas/TeamResponse"},"membership":{"$ref":"#/components/schemas/TeamMembershipResponse"}},"type":"object","required":["team","membership"],"title":"AcceptTeamInviteResponse","description":"Result of accepting a pending team invite."},"ActivityEntryOut":{"properties":{"id":{"type":"string","title":"Id"},"tool_name":{"type":"string","title":"Tool Name"},"user_id":{"type":"string","title":"User Id"},"key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Id"},"item_ids":{"items":{"type":"string"},"type":"array","title":"Item Ids"},"latency_ms":{"type":"integer","title":"Latency Ms"},"status":{"type":"string","title":"Status"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","tool_name","user_id","item_ids","latency_ms","status","created_at"],"title":"ActivityEntryOut"},"ActivityItem":{"properties":{"id":{"type":"string","title":"Id"},"item_type":{"type":"string","enum":["own_comment","notification"],"title":"Item Type"},"comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Id"},"comment_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Body"},"feed_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feed Item Id"},"feed_item_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feed Item Title"},"feed_item_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feed Item Slug"},"notification_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notification Type"},"notification_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notification Body"},"actor_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Username"},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id"},"is_read":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Read"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","item_type","created_at"],"title":"ActivityItem","description":"One row in the unified activity timeline."},"ActivityPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ActivityItem"},"type":"array","title":"Items"},"unread_count":{"type":"integer","title":"Unread Count"}},"type":"object","required":["items","unread_count"],"title":"ActivityPage"},"ActivityResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/ActivityEntryOut"},"type":"array","title":"Entries"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["entries"],"title":"ActivityResponse"},"AddMembershipsRequest":{"properties":{"project_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"minItems":1,"title":"Project Ids","description":"Member project UUIDs to add (max 50 per call)."}},"type":"object","required":["project_ids"],"title":"AddMembershipsRequest"},"AddMembershipsResponse":{"properties":{"added":{"items":{"type":"string"},"type":"array","title":"Added"},"skipped":{"items":{"type":"string"},"type":"array","title":"Skipped"}},"type":"object","required":["added","skipped"],"title":"AddMembershipsResponse"},"AdminUserDetail":{"properties":{"id":{"type":"string","title":"Id"},"clerk_id":{"type":"string","title":"Clerk Id"},"email":{"type":"string","title":"Email"},"plan":{"type":"string","title":"Plan"},"status":{"type":"string","title":"Status"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"kind":{"type":"string","enum":["real","test","internal"],"title":"Kind"},"real_key_count":{"type":"integer","title":"Real Key Count"},"test_key_count":{"type":"integer","title":"Test Key Count"},"usage_event_count":{"type":"integer","title":"Usage Event Count"},"email_opt_out":{"type":"boolean","title":"Email Opt Out"}},"type":"object","required":["id","clerk_id","email","plan","status","created_at","kind","real_key_count","test_key_count","usage_event_count","email_opt_out"],"title":"AdminUserDetail"},"AdminUserItem":{"properties":{"clerk_id":{"type":"string","title":"Clerk Id"},"email":{"type":"string","title":"Email"},"plan":{"type":"string","title":"Plan"},"status":{"type":"string","title":"Status"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"compressions_30d":{"type":"integer","title":"Compressions 30D","description":"Compressions in last 30 days (anomaly signal)."},"age_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Age Hours","description":"Hours since signup. <24h + over-quota = abuse signal."}},"type":"object","required":["clerk_id","email","plan","status","created_at","compressions_30d","age_hours"],"title":"AdminUserItem"},"AdminUserListResponse":{"properties":{"users":{"items":{"$ref":"#/components/schemas/AdminUserRow"},"type":"array","title":"Users"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"}},"type":"object","required":["users","total","page","page_size"],"title":"AdminUserListResponse"},"AdminUserRow":{"properties":{"id":{"type":"string","title":"Id"},"clerk_id":{"type":"string","title":"Clerk Id"},"email":{"type":"string","title":"Email"},"plan":{"type":"string","title":"Plan"},"status":{"type":"string","title":"Status"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"kind":{"type":"string","enum":["real","test","internal"],"title":"Kind"},"real_key_count":{"type":"integer","title":"Real Key Count"},"activated":{"type":"boolean","title":"Activated"}},"type":"object","required":["id","clerk_id","email","plan","status","created_at","kind","real_key_count","activated"],"title":"AdminUserRow","description":"Single row in the paginated user list."},"AlertWebhookPatch":{"properties":{"alert_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alert Webhook Url"}},"type":"object","required":["alert_webhook_url"],"title":"AlertWebhookPatch","description":"Payload for PATCH /v1/account/alert-webhook.\n\nPass ``null`` to clear the configured URL. Validated server-side\nvia ``services.discord_alerts.is_valid_discord_webhook_url`` so a\nstolen Clerk session can't repurpose this field as a generic SSRF\nprimitive."},"AlertWebhookResponse":{"properties":{"alert_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alert Webhook Url"}},"type":"object","required":["alert_webhook_url"],"title":"AlertWebhookResponse","description":"Discord-compatible webhook URL for per-key quota alerts (v1.20.2)."},"ApprovalDecisionRequest":{"properties":{"decision":{"type":"string","enum":["approved","rejected","requested_changes"],"title":"Decision"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"}},"type":"object","required":["decision"],"title":"ApprovalDecisionRequest"},"ApprovalResponse":{"properties":{"id":{"type":"string","title":"Id"},"item_id":{"type":"string","title":"Item Id"},"project_id":{"type":"string","title":"Project Id"},"reviewer_user_id":{"type":"string","title":"Reviewer User Id"},"decision":{"type":"string","title":"Decision"},"decided_at":{"type":"string","title":"Decided At"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["id","item_id","project_id","reviewer_user_id","decision","decided_at"],"title":"ApprovalResponse"},"ApprovalsListResponse":{"properties":{"approvals":{"items":{"$ref":"#/components/schemas/ApprovalResponse"},"type":"array","title":"Approvals"}},"type":"object","required":["approvals"],"title":"ApprovalsListResponse"},"ApproveResponse":{"properties":{"article_id":{"type":"string","title":"Article Id"},"slug":{"type":"string","title":"Slug"},"published_at":{"type":"string","title":"Published At"}},"type":"object","required":["article_id","slug","published_at"],"title":"ApproveResponse"},"AuditCacheRequest":{"properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Prompt or document text to audit."},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/AuditSection"},"type":"array"},{"type":"null"}],"title":"Sections","description":"Structured prompt sections (tool_definitions, system_instructions, rag_context, few_shot_examples, chat_history, metadata, user_query). If omitted, the flat ``text`` is wrapped as a single system_instructions section."},"provider":{"type":"string","title":"Provider","description":"AI provider: anthropic, openai, google","default":"anthropic"}},"type":"object","title":"AuditCacheRequest","description":"Accepts either a flat ``text`` (wrapped as ``system_instructions``) or\na structured ``sections`` list matching the tool's canonical schema."},"AuditCacheResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"cache_friendly":{"type":"boolean","title":"Cache Friendly"},"score":{"type":"number","title":"Score","description":"Cacheability score 0.0-1.0"},"recommendations":{"items":{"type":"string"},"type":"array","title":"Recommendations"},"estimated_savings_pct":{"type":"number","title":"Estimated Savings Pct","description":"Estimated cache hit savings"}},"type":"object","required":["provider","cache_friendly","score","recommendations","estimated_savings_pct"],"title":"AuditCacheResponse"},"AuditEventResponse":{"properties":{"id":{"type":"string","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"project_id":{"type":"string","title":"Project Id"},"item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Id"},"actor":{"type":"string","title":"Actor"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","event_type","project_id","actor","payload","created_at"],"title":"AuditEventResponse"},"AuditLogEntry":{"properties":{"id":{"type":"string","title":"Id"},"timestamp":{"type":"string","title":"Timestamp"},"actor_id":{"type":"string","title":"Actor Id"},"actor_type":{"type":"string","title":"Actor Type"},"action":{"type":"string","title":"Action"},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"}},"type":"object","required":["id","timestamp","actor_id","actor_type","action","target_type","target_id","metadata","ip_address"],"title":"AuditLogEntry","description":"Single audit log entry."},"AuditSection":{"properties":{"name":{"type":"string","title":"Name"},"content":{"type":"string","title":"Content"}},"type":"object","required":["name","content"],"title":"AuditSection"},"AvatarRequest":{"properties":{"avatar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar"}},"type":"object","required":["avatar"],"title":"AvatarRequest","description":"Payload for PATCH /v1/account/avatar.\n\n``avatar`` must be one of the curated shortcodes in ``AVATAR_ALLOWLIST``,\nor ``None`` to reset to the auto-generated identicon."},"AvatarResponse":{"properties":{"avatar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar"}},"type":"object","required":["avatar"],"title":"AvatarResponse","description":"Response for GET and PATCH /v1/account/avatar."},"BatchDocument":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to compress"},"fidelity":{"type":"string","title":"Fidelity","description":"Compression level: abstract, outline, balanced, detailed, raw","default":"balanced"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Optional query for query-guided compression of this document"}},"type":"object","required":["text"],"title":"BatchDocument","description":"A single document in a batch compression request."},"BatchItemIngestRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SingleItemIngestRequest"},"type":"array","maxItems":100,"minItems":1,"title":"Items","description":"Up to 100 items per batch"}},"type":"object","required":["items"],"title":"BatchItemIngestRequest"},"BatchQueueCreatedResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"status":{"type":"string","title":"Status"},"items_total":{"type":"integer","title":"Items Total"}},"type":"object","required":["job_id","status","items_total"],"title":"BatchQueueCreatedResponse","description":"Response after a batch queue job is accepted."},"BatchQueueItemIn":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to compress"}},"type":"object","required":["text"],"title":"BatchQueueItemIn","description":"A single document to enqueue for compression."},"BatchQueueItemResult":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","title":"Status"},"input_text":{"type":"string","title":"Input Text"},"compressed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compressed"},"tokens_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens In"},"tokens_out":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens Out"},"tokens_saved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens Saved"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","status","input_text"],"title":"BatchQueueItemResult","description":"Result for a single item in a batch job."},"BatchQueueJobResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"status":{"type":"string","title":"Status"},"fidelity":{"type":"string","title":"Fidelity"},"items_total":{"type":"integer","title":"Items Total"},"items_completed":{"type":"integer","title":"Items Completed"},"progress_pct":{"type":"number","title":"Progress Pct"},"project_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["job_id","status","fidelity","items_total","items_completed","progress_pct","created_at"],"title":"BatchQueueJobResponse","description":"Status snapshot of a batch queue job."},"BatchQueueListResponse":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/BatchQueueJobResponse"},"type":"array","title":"Jobs"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["jobs","page","page_size","total"],"title":"BatchQueueListResponse","description":"Paginated list of batch queue jobs."},"BatchQueueRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BatchQueueItemIn"},"type":"array","title":"Items","description":"List of documents to compress. Maximum 200 per job."},"fidelity":{"type":"string","title":"Fidelity","description":"Compression level: abstract, outline, balanced, detailed, raw","default":"balanced"},"project_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id","description":"Optional project ID to associate the batch with."}},"type":"object","required":["items"],"title":"BatchQueueRequest","description":"Request body for creating a batch queue job."},"BatchQueueResultsResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"status":{"type":"string","title":"Status"},"items":{"items":{"$ref":"#/components/schemas/BatchQueueItemResult"},"type":"array","title":"Items"}},"type":"object","required":["job_id","status","items"],"title":"BatchQueueResultsResponse","description":"All items and their results for a batch job."},"BatchRequest":{"properties":{"documents":{"items":{"$ref":"#/components/schemas/BatchDocument"},"type":"array","title":"Documents","description":"List of documents to compress. Maximum 50 per call."}},"type":"object","required":["documents"],"title":"BatchRequest","description":"Request body for batch compression."},"BatchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BatchResultItem"},"type":"array","title":"Results"},"summary":{"$ref":"#/components/schemas/BatchSummary"}},"type":"object","required":["results","summary"],"title":"BatchResponse","description":"Response from batch compression."},"BatchResultItem":{"properties":{"compressed":{"type":"string","title":"Compressed"},"original_tokens":{"type":"integer","title":"Original Tokens"},"compressed_tokens":{"type":"integer","title":"Compressed Tokens"},"savings_pct":{"type":"number","title":"Savings Pct"},"compression_ratio":{"type":"number","title":"Compression Ratio"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["compressed","original_tokens","compressed_tokens","savings_pct","compression_ratio"],"title":"BatchResultItem","description":"Compression result for one document in the batch."},"BatchSummary":{"properties":{"total_documents":{"type":"integer","title":"Total Documents"},"successful":{"type":"integer","title":"Successful"},"failed":{"type":"integer","title":"Failed"},"total_tokens_in":{"type":"integer","title":"Total Tokens In"},"total_tokens_saved":{"type":"integer","title":"Total Tokens Saved"},"avg_savings_pct":{"type":"number","title":"Avg Savings Pct"},"avg_compression_ratio":{"type":"number","title":"Avg Compression Ratio"}},"type":"object","required":["total_documents","successful","failed","total_tokens_in","total_tokens_saved","avg_savings_pct","avg_compression_ratio"],"title":"BatchSummary","description":"Aggregate statistics across the entire batch."},"BenchmarkRunCreateRequest":{"properties":{"model_text":{"type":"string","maxLength":200,"title":"Model Text","description":"Model ID, e.g. 'meta-llama/Llama-3.3-70B-Instruct'"},"model_quant_text":{"type":"string","maxLength":80,"title":"Model Quant Text","description":"Quantization, e.g. 'Q4_K_M' or 'FP16'"},"hardware_text":{"type":"string","maxLength":200,"title":"Hardware Text","description":"Hardware description, e.g. 'RTX 5090 32GB'"},"context_length":{"type":"integer","exclusiveMinimum":0.0,"title":"Context Length","description":"Context window length in tokens"},"batch_size":{"type":"integer","exclusiveMinimum":0.0,"title":"Batch Size","description":"Batch size used during inference"},"tokens_per_sec_output":{"type":"number","exclusiveMinimum":0.0,"title":"Tokens Per Sec Output","description":"Output tokens per second"},"hardware_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Hardware Id","description":"Existing hardware SKU UUID (preferred over free-text)"},"ttft_ms":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Ttft Ms","description":"Time to first token in milliseconds"},"tokens_per_sec_input":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Tokens Per Sec Input"},"p50_latency_ms":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"P50 Latency Ms"},"p95_latency_ms":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"P95 Latency Ms"},"p99_latency_ms":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"P99 Latency Ms"},"vram_peak_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Vram Peak Mb"},"perplexity":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Perplexity"},"eval_scores":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Eval Scores","description":"e.g. {\"mmlu\": 0.62, \"humaneval\": 0.45}"},"software_stack":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Software Stack","description":"e.g. {\"framework\": \"llama.cpp\", \"version\": \"b3000\", \"cuda\": \"12.3\"}"},"settings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Settings","description":"e.g. {\"temperature\": 0.7, \"top_p\": 0.9}"},"notes":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Notes"},"source_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Source Url"},"source_label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Source Label"},"cf_turnstile_response":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Cf Turnstile Response","description":"Cloudflare Turnstile token for anonymous submissions. Prefer the cf-turnstile-response header; this body field is the fallback."},"itl_ms":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Itl Ms","description":"Inter-token latency (TPOT) in milliseconds — distinct from end-to-end p50/p95/p99"},"speculative_decoding":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Speculative Decoding","description":"Speculative decoding enabled (NULL = unknown)"},"flash_attn":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Flash Attn","description":"Flash Attention enabled (NULL = unknown)"},"perplexity_dataset":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Perplexity Dataset","description":"Corpus used for perplexity (e.g. WikiText-2, PTB, C4, ShareGPT, Custom)"},"runtime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Type","description":"Accelerator runtime type — one of ['cpu', 'cuda', 'metal', 'openvino', 'rocm', 'vulkan']"},"runtime_version":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Runtime Version","description":"Runtime version string (e.g. '12.4', '6.3.1')"},"gpu_count":{"type":"integer","exclusiveMinimum":0.0,"title":"Gpu Count","description":"Number of identical GPUs (e.g. 4× RTX 3090 = 4)","default":1},"gpu_split_mode":{"type":"string","title":"Gpu Split Mode","description":"GPU split strategy — one of ['layer', 'none', 'pipeline_parallel', 'row', 'tensor_parallel']","default":"none"},"gpu_secondary_hardware_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Gpu Secondary Hardware Id","description":"Secondary hardware UUID for HETEROGENEOUS configurations only (e.g. RTX 4070 + RTX 5070). Leave NULL for homogeneous multi-GPU."},"is_moe":{"type":"boolean","title":"Is Moe","description":"Mixture-of-Experts model flag","default":false},"total_params_b":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Total Params B","description":"Total parameter count in billions (e.g. 35 for Qwen3.6-35B-A3B)"},"active_params_b":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Active Params B","description":"Active parameter count in billions (e.g. 3 for A3B)"},"expert_offload_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Offload Mode","description":"Expert offload strategy — one of ['cpu_moe', 'n_cpu_moe', 'none', 'ot_exps_cpu']"},"n_cpu_moe_value":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"N Cpu Moe Value","description":"Integer value when expert_offload_mode == 'n_cpu_moe' (e.g. 32)"},"parallel_slots":{"type":"integer","exclusiveMinimum":0.0,"title":"Parallel Slots","description":"llama.cpp --parallel N value; per-slot ctx = context_length // parallel_slots","default":1},"inference_engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Engine","description":"Inference harness/engine — one of ['aphrodite', 'cerebras', 'dynamo', 'exllamav2', 'exllamav3', 'gpt4all', 'groq', 'jan', 'koboldcpp', 'llama_cpp', 'lm_studio', 'lmdeploy', 'localai', 'mlx_lm', 'nim', 'ollama', 'other', 'sambanova', 'sglang', 'tabbyapi', 'tensorrt_llm', 'text_generation_webui', 'tgi', 'transformers', 'triton', 'vllm', 'vllm_mlx']. Use 'other' + inference_engine_other for engines not in the list."},"inference_engine_other":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Inference Engine Other","description":"Free-text engine name when inference_engine == 'other'."},"backend_engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Engine","description":"Inner / backend engine for wrapper harnesses — one of ['aphrodite', 'cerebras', 'dynamo', 'exllamav2', 'exllamav3', 'gpt4all', 'groq', 'jan', 'koboldcpp', 'llama_cpp', 'lm_studio', 'lmdeploy', 'localai', 'mlx_lm', 'nim', 'ollama', 'other', 'sambanova', 'sglang', 'tabbyapi', 'tensorrt_llm', 'text_generation_webui', 'tgi', 'transformers', 'triton', 'vllm', 'vllm_mlx']."},"launch_command":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Launch Command","description":"Raw CLI invocation string for this run. Use settings jsonb for structured key-value engine parameters."},"kv_cache_dtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kv Cache Dtype","description":"KV-cache dtype — one of ['bf16', 'fp16', 'fp8', 'other', 'q4_0', 'q8_0']."}},"type":"object","required":["model_text","model_quant_text","hardware_text","context_length","batch_size","tokens_per_sec_output"],"title":"BenchmarkRunCreateRequest","description":"Payload for POST /v1/benchmarks/runs."},"BenchmarkRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"public_slug":{"type":"string","title":"Public Slug"},"model_text":{"type":"string","title":"Model Text"},"model_quant_text":{"type":"string","title":"Model Quant Text"},"hardware_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Hardware Id"},"hardware_text":{"type":"string","title":"Hardware Text"},"context_length":{"type":"integer","title":"Context Length"},"batch_size":{"type":"integer","title":"Batch Size"},"tokens_per_sec_output":{"type":"number","title":"Tokens Per Sec Output"},"ttft_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttft Ms"},"tokens_per_sec_input":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tokens Per Sec Input"},"p50_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Latency Ms"},"p95_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Latency Ms"},"p99_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P99 Latency Ms"},"vram_peak_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Vram Peak Mb"},"perplexity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Perplexity"},"eval_scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Eval Scores"},"software_stack":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Software Stack"},"settings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Settings"},"itl_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Itl Ms"},"speculative_decoding":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Speculative Decoding"},"flash_attn":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Flash Attn"},"perplexity_dataset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perplexity Dataset"},"runtime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Type"},"runtime_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Version"},"gpu_count":{"type":"integer","title":"Gpu Count","default":1},"gpu_split_mode":{"type":"string","title":"Gpu Split Mode","default":"none"},"gpu_secondary_hardware_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Gpu Secondary Hardware Id"},"is_moe":{"type":"boolean","title":"Is Moe","default":false},"total_params_b":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Params B"},"active_params_b":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Active Params B"},"expert_offload_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Offload Mode"},"n_cpu_moe_value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Cpu Moe Value"},"parallel_slots":{"type":"integer","title":"Parallel Slots","default":1},"per_slot_context":{"type":"integer","title":"Per Slot Context","default":0},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"inference_engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Engine"},"inference_engine_other":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Engine Other"},"backend_engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Engine"},"launch_command":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Launch Command"},"kv_cache_dtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kv Cache Dtype"},"verified_status":{"type":"string","title":"Verified Status"},"outlier_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Outlier Score"},"flag_count":{"type":"integer","title":"Flag Count"},"submitted_by_agent":{"type":"boolean","title":"Submitted By Agent"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Label"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"feed_item_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Feed Item Id"}},"type":"object","required":["id","public_slug","model_text","model_quant_text","hardware_id","hardware_text","context_length","batch_size","tokens_per_sec_output","ttft_ms","tokens_per_sec_input","p50_latency_ms","p95_latency_ms","p99_latency_ms","vram_peak_mb","perplexity","eval_scores","software_stack","settings","verified_status","outlier_score","flag_count","submitted_by_agent","notes","created_at"],"title":"BenchmarkRunResponse","description":"Full benchmark run representation."},"BudgetCheckRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to check against budget"},"context_window":{"type":"integer","title":"Context Window","description":"Target context window size in tokens","default":200000},"model":{"type":"string","title":"Model","description":"Target model name for cost estimation","default":"claude-opus-4"}},"type":"object","required":["text"],"title":"BudgetCheckRequest"},"BudgetCheckResponse":{"properties":{"estimated_tokens":{"type":"integer","title":"Estimated Tokens"},"context_window":{"type":"integer","title":"Context Window"},"pct_used":{"type":"number","title":"Pct Used"},"status":{"type":"string","title":"Status","description":"OK, WARNING, or CRITICAL"},"recommendation":{"type":"string","title":"Recommendation"}},"type":"object","required":["estimated_tokens","context_window","pct_used","status","recommendation"],"title":"BudgetCheckResponse"},"BudgetConfig":{"properties":{"monthly_token_budget":{"type":"integer","minimum":1.0,"title":"Monthly Token Budget","description":"Monthly token ceiling (tokens-in)."},"alert_thresholds":{"items":{"type":"integer"},"type":"array","title":"Alert Thresholds","description":"Alert percentages. Each value must be 1–100.","default":[75,90,100]}},"type":"object","required":["monthly_token_budget"],"title":"BudgetConfig","description":"Budget configuration payload (PUT body and GET response body)."},"BudgetResponse":{"properties":{"project_id":{"type":"string","title":"Project Id"},"monthly_token_budget":{"type":"integer","title":"Monthly Token Budget"},"alert_thresholds":{"items":{"type":"integer"},"type":"array","title":"Alert Thresholds"},"last_alerted_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Alerted Threshold"},"last_alerted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Alerted At"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["project_id","monthly_token_budget","alert_thresholds","created_at","updated_at"],"title":"BudgetResponse","description":"Budget configuration + state as returned by GET/PUT."},"BulkDeleteBody":{"properties":{"kind":{"type":"string","title":"Kind","description":"Must be 'test' in Phase 1."}},"type":"object","required":["kind"],"title":"BulkDeleteBody","description":"Payload for POST /v1/admin/users/v2/bulk-delete.\n\nPhase 1 only supports kind='test' (deletes @test.invalid accounts).\nAny other value is rejected with HTTP 400 to bound blast radius."},"BulkDeleteResponse":{"properties":{"deleted":{"type":"integer","title":"Deleted"}},"type":"object","required":["deleted"],"title":"BulkDeleteResponse"},"CacheBreakpointOut":{"properties":{"target":{"type":"string","title":"Target"},"position_tokens":{"type":"integer","title":"Position Tokens"},"ttl":{"type":"string","title":"Ttl"},"hint":{"type":"string","title":"Hint","default":""}},"type":"object","required":["target","position_tokens","ttl"],"title":"CacheBreakpointOut","description":"Provider-specific cache breakpoint hint emitted in the response."},"CachePolicyIn":{"properties":{"preserve_prefix":{"type":"boolean","title":"Preserve Prefix","default":false},"explicit_prefix_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Explicit Prefix Bytes"},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target","description":"anthropic | openai | gemini"},"ttl":{"type":"string","pattern":"^(5m|1h|24h)$","title":"Ttl","default":"5m"}},"type":"object","title":"CachePolicyIn","description":"Optional prompt-cache policy (v1.1).\n\nWhen ``preserve_prefix`` is true, the compressor leaves the declared\n(or auto-detected) static prefix byte-for-byte and compresses only\nthe dynamic suffix, so downstream providers can hit their native\nprompt cache on the prefix. ``target`` selects which provider's\nbreakpoint hint to return — anthropic / openai / gemini."},"CacheRollupRow":{"properties":{"target":{"type":"string","title":"Target"},"compressions":{"type":"integer","title":"Compressions"},"preserved_prefix_tokens_total":{"type":"integer","title":"Preserved Prefix Tokens Total"},"projected_combined_savings_usd":{"type":"number","title":"Projected Combined Savings Usd"}},"type":"object","required":["target","compressions","preserved_prefix_tokens_total","projected_combined_savings_usd"],"title":"CacheRollupRow"},"CandidateRow":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"tokens_last_30d":{"type":"integer","title":"Tokens Last 30D"},"projected_monthly_opus47_savings_usd":{"type":"number","title":"Projected Monthly Opus47 Savings Usd"},"email_opt_out":{"type":"boolean","title":"Email Opt Out"}},"type":"object","required":["user_id","email","tokens_last_30d","projected_monthly_opus47_savings_usd","email_opt_out"],"title":"CandidateRow"},"CheckoutRequest":{"properties":{"plan":{"type":"string","title":"Plan","default":"pro"}},"type":"object","title":"CheckoutRequest","description":"Body for the checkout endpoint."},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url"}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse","description":"Response containing the Polar checkout URL."},"ClaimReferralRequest":{"properties":{"referral_code":{"type":"string","title":"Referral Code"},"referred_user_id":{"type":"string","title":"Referred User Id"}},"type":"object","required":["referral_code","referred_user_id"],"title":"ClaimReferralRequest","description":"Body for POST /v1/referrals/claim."},"ClaimReferralResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"referral_code":{"type":"string","title":"Referral Code"},"referrer_user_id":{"type":"string","title":"Referrer User Id"},"credit_days":{"type":"integer","title":"Credit Days"}},"type":"object","required":["success","referral_code","referrer_user_id","credit_days"],"title":"ClaimReferralResponse","description":"Confirmation of referral claim."},"ClassificationPolicyRequest":{"properties":{"allowed_classifications":{"items":{"type":"string"},"type":"array","title":"Allowed Classifications","description":"Subset of classification values allowed for items in this project."},"default_classification":{"type":"string","title":"Default Classification","description":"Classification applied when caller omits classification on ingest.","default":"internal"},"required_at_ingest":{"type":"boolean","title":"Required At Ingest","description":"When True, callers must supply classification on ingest or receive 422.","default":false}},"type":"object","title":"ClassificationPolicyRequest","description":"Body for PUT …/policy."},"ClassificationPolicyResponse":{"properties":{"project_id":{"type":"string","title":"Project Id"},"allowed_classifications":{"items":{"type":"string"},"type":"array","title":"Allowed Classifications"},"default_classification":{"type":"string","title":"Default Classification"},"required_at_ingest":{"type":"boolean","title":"Required At Ingest"}},"type":"object","required":["project_id","allowed_classifications","default_classification","required_at_ingest"],"title":"ClassificationPolicyResponse","description":"Response for GET / PUT …/policy."},"ClassificationRequest":{"properties":{"classification":{"type":"string","enum":["public","internal","confidential","restricted"],"title":"Classification","description":"Data sensitivity classification level."}},"type":"object","required":["classification"],"title":"ClassificationRequest","description":"Body for PATCH …/classification."},"ClientRollupItem":{"properties":{"client":{"type":"string","title":"Client"},"calls":{"type":"integer","title":"Calls"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"avg_savings_pct":{"type":"number","title":"Avg Savings Pct"},"pct_of_total":{"type":"number","title":"Pct Of Total"}},"type":"object","required":["client","calls","tokens_in","tokens_saved","avg_savings_pct","pct_of_total"],"title":"ClientRollupItem"},"CodeCompressionStats":{"properties":{"original_tokens":{"type":"integer","title":"Original Tokens"},"compressed_tokens":{"type":"integer","title":"Compressed Tokens"},"savings_pct":{"type":"number","title":"Savings Pct"},"language_detected":{"type":"string","title":"Language Detected"}},"type":"object","required":["original_tokens","compressed_tokens","savings_pct","language_detected"],"title":"CodeCompressionStats","description":"Code compression statistics."},"CommentCreateRequest":{"properties":{"content":{"type":"string","maxLength":10000,"minLength":1,"title":"Content"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"UUID of the parent comment for replies"}},"type":"object","required":["content"],"title":"CommentCreateRequest","description":"Request body for POST /v1/benchmarks/runs/{run_id}/comments."},"CommentItem":{"properties":{"id":{"type":"string","title":"Id"},"item_id":{"type":"string","title":"Item Id"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"body":{"type":"string","title":"Body"},"depth":{"type":"integer","title":"Depth"},"score":{"type":"integer","title":"Score"},"author_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Username"},"edited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Edited At"},"author_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Plan"},"author_avatar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Avatar"}},"type":"object","required":["id","item_id","body","depth","score"],"title":"CommentItem"},"CommentListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CommentResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["items","total"],"title":"CommentListResponse","description":"Response shape for GET /v1/benchmarks/runs/{run_id}/comments."},"CommentRequest":{"properties":{"body":{"type":"string","maxLength":10000,"minLength":1,"title":"Body"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"}},"type":"object","required":["body"],"title":"CommentRequest"},"CommentResponse":{"properties":{"id":{"type":"string","title":"Id"},"benchmark_run_id":{"type":"string","title":"Benchmark Run Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"depth":{"type":"integer","title":"Depth"},"content":{"type":"string","title":"Content"},"status":{"type":"string","title":"Status"},"moderation_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moderation Label"},"moderation_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Moderation Confidence"},"moderation_reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moderation Reasoning"},"created_at":{"anyOf":[{},{"type":"null"}],"title":"Created At"},"deleted_at":{"anyOf":[{},{"type":"null"}],"title":"Deleted At"}},"type":"object","required":["id","benchmark_run_id","user_id","parent_id","depth","content","status","moderation_label","moderation_confidence","moderation_reasoning","created_at"],"title":"CommentResponse","description":"Response shape for a single benchmark comment."},"CommentResult":{"properties":{"id":{"type":"string","title":"Id"},"item_id":{"type":"string","title":"Item Id"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"depth":{"type":"integer","title":"Depth"},"body":{"type":"string","title":"Body"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"edited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Edited At"}},"type":"object","required":["id","item_id","depth","body","created_at"],"title":"CommentResult"},"CommentsPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CommentItem"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"CommentsPage"},"CompressCodeRequest":{"properties":{"code":{"type":"string","minLength":1,"title":"Code","description":"Source code to compress"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Programming language hint (python, javascript, typescript, java, go, rust, cpp). Auto-detected from content when omitted."},"fidelity":{"type":"string","title":"Fidelity","description":"Compression level: abstract, outline, balanced, detailed, raw","default":"balanced"}},"type":"object","required":["code"],"title":"CompressCodeRequest","description":"Request body for code compression."},"CompressCodeResponse":{"properties":{"compressed":{"type":"string","title":"Compressed"},"stats":{"$ref":"#/components/schemas/CodeCompressionStats"}},"type":"object","required":["compressed","stats"],"title":"CompressCodeResponse","description":"Response from code compression."},"CompressRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to compress"},"fidelity":{"type":"string","title":"Fidelity","description":"Compression level: abstract, outline, balanced, detailed, raw","default":"balanced"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Optional query string for query-guided compression. When provided, nodes most relevant to the query are prioritised while still meeting the target compression ratio."},"cost_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Model","description":"Model name for cost estimation (e.g. claude-sonnet-4-6)"},"team_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Team Id","description":"Optional team workspace to attribute this compression to."},"profile_id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Profile Id","description":"Optional saved fidelity profile to apply for this compression."},"multi_level":{"type":"boolean","title":"Multi Level","description":"When true, returns three compression levels in one call: headline (~10% kept), summary (~30% kept), and full (as per fidelity). The response includes a 'levels' object instead of a single 'compressed' string.","default":false},"cache_policy":{"anyOf":[{"$ref":"#/components/schemas/CachePolicyIn"},{"type":"null"}],"description":"Optional v1.1 prompt-cache policy. When set with ``preserve_prefix=true``, the static prefix is passed through byte-for-byte and only the dynamic suffix is compressed, so downstream providers can hit their native prompt cache."},"style":{"type":"string","pattern":"^(terse|normal|verbose)$","title":"Style","description":"v1.4.0 output-style hint. When 'terse', the response includes a short system_prompt_suffix clients should inject into the downstream LLM system prompt to cap output verbosity (~63% output-token reduction on independent 2026 benchmarks).","default":"normal"}},"type":"object","required":["text"],"title":"CompressRequest","description":"Request body for compression."},"CompressResponse":{"properties":{"compressed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compressed","description":"Compressed text (single-level mode)"},"levels":{"anyOf":[{"$ref":"#/components/schemas/MultiLevelOutput"},{"type":"null"}],"description":"Three tiers of compression (multi_level mode)"},"stats":{"$ref":"#/components/schemas/CompressionStats"},"original_tokens":{"type":"integer","title":"Original Tokens","description":"Token count of the original input text (cl100k_base, gpt-4 compatible).","default":0},"compressed_tokens":{"type":"integer","title":"Compressed Tokens","description":"Token count of the compressed output text.","default":0},"savings_pct":{"type":"number","title":"Savings Pct","description":"Percentage of tokens saved: (1 - compressed/original) * 100, rounded to 1 decimal place and clamped to 0 when the output is larger than the input (e.g. very short texts).","default":0.0},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Human-readable hint, present ONLY when the input was too small to compress effectively (below ~200 tokens the semantic-skeleton's fixed overhead exceeds the savings). Guides first-time evaluators to retry with a larger document instead of concluding the product 'made it bigger'."},"cache_breakpoints":{"items":{"$ref":"#/components/schemas/CacheBreakpointOut"},"type":"array","title":"Cache Breakpoints","description":"v1.1: provider-specific cache breakpoint hints. Empty when no ``cache_policy`` was supplied on the request."},"preserved_prefix_tokens":{"type":"integer","title":"Preserved Prefix Tokens","description":"v1.1: approximate token count of the prefix preserved byte-for-byte for prompt-cache reuse. Zero when no cache policy was supplied.","default":0},"system_prompt_suffix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt Suffix","description":"v1.4.0: short system-prompt rule block for the downstream LLM. Non-null only when the request sets style='terse'."},"style_suffix_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Style Suffix Version","description":"v1.4.0: version tag of the returned suffix (e.g. 'v1')."}},"type":"object","required":["stats"],"title":"CompressResponse","description":"Response from compression."},"CompressToolOutputRequest":{"properties":{"output":{"type":"string","minLength":1,"title":"Output","description":"Raw tool / command / MCP output to compress. Send the full blob — the service will preserve execution-critical identifiers (file paths with line numbers, error codes, symbols, URLs, stack frames, env var names, UUIDs) even when they would normally be elided by compression."},"command_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Command Hint","description":"Optional hint about the source tool type (e.g. 'mcp_tool_result', 'pytest', 'typescript_error', 'bash_output'). Auto-detected when omitted."},"preserve_identifiers":{"type":"boolean","title":"Preserve Identifiers","description":"When true (default), execution-critical identifiers are guaranteed to survive compression via a force-keep pass after the main compression engine runs. Set false to get standard filter_cli_output behavior.","default":true}},"type":"object","required":["output"],"title":"CompressToolOutputRequest","description":"Request body for tool output compression with identifier preservation."},"CompressToolOutputResponse":{"properties":{"compressed":{"type":"string","title":"Compressed"},"original_chars":{"type":"integer","title":"Original Chars"},"filtered_chars":{"type":"integer","title":"Filtered Chars"},"savings_pct":{"type":"number","title":"Savings Pct"},"detected_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Type"},"preserved_identifier_count":{"type":"integer","title":"Preserved Identifier Count","default":0},"reinjected_count":{"type":"integer","title":"Reinjected Count","default":0},"reinjected_tokens":{"items":{"type":"string"},"type":"array","title":"Reinjected Tokens"}},"type":"object","required":["compressed","original_chars","filtered_chars","savings_pct"],"title":"CompressToolOutputResponse","description":"Response from POST /v1/compress/tool-output."},"CompressionEvent":{"properties":{"id":{"type":"string","title":"Id"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_out":{"type":"integer","title":"Tokens Out"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"savings_pct":{"type":"number","title":"Savings Pct"},"fidelity":{"type":"string","title":"Fidelity"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"input_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Preview"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Name"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"model_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Source"},"status":{"type":"string","title":"Status","default":"success"},"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","tokens_in","tokens_out","tokens_saved","savings_pct","fidelity","created_at"],"title":"CompressionEvent","description":"A single compression event in the history."},"CompressionStats":{"properties":{"original_tokens":{"type":"integer","title":"Original Tokens"},"compressed_tokens":{"type":"integer","title":"Compressed Tokens"},"savings_pct":{"type":"number","title":"Savings Pct"},"compression_ratio":{"type":"number","title":"Compression Ratio"},"estimated_cost_saved":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Cost Saved"}},"type":"object","required":["original_tokens","compressed_tokens","savings_pct","compression_ratio"],"title":"CompressionStats","description":"Compression statistics."},"ConfirmTokenResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"operation":{"type":"string","title":"Operation"},"api_key_id":{"type":"string","title":"Api Key Id"},"payload_processed":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Processed"},"new_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Key"},"new_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Key Id"}},"type":"object","required":["success","operation","api_key_id"],"title":"ConfirmTokenResponse"},"ContentReportRequest":{"properties":{"target_type":{"type":"string","title":"Target Type","description":"Type of content being reported. One of: benchmark, comment, feed_item, news"},"target_id":{"type":"string","title":"Target Id","description":"UUID of the content being reported."},"reason":{"type":"string","pattern":"^(spam|inappropriate|illegal|other)$","title":"Reason","description":"Reason for the report."},"detail":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Detail"}},"type":"object","required":["target_type","target_id","reason"],"title":"ContentReportRequest"},"CreateKeyRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Human-readable key name"},"default_model":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Default Model","description":"Optional LLM model this key is typically used with. Used to price MCP compression savings when the tool call doesn't pass an explicit ``_meta.model``. Must be one of the models returned by ``/v1/models`` (or a recognised alias)."},"environment":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Environment","description":"Environment label: dev | staging | prod | other.","default":"prod"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"UUID of the project to bind this key to (optional)."},"scope_model":{"type":"string","title":"Scope Model","description":"Scope enforcement model: 'legacy' = god-mode (default, backward compat); 'scoped' = enforce scopes / denied_scopes allow/deny list.","default":"legacy"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"List of granted scope strings (e.g. ['compress:read', 'keys:read'])."},"denied_scopes":{"items":{"type":"string"},"type":"array","title":"Denied Scopes","description":"List of explicitly denied scopes (trumps grants)."}},"type":"object","required":["name"],"title":"CreateKeyRequest","description":"Request body for API key creation."},"CreateKeyResponse":{"properties":{"key":{"type":"string","title":"Key"},"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"created_at":{"type":"string","title":"Created At"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model"},"environment":{"type":"string","title":"Environment","default":"prod"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"},"scope_model":{"type":"string","title":"Scope Model","default":"legacy"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","default":[]},"denied_scopes":{"items":{"type":"string"},"type":"array","title":"Denied Scopes","default":[]}},"type":"object","required":["key","key_id","name","created_at"],"title":"CreateKeyResponse","description":"Response after creating an API key.\n\nThe ``key`` field contains the full raw key — this is shown ONCE and\ncannot be retrieved again. Store it securely immediately."},"CreateLeadRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"email":{"type":"string","maxLength":255,"minLength":3,"title":"Email"},"company":{"type":"string","maxLength":255,"minLength":1,"title":"Company"},"message":{"type":"string","maxLength":5000,"title":"Message","default":""}},"type":"object","required":["name","email","company"],"title":"CreateLeadRequest","description":"Body for POST /v1/leads."},"CreateNotificationRequest":{"properties":{"title":{"type":"string","maxLength":200,"minLength":1,"title":"Title"},"message":{"type":"string","minLength":1,"title":"Message"},"severity":{"type":"string","pattern":"^(info|warning|error|success)$","title":"Severity","default":"info"},"category":{"type":"string","pattern":"^(system|billing|usage|feature|maintenance)$","title":"Category","default":"system"},"target":{"type":"string","title":"Target","description":"Target: 'all', 'free', 'pro', 'enterprise', or a specific user_id","default":"all"},"dismissible":{"type":"boolean","title":"Dismissible","default":true},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["title","message"],"title":"CreateNotificationRequest"},"CreateProfileRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Human-readable profile name"},"fidelity":{"type":"string","title":"Fidelity","description":"Compression fidelity level"},"chunk_size":{"type":"integer","maximum":1000.0,"minimum":50.0,"title":"Chunk Size","description":"Token chunk size for segmentation","default":150},"skeleton_ratio":{"type":"number","maximum":1.0,"minimum":0.05,"title":"Skeleton Ratio","description":"Fraction of nodes kept in skeleton","default":0.2},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description"}},"type":"object","required":["name","fidelity"],"title":"CreateProfileRequest","description":"Body for POST /v1/profiles."},"CreateProjectRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Human-readable project name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional project description"}},"type":"object","required":["name"],"title":"CreateProjectRequest","description":"Body for POST /v1/projects."},"CreateSavedViewRequest":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name"},"filters":{"additionalProperties":true,"type":"object","title":"Filters"}},"type":"object","required":["name"],"title":"CreateSavedViewRequest"},"CreateTeamRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"}},"type":"object","required":["name"],"title":"CreateTeamRequest","description":"Body for POST /v1/teams."},"CreateTestKeyRequest":{"properties":{"plan":{"type":"string","enum":["free","pro","team","enterprise"],"title":"Plan","description":"Plan tier to stamp on the key."},"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"expires_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":0.0},{"type":"null"}],"title":"Expires Days","description":"Optional auto-expiry in days. 0 or null means no expiry. Helps prevent forgotten long-lived admin keys."}},"type":"object","required":["plan","name"],"title":"CreateTestKeyRequest"},"CreateTestKeyResponse":{"properties":{"key":{"type":"string","title":"Key"},"key_id":{"type":"string","title":"Key Id"},"plan":{"type":"string","title":"Plan"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["key","key_id","plan","expires_at"],"title":"CreateTestKeyResponse"},"CreateWebhookRequest":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"events":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Events"}},"type":"object","required":["url","events"],"title":"CreateWebhookRequest","description":"Body for POST /v1/webhooks."},"DataExportResponse":{"properties":{"exported_at":{"type":"string","title":"Exported At"},"user_id":{"type":"string","title":"User Id"},"usage_events_count":{"type":"integer","title":"Usage Events Count"},"api_keys_count":{"type":"integer","title":"Api Keys Count"},"profiles_count":{"type":"integer","title":"Profiles Count"},"referrals_count":{"type":"integer","title":"Referrals Count"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["exported_at","user_id","usage_events_count","api_keys_count","profiles_count","referrals_count","data"],"title":"DataExportResponse","description":"GDPR Article 20 — data portability response."},"DecideRequest":{"properties":{"decision":{"type":"string","title":"Decision"}},"type":"object","required":["decision"],"title":"DecideRequest"},"DecideResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["request_id","status"],"title":"DecideResponse"},"DeleteResponse":{"properties":{"deleted":{"type":"boolean","title":"Deleted"},"item_id":{"type":"string","title":"Item Id"}},"type":"object","required":["deleted","item_id"],"title":"DeleteResponse"},"DemoCompressRequest":{"properties":{"text":{"type":"string","maxLength":5000,"minLength":10,"title":"Text"},"fidelity":{"type":"string","title":"Fidelity","default":"balanced"}},"type":"object","required":["text"],"title":"DemoCompressRequest","description":"Minimal request body for the anonymous playground."},"DemoCompressResponse":{"properties":{"compressed":{"type":"string","title":"Compressed"},"original_tokens":{"type":"integer","title":"Original Tokens"},"compressed_tokens":{"type":"integer","title":"Compressed Tokens"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"savings_pct":{"type":"number","title":"Savings Pct"}},"type":"object","required":["compressed","original_tokens","compressed_tokens","tokens_saved","savings_pct"],"title":"DemoCompressResponse","description":"Playground response with savings stats."},"DetectIssuesRequest":{"properties":{"original_text":{"type":"string","minLength":1,"title":"Original Text","description":"Original uncompressed text"},"compressed_text":{"type":"string","minLength":1,"title":"Compressed Text","description":"Compressed/generated text to check"},"check_hallucination":{"type":"boolean","title":"Check Hallucination","description":"Check for hallucinated content not in the original","default":true},"check_blind_spots":{"type":"boolean","title":"Check Blind Spots","description":"Check for critical info lost during compression","default":true}},"type":"object","required":["original_text","compressed_text"],"title":"DetectIssuesRequest","description":"Request body for issue detection."},"DetectIssuesResponse":{"properties":{"issues_found":{"type":"integer","title":"Issues Found"},"issues":{"items":{"$ref":"#/components/schemas/IssueItem"},"type":"array","title":"Issues"},"quality_score":{"type":"number","title":"Quality Score","description":"Overall quality 0.0-1.0 (1.0 = no issues)"}},"type":"object","required":["issues_found","issues","quality_score"],"title":"DetectIssuesResponse","description":"Response from issue detection."},"DiffResponse":{"properties":{"from_version_id":{"type":"string","title":"From Version Id"},"to_version_id":{"type":"string","title":"To Version Id"},"from_content":{"type":"string","title":"From Content"},"to_content":{"type":"string","title":"To Content"},"unified_diff":{"type":"string","title":"Unified Diff"}},"type":"object","required":["from_version_id","to_version_id","from_content","to_content","unified_diff"],"title":"DiffResponse"},"DispatchRequest":{"properties":{"user_ids":{"items":{"type":"string"},"type":"array","title":"User Ids"},"dry_run":{"type":"boolean","title":"Dry Run","default":false},"allowlist_csv_env":{"type":"string","title":"Allowlist Csv Env","default":"OPUS_EMAIL_ALLOWLIST_CSV"}},"type":"object","required":["user_ids"],"title":"DispatchRequest"},"DispatchResponse":{"properties":{"sent":{"type":"integer","title":"Sent"},"skipped_opt_out":{"type":"integer","title":"Skipped Opt Out"},"skipped_duplicate":{"type":"integer","title":"Skipped Duplicate"},"skipped_not_in_allowlist":{"type":"integer","title":"Skipped Not In Allowlist"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors"}},"type":"object","required":["sent","skipped_opt_out","skipped_duplicate","skipped_not_in_allowlist","errors"],"title":"DispatchResponse"},"DraftItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"source_slug":{"type":"string","title":"Source Slug"},"url":{"type":"string","title":"Url"},"original_title":{"type":"string","title":"Original Title"},"ingested_at":{"type":"string","title":"Ingested At"},"draft_status":{"type":"string","title":"Draft Status"},"draft_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Title"},"draft_excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Excerpt"},"draft_body_md":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Body Md"},"draft_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Category"},"draft_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Model"},"draft_tokens_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Draft Tokens In"},"draft_tokens_out":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Draft Tokens Out"},"draft_cost_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Draft Cost Micros"},"drafted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drafted At"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"},"reviewed_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed By User Id"},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rejection Reason"},"published_article_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Article Id"},"draft_thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Thumbnail Url"}},"type":"object","required":["id","source_slug","url","original_title","ingested_at","draft_status","draft_title","draft_excerpt","draft_body_md","draft_category","draft_model","draft_tokens_in","draft_tokens_out","draft_cost_micros","drafted_at","reviewed_at","reviewed_by_user_id","rejection_reason","published_article_id"],"title":"DraftItemResponse","description":"Single draft item shape (news_items row with draft columns)."},"EditArticleRequest":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Title"},"body_md":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Body Md"},"category":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Category"},"hero_image_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Hero Image Url"},"excerpt":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Excerpt"},"source_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Source Url"},"source_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Attribution"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","title":"EditArticleRequest"},"EditArticleResponse":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"status":{"type":"string","title":"Status"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","slug","title","status","updated_at"],"title":"EditArticleResponse"},"EditCommentRequest":{"properties":{"body":{"type":"string","maxLength":10000,"minLength":1,"title":"Body"}},"type":"object","required":["body"],"title":"EditCommentRequest"},"EditRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"content":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Content"},"base_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Base Version Id"},"force_overwrite":{"type":"boolean","title":"Force Overwrite","default":false},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"fidelity":{"type":"string","enum":["abstract","outline","balanced","detailed","raw"],"title":"Fidelity","default":"balanced"},"mcp_exposed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mcp Exposed"}},"type":"object","title":"EditRequest","description":"PATCH /v1/projects/{project_id}/knowledge/items/{id}.\n\nAt least one of ``name``, ``content``, or ``mcp_exposed`` must be present.\n``base_version_id`` is required when ``content`` is provided."},"EmailPreferencesPatch":{"properties":{"email_opt_out":{"type":"boolean","title":"Email Opt Out"}},"type":"object","required":["email_opt_out"],"title":"EmailPreferencesPatch","description":"Payload for PATCH /v1/account/email-preferences.\n\nUses ``StrictBool`` so Pydantic's lax coercion (where ``\"yes\"`` would\nsilently become ``True``) is rejected with 422 — matching the intent\nof the ``test_patch_email_preferences_rejects_string`` regression."},"EmailPreferencesResponse":{"properties":{"email_opt_out":{"type":"boolean","title":"Email Opt Out"}},"type":"object","required":["email_opt_out"],"title":"EmailPreferencesResponse","description":"Email preference state for the authenticated user."},"EventsResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/CompressionEvent"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["events","total","page","page_size","has_more"],"title":"EventsResponse","description":"Paginated compression history."},"FeedItem":{"properties":{"id":{"type":"string","title":"Id"},"content_type":{"type":"string","enum":["news","blog","benchmark"],"title":"Content Type"},"type":{"type":"string","enum":["news","blog","benchmark"],"title":"Type"},"title":{"type":"string","title":"Title"},"sort_time":{"type":"string","format":"date-time","title":"Sort Time"},"content_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Slug"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"author_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Label"},"compression_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compression Ratio"},"hardware_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware Text"},"model_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Text"},"tokens_per_sec":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tokens Per Sec"},"net_score":{"type":"integer","title":"Net Score","default":0},"upvote_count":{"type":"integer","title":"Upvote Count","default":0},"downvote_count":{"type":"integer","title":"Downvote Count","default":0},"comment_count":{"type":"integer","title":"Comment Count","default":0},"hot_score":{"type":"number","title":"Hot Score","default":0.0},"user_vote":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Vote"}},"type":"object","required":["id","content_type","type","title","sort_time"],"title":"FeedItem","description":"Unified feed card wire shape (mirrors the TS ``FeedItem`` in\napps/web/src/libs/gotcontext-api.ts — keep them in lockstep, F11)."},"FeedPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeedItem"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items"],"title":"FeedPage"},"FilterCliRequest":{"properties":{"output":{"type":"string","minLength":1,"title":"Output","description":"Raw CLI output to filter/compress"},"command_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Command Hint","description":"Optional hint about the command type (e.g., 'git_diff', 'test_output'). Auto-detected if omitted."}},"type":"object","required":["output"],"title":"FilterCliRequest","description":"Request body for CLI output filtering."},"FilterCliResponse":{"properties":{"filtered":{"type":"string","title":"Filtered"},"original_chars":{"type":"integer","title":"Original Chars"},"filtered_chars":{"type":"integer","title":"Filtered Chars"},"savings_pct":{"type":"number","title":"Savings Pct"},"detected_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Type"}},"type":"object","required":["filtered","original_chars","filtered_chars","savings_pct"],"title":"FilterCliResponse","description":"Response from CLI output filtering."},"FlagRequest":{"properties":{"reason":{"type":"string","maxLength":200,"title":"Reason"},"details":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Details"}},"type":"object","required":["reason"],"title":"FlagRequest"},"FollowStatusResponse":{"properties":{"following":{"type":"boolean","title":"Following"},"follower_count":{"type":"integer","title":"Follower Count"},"following_count":{"type":"integer","title":"Following Count"}},"type":"object","required":["following","follower_count","following_count"],"title":"FollowStatusResponse"},"FrameworkListResponse":{"properties":{"frameworks":{"items":{"$ref":"#/components/schemas/FrameworkResponse"},"type":"array","title":"Frameworks"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["frameworks","total"],"title":"FrameworkListResponse"},"FrameworkResponse":{"properties":{"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"version_tag":{"type":"string","title":"Version Tag"},"docs_url":{"type":"string","title":"Docs Url"},"description":{"type":"string","title":"Description"},"source_hint":{"type":"string","title":"Source Hint"},"last_ingested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Ingested At"}},"type":"object","required":["slug","display_name","version_tag","docs_url","description","source_hint"],"title":"FrameworkResponse"},"GenerateLicenseRequest":{"properties":{"org_id":{"type":"string","maxLength":255,"minLength":1,"title":"Org Id"},"tier":{"type":"string","maxLength":50,"minLength":1,"title":"Tier"},"seats":{"type":"integer","maximum":100000.0,"minimum":1.0,"title":"Seats"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"email":{"type":"string","maxLength":255,"minLength":3,"title":"Email"}},"type":"object","required":["org_id","tier","seats","expires_at","email"],"title":"GenerateLicenseRequest","description":"Body for POST /v1/licenses/generate."},"GenerateLicenseResponse":{"properties":{"license_id":{"type":"string","title":"License Id"},"org_id":{"type":"string","title":"Org Id"},"tier":{"type":"string","title":"Tier"},"seats":{"type":"integer","title":"Seats"},"expires_at":{"type":"string","title":"Expires At"},"license_key":{"type":"string","title":"License Key"},"email_delivery_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Delivery Id"}},"type":"object","required":["license_id","org_id","tier","seats","expires_at","license_key","email_delivery_id"],"title":"GenerateLicenseResponse","description":"Serialized result of a generated self-hosted license."},"GenerateReferralResponse":{"properties":{"referral_code":{"type":"string","title":"Referral Code"},"referral_url":{"type":"string","title":"Referral Url"},"is_new":{"type":"boolean","title":"Is New"}},"type":"object","required":["referral_code","referral_url","is_new"],"title":"GenerateReferralResponse","description":"Response from POST /v1/referrals/generate."},"GithubIntegrationConfig":{"properties":{"token":{"type":"string","title":"Token"},"webhook_secret":{"type":"string","title":"Webhook Secret"},"repo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Repo Url"}},"type":"object","required":["token","webhook_secret"],"title":"GithubIntegrationConfig"},"GrantModeratorBody":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":1,"title":"Reason"}},"type":"object","required":["reason"],"title":"GrantModeratorBody"},"GrantShareRequest":{"properties":{"item_id":{"type":"string","format":"uuid","title":"Item Id"},"peer_id":{"type":"string","format":"uuid","title":"Peer Id"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["item_id","peer_id"],"title":"GrantShareRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HardwareCreateRequest":{"properties":{"vendor_text":{"type":"string","maxLength":100,"title":"Vendor Text"},"model_text":{"type":"string","maxLength":200,"title":"Model Text"},"vram_gb":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Vram Gb"},"hw_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hw Metadata"},"gpu_count":{"type":"integer","exclusiveMinimum":0.0,"title":"Gpu Count","description":"Number of physical GPU cards (default 1)","default":1},"memory_type":{"type":"string","title":"Memory Type","description":"Memory architecture — one of ['discrete_vram', 'system_ram', 'unified_memory']","default":"discrete_vram"},"hardware_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware Class","description":"Hardware ecosystem class — one of ['amd_rocm', 'apple_silicon', 'cpu_only', 'intel_arc', 'nvidia_cuda', 'other']"}},"type":"object","required":["vendor_text","model_text"],"title":"HardwareCreateRequest"},"HardwareResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"vendor_text":{"type":"string","title":"Vendor Text"},"model_text":{"type":"string","title":"Model Text"},"vram_gb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Vram Gb"},"canonical":{"type":"boolean","title":"Canonical"},"hw_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hw Metadata"},"gpu_count":{"type":"integer","title":"Gpu Count","default":1},"memory_type":{"type":"string","title":"Memory Type","default":"discrete_vram"},"hardware_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware Class"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","vendor_text","model_text","vram_gb","canonical","hw_metadata","created_at"],"title":"HardwareResponse"},"HitSourceBreakdown":{"properties":{"exact_hits":{"type":"integer","title":"Exact Hits"},"semantic_hits":{"type":"integer","title":"Semantic Hits"},"misses":{"type":"integer","title":"Misses"}},"type":"object","required":["exact_hits","semantic_hits","misses"],"title":"HitSourceBreakdown","description":"v1.4.0 F5 — exact vs semantic hit breakdown.\n\nThe existing ``semantic_cache`` block collapses both hit types into\none ``hits`` counter. Dashboards that want to distinguish\nbyte-identical hash hits from embedding-distance hits read from\n``by_source``. ``exact_hits`` are cache rows where\n``semantic_cache_distance = 0.0`` (the request-hash fastpath);\n``semantic_hits`` are rows where the embedding-distance fallback\nmatched; ``misses`` is the existing miss counter."},"InboundShareRequestPayload":{"properties":{"from_peer_id":{"type":"string","format":"uuid","title":"From Peer Id"},"target_project_id":{"type":"string","format":"uuid","title":"Target Project Id"},"requested_resource":{"type":"string","title":"Requested Resource"},"request_jws":{"type":"string","title":"Request Jws"}},"type":"object","required":["from_peer_id","target_project_id","requested_resource","request_jws"],"title":"InboundShareRequestPayload","description":"Public POST body for external A2A peers submitting a share request."},"InboxItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"from_peer_id":{"type":"string","title":"From Peer Id"},"target_project_id":{"type":"string","title":"Target Project Id"},"requested_resource":{"type":"string","title":"Requested Resource"},"status":{"type":"string","title":"Status"},"created_at":{"type":"string","title":"Created At"},"decided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided At"},"decided_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided By User Id"}},"type":"object","required":["id","from_peer_id","target_project_id","requested_resource","status","created_at","decided_at","decided_by_user_id"],"title":"InboxItemResponse"},"IncidentCluster":{"properties":{"bucket_start":{"type":"string","title":"Bucket Start"},"status":{"type":"string","title":"Status"},"count":{"type":"integer","title":"Count"},"sample_event_ids":{"items":{"type":"string"},"type":"array","title":"Sample Event Ids"}},"type":"object","required":["bucket_start","status","count","sample_event_ids"],"title":"IncidentCluster","description":"One time-bucketed status cluster."},"IncidentsResponse":{"properties":{"clusters":{"items":{"$ref":"#/components/schemas/IncidentCluster"},"type":"array","title":"Clusters"},"lookback_hours":{"type":"integer","title":"Lookback Hours"},"min_count":{"type":"integer","title":"Min Count"},"total_failures":{"type":"integer","title":"Total Failures"},"total_calls":{"type":"integer","title":"Total Calls","default":0}},"type":"object","required":["clusters","lookback_hours","min_count","total_failures"],"title":"IncidentsResponse"},"IngestErrorResult":{"properties":{"external_id":{"type":"string","title":"External Id"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["external_id","reason"],"title":"IngestErrorResult"},"IngestItemResult":{"properties":{"id":{"type":"string","title":"Id"},"external_id":{"type":"string","title":"External Id"}},"type":"object","required":["id","external_id"],"title":"IngestItemResult"},"IngestRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Raw text content. Mutually exclusive with url."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL to fetch. Mutually exclusive with content."},"type":{"type":"string","enum":["note","document","url","file"],"title":"Type","default":"note"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"is_ephemeral":{"type":"boolean","title":"Is Ephemeral","default":false},"fidelity":{"type":"string","enum":["abstract","outline","balanced","detailed","raw"],"title":"Fidelity","default":"balanced"}},"type":"object","required":["name"],"title":"IngestRequest","description":"POST /v1/projects/{project_id}/knowledge/items body."},"InviteTeamMemberRequest":{"properties":{"email":{"type":"string","maxLength":255,"minLength":3,"title":"Email"},"role":{"type":"string","title":"Role","default":"member"}},"type":"object","required":["email"],"title":"InviteTeamMemberRequest","description":"Body for POST /v1/teams/{id}/invites."},"IssueItem":{"properties":{"type":{"type":"string","title":"Type","description":"hallucination or blind_spot"},"severity":{"type":"string","title":"Severity","description":"low, medium, or high"},"description":{"type":"string","title":"Description"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"}},"type":"object","required":["type","severity","description"],"title":"IssueItem","description":"A single detected issue."},"IssueUploadRequest":{"properties":{"filename":{"type":"string","maxLength":512,"minLength":1,"title":"Filename"},"mime_type":{"type":"string","maxLength":128,"minLength":1,"title":"Mime Type"},"expected_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Expected Bytes"},"idempotency_key":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","required":["filename","mime_type"],"title":"IssueUploadRequest","description":"POST /v1/projects/{project_id}/knowledge/uploads body."},"IssueUploadResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id"},"signed_url":{"type":"string","title":"Signed Url"},"expires_at":{"type":"string","title":"Expires At"},"status":{"type":"string","title":"Status"}},"type":"object","required":["upload_id","signed_url","expires_at","status"],"title":"IssueUploadResponse","description":"201 response for POST /uploads."},"ItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"current_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Version Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner"},"chunk_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunk Count"},"owner_display":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Display"},"owner_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Type"},"mcp_exposed":{"type":"boolean","title":"Mcp Exposed","default":true},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"item_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Status"}},"type":"object","required":["id","name","type","current_version_id","metadata","created_at","updated_at"],"title":"ItemResponse"},"KbEditRequest":{"properties":{"content":{"type":"string","minLength":1,"title":"Content","description":"New text content for the item."},"base_version_id":{"type":"string","title":"Base Version Id","description":"UUID of the current version. Used for optimistic concurrency — if stale, returns 409 with current_version_id."},"force_overwrite":{"type":"boolean","title":"Force Overwrite","description":"When True, bypass the optimistic-concurrency guard.","default":false},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Metadata to merge into the item (top-level keys overwrite)."},"fidelity":{"type":"string","enum":["abstract","outline","balanced","detailed","raw"],"title":"Fidelity","default":"balanced"}},"type":"object","required":["content","base_version_id"],"title":"KbEditRequest","description":"PATCH /v1/kb/items/{item_id} body."},"KbEditResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"}},"type":"object","required":["item_id","version_id"],"title":"KbEditResponse"},"KbIngestRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Human-readable item name."},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Raw text content. Mutually exclusive with url."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL to fetch and ingest. Mutually exclusive with content."},"type":{"type":"string","enum":["note","document","url","file"],"title":"Type","description":"KB item type.","default":"note"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary JSONB metadata."},"is_ephemeral":{"type":"boolean","title":"Is Ephemeral","description":"When True, mark for sweeping.","default":false},"fidelity":{"type":"string","enum":["abstract","outline","balanced","detailed","raw"],"title":"Fidelity","description":"Compression fidelity preset.","default":"balanced"}},"type":"object","required":["name"],"title":"KbIngestRequest","description":"POST /v1/kb/items body."},"KbIngestResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"}},"type":"object","required":["item_id","version_id"],"title":"KbIngestResponse"},"KbItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"current_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Version Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","name","type","current_version_id","metadata","created_at","updated_at"],"title":"KbItemResponse"},"KbListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/KbItemResponse"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items","next_cursor"],"title":"KbListResponse"},"KbQueryChunk":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"},"text":{"type":"string","title":"Text"},"raw_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw Text"},"byte_range":{"items":{"type":"integer"},"type":"array","title":"Byte Range"},"score":{"type":"number","title":"Score"},"score_type":{"type":"string","title":"Score Type","default":"cosine"}},"type":"object","required":["chunk_id","item_id","version_id","text","byte_range","score"],"title":"KbQueryChunk"},"KbQueryRequest":{"properties":{"query_text":{"type":"string","maxLength":8000,"minLength":1,"title":"Query Text"},"k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"K","description":"Number of results (1-100).","default":10},"metadata_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata Filter","description":"Optional JSONB containment filter on item metadata."}},"type":"object","required":["query_text"],"title":"KbQueryRequest","description":"POST /v1/kb/query body."},"KbQueryResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/KbQueryChunk"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"KbQueryResponse"},"KbVersionResponse":{"properties":{"version_id":{"type":"string","title":"Version Id"},"version_n":{"type":"integer","title":"Version N"},"created_at":{"type":"string","title":"Created At"},"from_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Version Id"},"to_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Version Id"},"unified_diff":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unified Diff"}},"type":"object","required":["version_id","version_n","created_at"],"title":"KbVersionResponse"},"KbVersionsResponse":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/KbVersionResponse"},"type":"array","title":"Versions"}},"type":"object","required":["versions"],"title":"KbVersionsResponse"},"KeyListItem":{"properties":{"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"masked_key":{"type":"string","title":"Masked Key"},"created_at":{"type":"string","title":"Created At"},"last_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used"},"status":{"type":"string","title":"Status"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model"},"monthly_quota":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Quota"},"quota_alert_state":{"type":"string","title":"Quota Alert State","default":"none"},"enforce_quota":{"type":"boolean","title":"Enforce Quota","default":false},"current_period_count":{"type":"integer","title":"Current Period Count","default":0},"environment":{"type":"string","title":"Environment","default":"prod"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"replaces_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Replaces Key Id"},"replaced_by_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Replaced By Key Id"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"},"project_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Name"},"cache_invalidated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cache Invalidated"},"scope_model":{"type":"string","title":"Scope Model","default":"legacy"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","default":[]},"denied_scopes":{"items":{"type":"string"},"type":"array","title":"Denied Scopes","default":[]}},"type":"object","required":["key_id","name","masked_key","created_at","last_used","status"],"title":"KeyListItem","description":"A single API key entry in the list response."},"KeyRollupRow":{"properties":{"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"compressions":{"type":"integer","title":"Compressions"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"estimated_savings_usd":{"type":"number","title":"Estimated Savings Usd"}},"type":"object","required":["key_id","name","compressions","tokens_saved","estimated_savings_usd"],"title":"KeyRollupRow","description":"Per-key rollup row.\n\n``estimated_savings_usd`` is computed against the user's most-\ncommon model's input price across the same period. Falls back to\nSonnet 4.6 when the user has no attributed model yet."},"LatencyPercentilesResponse":{"properties":{"window_hours":{"type":"integer","title":"Window Hours"},"count":{"type":"integer","title":"Count"},"p50_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"P50 Ms"},"p95_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"P95 Ms"},"p99_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"P99 Ms"}},"type":"object","required":["window_hours","count","p50_ms","p95_ms","p99_ms"],"title":"LatencyPercentilesResponse","description":"p50/p95/p99 of ``usage_events.latency_ms`` over the requested window."},"LeadResponse":{"properties":{"id":{"type":"string","title":"Id"},"source":{"type":"string","title":"Source"},"status":{"type":"string","title":"Status"}},"type":"object","required":["id","source","status"],"title":"LeadResponse","description":"Serialized result for a created lead."},"LeaderboardEntry":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"public_slug":{"type":"string","title":"Public Slug"},"model_text":{"type":"string","title":"Model Text"},"model_quant_text":{"type":"string","title":"Model Quant Text"},"hardware_text":{"type":"string","title":"Hardware Text"},"hardware_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Hardware Id"},"tokens_per_sec_output":{"type":"number","title":"Tokens Per Sec Output"},"verified_status":{"type":"string","title":"Verified Status"},"submitted_by_agent":{"type":"boolean","title":"Submitted By Agent"},"lens_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lens Value","description":"Value for the selected lens"},"lens_eligible":{"type":"boolean","title":"Lens Eligible","description":"False when required data for lens is missing","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Label"},"feed_item_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Feed Item Id"}},"type":"object","required":["id","public_slug","model_text","model_quant_text","hardware_text","hardware_id","tokens_per_sec_output","verified_status","submitted_by_agent","created_at"],"title":"LeaderboardEntry","description":"A single leaderboard row."},"LeaderboardResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/LeaderboardEntry"},"type":"array","title":"Entries"},"total":{"type":"integer","title":"Total"},"lens":{"type":"string","title":"Lens"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["entries","total","lens"],"title":"LeaderboardResponse"},"LicenseValidationResponse":{"properties":{"license_id":{"type":"string","title":"License Id"},"org_id":{"type":"string","title":"Org Id"},"tier":{"type":"string","title":"Tier"},"seats":{"type":"integer","title":"Seats"},"expires_at":{"type":"string","title":"Expires At"},"grace_expires_at":{"type":"string","title":"Grace Expires At"},"status":{"type":"string","title":"Status"}},"type":"object","required":["license_id","org_id","tier","seats","expires_at","grace_expires_at","status"],"title":"LicenseValidationResponse","description":"Decoded license claims plus the evaluated lifecycle status."},"ListA2APeersResponse":{"properties":{"peers":{"items":{"$ref":"#/components/schemas/A2APeerResponse"},"type":"array","title":"Peers"}},"type":"object","required":["peers"],"title":"ListA2APeersResponse"},"ListInboxResponse":{"properties":{"requests":{"items":{"$ref":"#/components/schemas/InboxItemResponse"},"type":"array","title":"Requests"},"pending_count":{"type":"integer","title":"Pending Count"}},"type":"object","required":["requests","pending_count"],"title":"ListInboxResponse"},"ListItemsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ItemResponse"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items","next_cursor"],"title":"ListItemsResponse"},"ListKeysResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/KeyListItem"},"type":"array","title":"Keys"}},"type":"object","required":["keys"],"title":"ListKeysResponse","description":"List of API keys for the authenticated user."},"ListMcpClientsResponse":{"properties":{"clients":{"items":{"$ref":"#/components/schemas/McpClientSummaryOut"},"type":"array","title":"Clients"}},"type":"object","required":["clients"],"title":"ListMcpClientsResponse"},"ListMembershipsResponse":{"properties":{"memberships":{"items":{"$ref":"#/components/schemas/MembershipResponse"},"type":"array","title":"Memberships"}},"type":"object","required":["memberships"],"title":"ListMembershipsResponse"},"ListSavedViewsResponse":{"properties":{"views":{"items":{"$ref":"#/components/schemas/SavedView"},"type":"array","title":"Views"}},"type":"object","required":["views"],"title":"ListSavedViewsResponse"},"ListSharesResponse":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/ShareResponse"},"type":"array","title":"Shares"}},"type":"object","required":["shares"],"title":"ListSharesResponse"},"ListTestKeysResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/TestKeyListItem"},"type":"array","title":"Keys"}},"type":"object","required":["keys"],"title":"ListTestKeysResponse"},"ListUsersResponse":{"properties":{"users":{"items":{"$ref":"#/components/schemas/AdminUserItem"},"type":"array","title":"Users"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["users","total"],"title":"ListUsersResponse"},"MarkUploadCompleteRequest":{"properties":{"actual_mime":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Actual Mime"},"actual_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Actual Bytes"},"content_hash":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Content Hash"}},"type":"object","title":"MarkUploadCompleteRequest","description":"POST /v1/projects/{project_id}/knowledge/uploads/{upload_id}/complete body."},"McpClientSummaryOut":{"properties":{"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"last_active_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Active At"},"call_count_30d":{"type":"integer","title":"Call Count 30D"},"kb_item_allowlist":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Kb Item Allowlist"},"tool_allowlist":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tool Allowlist"}},"type":"object","required":["key_id","name","call_count_30d"],"title":"McpClientSummaryOut"},"McpReloadResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"previous_count":{"type":"integer","title":"Previous Count"},"current_count":{"type":"integer","title":"Current Count"},"added":{"items":{"type":"string"},"type":"array","title":"Added"},"removed":{"items":{"type":"string"},"type":"array","title":"Removed"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["success","previous_count","current_count","added","removed"],"title":"McpReloadResponse"},"McpToolsResponse":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/ToolInfo"},"type":"array","title":"Tools"},"total":{"type":"integer","title":"Total"},"plan":{"type":"string","title":"Plan"},"available_count":{"type":"integer","title":"Available Count"}},"type":"object","required":["tools","total","plan","available_count"],"title":"McpToolsResponse"},"MembershipResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"owner_project_id":{"type":"string","title":"Owner Project Id"},"member_project_id":{"type":"string","title":"Member Project Id"},"added_at":{"type":"string","title":"Added At"},"added_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Added By"}},"type":"object","required":["item_id","owner_project_id","member_project_id","added_at","added_by"],"title":"MembershipResponse","description":"A single membership row serialised for the API response."},"MeterUsageResponse":{"properties":{"count":{"type":"integer","title":"Count"},"event_name":{"type":"string","title":"Event Name"},"period":{"type":"string","title":"Period"},"degraded":{"type":"boolean","title":"Degraded","default":false}},"type":"object","required":["count","event_name","period"],"title":"MeterUsageResponse","description":"Current-period metered-usage count for the authenticated user."},"MeteringAcceptedResponse":{"properties":{"status":{"type":"string","title":"Status"},"org_id":{"type":"string","title":"Org Id"},"license_status":{"type":"string","title":"License Status"}},"type":"object","required":["status","org_id","license_status"],"title":"MeteringAcceptedResponse","description":"Acknowledgement of a persisted metering report."},"MeteringReportRequest":{"properties":{"org_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Org Id"},"compressions":{"type":"integer","minimum":0.0,"title":"Compressions"},"tokens":{"type":"integer","minimum":0.0,"title":"Tokens"},"active_users":{"type":"integer","minimum":0.0,"title":"Active Users"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"}},"type":"object","required":["compressions","tokens","active_users","period_start","period_end"],"title":"MeteringReportRequest","description":"Body for POST /v1/metering."},"ModelListItem":{"properties":{"model":{"type":"string","title":"Model"},"provider":{"type":"string","title":"Provider"},"input_per_1k":{"type":"number","title":"Input Per 1K","description":"USD per 1k input tokens."},"output_per_1k":{"type":"number","title":"Output Per 1K","description":"USD per 1k output tokens."}},"type":"object","required":["model","provider","input_per_1k","output_per_1k"],"title":"ModelListItem"},"ModelListResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ModelListItem"},"type":"array","title":"Models"}},"type":"object","required":["models"],"title":"ModelListResponse"},"ModelRollupItem":{"properties":{"model":{"type":"string","title":"Model"},"model_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Source"},"compressions":{"type":"integer","title":"Compressions"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"estimated_cost_saved_usd":{"type":"number","title":"Estimated Cost Saved Usd"}},"type":"object","required":["model","model_source","compressions","tokens_in","tokens_saved","estimated_cost_saved_usd"],"title":"ModelRollupItem"},"ModerateRequest":{"properties":{"action":{"type":"string","pattern":"^(approve|reject)$","title":"Action"}},"type":"object","required":["action"],"title":"ModerateRequest","description":"Request body for POST /v1/benchmarks/comments/{comment_id}/moderate."},"ModerationQueueResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CommentResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["items","total"],"title":"ModerationQueueResponse","description":"Response shape for GET /v1/benchmarks/moderation-queue."},"ModeratorReasonBody":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":1,"title":"Reason"}},"type":"object","required":["reason"],"title":"ModeratorReasonBody"},"MultiLevelOutput":{"properties":{"headline":{"type":"string","title":"Headline","description":"~10% kept — navigation-level summary"},"summary":{"type":"string","title":"Summary","description":"~30% kept — key points preserved"},"full":{"type":"string","title":"Full","description":"Compressed at the requested fidelity level"}},"type":"object","required":["headline","summary","full"],"title":"MultiLevelOutput","description":"Three compression tiers returned by multi_level mode."},"NewsArticleDetail":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"body_md":{"type":"string","title":"Body Md"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"category":{"type":"string","title":"Category"},"status":{"type":"string","title":"Status"},"author_clerk_id":{"type":"string","title":"Author Clerk Id"},"published_at":{"type":"string","title":"Published At"},"hero_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hero Image Url"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Attribution"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","slug","title","body_md","excerpt","category","status","author_clerk_id","published_at","hero_image_url","source_url","source_attribution","created_at","updated_at"],"title":"NewsArticleDetail","description":"Full article shape for the detail endpoint."},"NewsArticleListItem":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"category":{"type":"string","title":"Category"},"status":{"type":"string","title":"Status"},"author_clerk_id":{"type":"string","title":"Author Clerk Id"},"published_at":{"type":"string","title":"Published At"},"hero_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hero Image Url"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Attribution"}},"type":"object","required":["id","slug","title","excerpt","category","status","author_clerk_id","published_at","hero_image_url","source_url","source_attribution"],"title":"NewsArticleListItem","description":"Compact article shape for the listing endpoint."},"NewsCategoryItem":{"properties":{"category":{"type":"string","title":"Category"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["category","count"],"title":"NewsCategoryItem"},"NewsListResponse":{"properties":{"articles":{"items":{"$ref":"#/components/schemas/NewsArticleListItem"},"type":"array","title":"Articles"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["articles","next_cursor"],"title":"NewsListResponse"},"NewsSubscribeRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"source":{"type":"string","maxLength":64,"title":"Source","description":"Capture surface — 'inline-form', 'subscribe-page', 'rss-fallback'","default":"inline-form"},"website":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Website","description":"Honeypot — humans leave this blank; bots fill it"}},"type":"object","required":["email"],"title":"NewsSubscribeRequest"},"NewsSubscribeResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["ok","detail"],"title":"NewsSubscribeResponse"},"NotificationItem":{"properties":{"id":{"type":"string","title":"Id"},"type":{"type":"string","title":"Type"},"actor_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Username"},"target_type":{"type":"string","title":"Target Type"},"target_id":{"type":"string","title":"Target Id"},"body":{"type":"string","title":"Body"},"is_read":{"type":"boolean","title":"Is Read"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","type","target_type","target_id","body","is_read","created_at"],"title":"NotificationItem","description":"A single user_activity_notification row (for the notifications-only list)."},"NotificationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"severity":{"type":"string","title":"Severity"},"category":{"type":"string","title":"Category"},"title":{"type":"string","title":"Title"},"message":{"type":"string","title":"Message"},"target":{"type":"string","title":"Target"},"dismissible":{"type":"boolean","title":"Dismissible"},"starts_at":{"type":"string","format":"date-time","title":"Starts At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","severity","category","title","message","target","dismissible","starts_at","expires_at","created_by","created_at"],"title":"NotificationResponse"},"NotificationsResponse":{"properties":{"notifications":{"items":{"$ref":"#/components/schemas/NotificationItem"},"type":"array","title":"Notifications"},"unread_count":{"type":"integer","title":"Unread Count"}},"type":"object","required":["notifications","unread_count"],"title":"NotificationsResponse"},"OrderItem":{"properties":{"id":{"type":"string","title":"Id"},"amount_cents":{"type":"integer","title":"Amount Cents"},"currency":{"type":"string","title":"Currency"},"status":{"type":"string","title":"Status"},"invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Number"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","amount_cents","currency","status","created_at"],"title":"OrderItem","description":"A single Polar order record."},"OveragePreviewResponse":{"properties":{"plan":{"type":"string","title":"Plan"},"included_units":{"type":"integer","title":"Included Units"},"used_units":{"type":"integer","title":"Used Units"},"overage_units":{"type":"integer","title":"Overage Units"},"unit_amount_cents":{"type":"integer","title":"Unit Amount Cents"},"overage_cost_cents":{"type":"integer","title":"Overage Cost Cents"},"cap_amount_cents":{"type":"integer","title":"Cap Amount Cents"},"billed_cost_cents":{"type":"integer","title":"Billed Cost Cents"},"currency":{"type":"string","title":"Currency","default":"usd"},"period":{"type":"string","title":"Period"},"degraded":{"type":"boolean","title":"Degraded","default":false}},"type":"object","required":["plan","included_units","used_units","overage_units","unit_amount_cents","overage_cost_cents","cap_amount_cents","billed_cost_cents","period"],"title":"OveragePreviewResponse","description":"Projected overage cost for the current billing period."},"PatchDraftRequest":{"properties":{"draft_title":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Draft Title"},"draft_body_md":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Draft Body Md"},"draft_excerpt":{"anyOf":[{"type":"string","maxLength":220},{"type":"null"}],"title":"Draft Excerpt"},"draft_category":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Draft Category"}},"type":"object","title":"PatchDraftRequest","description":"Partial update for a draft item."},"PatchDraftResponse":{"properties":{"id":{"type":"string","title":"Id"},"draft_status":{"type":"string","title":"Draft Status"},"draft_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Title"},"draft_excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Excerpt"},"draft_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Category"}},"type":"object","required":["id","draft_status","draft_title","draft_excerpt","draft_category"],"title":"PatchDraftResponse"},"PatchUserBody":{"properties":{"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan","description":"New billing plan for the user."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"New account status: active | flagged | disabled."}},"type":"object","title":"PatchUserBody","description":"Payload for PATCH /v1/admin/users/v2/{id}.\n\nAt least one of plan / status must be provided. The endpoint rejects\na body with neither field set (HTTP 422)."},"PercentileResponse":{"properties":{"percentile":{"type":"number","title":"Percentile"},"tier":{"type":"string","title":"Tier"},"count":{"type":"integer","title":"Count"},"metric_name":{"type":"string","title":"Metric Name"}},"type":"object","required":["percentile","tier","count","metric_name"],"title":"PercentileResponse","description":"Response shape for GET /v1/benchmarks/runs/{run_id}/percentile."},"PortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url"}},"type":"object","required":["portal_url"],"title":"PortalResponse","description":"Response containing the Polar customer portal URL."},"PreviewResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"candidates":{"items":{"$ref":"#/components/schemas/CandidateRow"},"type":"array","title":"Candidates"},"skipped_opt_out":{"type":"integer","title":"Skipped Opt Out"},"total_projected_savings_usd":{"type":"number","title":"Total Projected Savings Usd"}},"type":"object","required":["period_days","candidates","skipped_opt_out","total_projected_savings_usd"],"title":"PreviewResponse"},"ProfileListResponse":{"properties":{"profiles":{"items":{"$ref":"#/components/schemas/ProfileResponse"},"type":"array","title":"Profiles"}},"type":"object","required":["profiles"],"title":"ProfileListResponse","description":"List of fidelity profiles."},"ProfileResponse":{"properties":{"id":{"type":"integer","title":"Id"},"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"fidelity":{"type":"string","title":"Fidelity"},"chunk_size":{"type":"integer","title":"Chunk Size"},"skeleton_ratio":{"type":"number","title":"Skeleton Ratio"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","user_id","name","fidelity","chunk_size","skeleton_ratio","description","created_at"],"title":"ProfileResponse","description":"A single fidelity profile."},"ProjectDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"current_period_compressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Period Compressions"},"is_default":{"type":"boolean","title":"Is Default","default":false},"total_compressions":{"type":"integer","title":"Total Compressions"},"total_tokens_in":{"type":"integer","title":"Total Tokens In"},"total_tokens_saved":{"type":"integer","title":"Total Tokens Saved"},"batch_job_count":{"type":"integer","title":"Batch Job Count"}},"type":"object","required":["id","user_id","name","description","created_at","updated_at","total_compressions","total_tokens_in","total_tokens_saved","batch_job_count"],"title":"ProjectDetailResponse","description":"Project with aggregated usage stats."},"ProjectListResponse":{"properties":{"projects":{"items":{"$ref":"#/components/schemas/ProjectResponse"},"type":"array","title":"Projects"}},"type":"object","required":["projects"],"title":"ProjectListResponse","description":"List of projects."},"ProjectModelBreakdown":{"properties":{"model":{"type":"string","title":"Model"},"count":{"type":"integer","title":"Count"},"savings_pct":{"type":"number","title":"Savings Pct"}},"type":"object","required":["model","count","savings_pct"],"title":"ProjectModelBreakdown","description":"Per-model usage breakdown for the current period."},"ProjectResponse":{"properties":{"id":{"type":"string","title":"Id"},"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"current_period_compressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Period Compressions"},"is_default":{"type":"boolean","title":"Is Default","default":false}},"type":"object","required":["id","user_id","name","description","created_at","updated_at"],"title":"ProjectResponse","description":"A single project."},"ProjectSummary":{"properties":{"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"},"project_name":{"type":"string","title":"Project Name"},"compressions":{"type":"integer","title":"Compressions"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"savings_pct":{"type":"number","title":"Savings Pct"},"estimated_cost_saved_usd":{"type":"number","title":"Estimated Cost Saved Usd"}},"type":"object","required":["project_id","project_name","compressions","tokens_in","tokens_saved","savings_pct","estimated_cost_saved_usd"],"title":"ProjectSummary"},"ProjectUsageResponse":{"properties":{"project_id":{"type":"string","title":"Project Id"},"project_name":{"type":"string","title":"Project Name"},"period":{"type":"string","title":"Period"},"period_start":{"type":"string","title":"Period Start"},"period_end":{"type":"string","title":"Period End"},"compressions_used":{"type":"integer","title":"Compressions Used"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"plan":{"type":"string","title":"Plan","default":"free"},"compressions_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Compressions Limit"},"models":{"items":{"$ref":"#/components/schemas/ProjectModelBreakdown"},"type":"array","title":"Models"}},"type":"object","required":["project_id","project_name","period","period_start","period_end","compressions_used","tokens_in","tokens_saved"],"title":"ProjectUsageResponse","description":"Project-scoped usage for the current calendar month."},"PromoteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"canonical":{"type":"boolean","title":"Canonical"},"approved_by_admin":{"type":"boolean","title":"Approved By Admin"},"message":{"type":"string","title":"Message"}},"type":"object","required":["id","canonical","approved_by_admin","message"],"title":"PromoteResponse"},"PublishArticleRequest":{"properties":{"title":{"type":"string","maxLength":512,"minLength":1,"title":"Title"},"body_md":{"type":"string","minLength":1,"title":"Body Md"},"category":{"type":"string","maxLength":64,"minLength":1,"title":"Category"},"news_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"News Item Id"},"slug":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Slug"},"excerpt":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Excerpt"},"hero_image_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Hero Image Url"},"source_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Source Url"},"source_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Attribution"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["title","body_md","category"],"title":"PublishArticleRequest"},"PublishArticleResponse":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"published_at":{"type":"string","title":"Published At"},"url":{"type":"string","title":"Url"}},"type":"object","required":["id","slug","published_at","url"],"title":"PublishArticleResponse"},"PushSubscribeRequest":{"properties":{"endpoint":{"type":"string","title":"Endpoint"},"expirationTime":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expirationtime"},"keys":{"$ref":"#/components/schemas/PushSubscriptionKeys"}},"type":"object","required":["endpoint","keys"],"title":"PushSubscribeRequest","description":"Body of POST /v1/push/subscribe.\n\nMirrors PushSubscription.toJSON() exactly so the browser can call:\n fetch('/v1/push/subscribe', {method:'POST', body: JSON.stringify(subscription.toJSON())})"},"PushSubscriptionKeys":{"properties":{"p256dh":{"type":"string","title":"P256Dh"},"auth":{"type":"string","title":"Auth"}},"type":"object","required":["p256dh","auth"],"title":"PushSubscriptionKeys","description":"Nested keys block from W3C PushSubscription.toJSON()."},"PushUnsubscribeRequest":{"properties":{"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["endpoint"],"title":"PushUnsubscribeRequest","description":"Body of DELETE /v1/push/subscribe."},"QueryRequest":{"properties":{"query_text":{"type":"string","maxLength":8000,"minLength":1,"title":"Query Text"},"k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"K","default":10},"metadata_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata Filter"}},"type":"object","required":["query_text"],"title":"QueryRequest"},"QueryResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/QueryResultChunk"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"QueryResponse"},"QueryResultChunk":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"},"text":{"type":"string","title":"Text"},"byte_range":{"items":{"type":"integer"},"type":"array","title":"Byte Range"},"score":{"type":"number","title":"Score"},"raw_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw Text"}},"type":"object","required":["chunk_id","item_id","version_id","text","byte_range","score"],"title":"QueryResultChunk"},"RankedContextItem":{"properties":{"path":{"type":"string","title":"Path"},"score":{"type":"number","title":"Score"},"rank":{"type":"integer","title":"Rank"},"contributing_signals":{"items":{"type":"string"},"type":"array","title":"Contributing Signals"}},"type":"object","required":["path","score","rank","contributing_signals"],"title":"RankedContextItem"},"RecommendRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to analyse for recommendation"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Target model name (e.g. claude-sonnet-4-6). Used to check context fit."},"context_window":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Context Window","description":"Override context window size in tokens. Takes precedence over the model-derived value."}},"type":"object","required":["text"],"title":"RecommendRequest","description":"Request body for fidelity recommendation."},"RecommendResponse":{"properties":{"recommended_fidelity":{"type":"string","title":"Recommended Fidelity"},"estimated_ratio":{"type":"number","title":"Estimated Ratio"},"estimated_output_tokens":{"type":"integer","title":"Estimated Output Tokens"},"original_tokens":{"type":"integer","title":"Original Tokens"},"reasoning":{"type":"string","title":"Reasoning"}},"type":"object","required":["recommended_fidelity","estimated_ratio","estimated_output_tokens","original_tokens","reasoning"],"title":"RecommendResponse","description":"Fidelity recommendation result."},"ReferralItem":{"properties":{"id":{"type":"integer","title":"Id"},"referral_code":{"type":"string","title":"Referral Code"},"referred_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referred User Id"},"status":{"type":"string","title":"Status"},"credit_days":{"type":"integer","title":"Credit Days"},"created_at":{"type":"string","title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","referral_code","referred_user_id","status","credit_days","created_at","completed_at"],"title":"ReferralItem","description":"A single referral entry."},"ReferralListResponse":{"properties":{"referrals":{"items":{"$ref":"#/components/schemas/ReferralItem"},"type":"array","title":"Referrals"}},"type":"object","required":["referrals"],"title":"ReferralListResponse","description":"List of referrals created by the caller."},"ReferralMilestone":{"properties":{"referrals_needed":{"type":"integer","title":"Referrals Needed"},"reward":{"type":"string","title":"Reward"},"reached":{"type":"boolean","title":"Reached"}},"type":"object","required":["referrals_needed","reward","reached"],"title":"ReferralMilestone","description":"A referral milestone tier."},"ReferralStatsResponse":{"properties":{"total_referred":{"type":"integer","title":"Total Referred"},"credits_earned_days":{"type":"integer","title":"Credits Earned Days"},"pending":{"type":"integer","title":"Pending"},"milestones":{"items":{"$ref":"#/components/schemas/ReferralMilestone"},"type":"array","title":"Milestones","default":[]}},"type":"object","required":["total_referred","credits_earned_days","pending"],"title":"ReferralStatsResponse","description":"Aggregate stats for the caller's referral program."},"ReindexResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"},"status":{"type":"string","title":"Status","default":"COMPLETE"}},"type":"object","required":["item_id","version_id"],"title":"ReindexResponse"},"RejectRequest":{"properties":{"reason":{"type":"string","minLength":1,"title":"Reason"}},"type":"object","required":["reason"],"title":"RejectRequest"},"RejectResponse":{"properties":{"id":{"type":"string","title":"Id"},"draft_status":{"type":"string","title":"Draft Status"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"}},"type":"object","required":["id","draft_status","reviewed_at"],"title":"RejectResponse"},"RemoveMembershipResponse":{"properties":{"removed":{"type":"boolean","title":"Removed"},"item_id":{"type":"string","title":"Item Id"},"member_project_id":{"type":"string","title":"Member Project Id"}},"type":"object","required":["removed","item_id","member_project_id"],"title":"RemoveMembershipResponse"},"ReportCommentRequest":{"properties":{"reason":{"type":"string","pattern":"^(spam|inappropriate|illegal|other)$","title":"Reason"},"detail":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Detail"}},"type":"object","required":["reason"],"title":"ReportCommentRequest"},"ResolveReportBody":{"properties":{"action":{"type":"string","pattern":"^(resolved|ignored)$","title":"Action"},"reason":{"type":"string","maxLength":1000,"minLength":1,"title":"Reason"}},"type":"object","required":["action","reason"],"title":"ResolveReportBody"},"RetentionPolicyRequest":{"properties":{"retention_days":{"anyOf":[{"type":"integer","maximum":3650.0,"minimum":1.0},{"type":"null"}],"title":"Retention Days"},"legal_hold_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Hold Until","description":"ISO-8601 timestamp"}},"type":"object","title":"RetentionPolicyRequest"},"RetentionPolicyResponse":{"properties":{"project_id":{"type":"string","title":"Project Id"},"retention_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retention Days"},"legal_hold_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Hold Until"}},"type":"object","required":["project_id"],"title":"RetentionPolicyResponse"},"RevokeKeyResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"key_id":{"type":"string","title":"Key Id"}},"type":"object","required":["success","key_id"],"title":"RevokeKeyResponse","description":"Confirmation of key revocation."},"RotateKeyRequest":{"properties":{"grace_period_days":{"type":"integer","maximum":30.0,"minimum":0.0,"title":"Grace Period Days","description":"Days the predecessor key remains valid after rotation (0-30). Default 7. ``0`` immediately expires the predecessor (panic rotate).","default":7},"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Name"}},"type":"object","title":"RotateKeyRequest","description":"Request body for ``POST /v1/keys/{key_id}/rotate`` (v1.20.10).\n\nBoth fields are optional. ``grace_period_days`` defaults to 7 (Stripe-\nstyle SaaS norm). ``name`` defaults to ``\" (rotated\nYYYY-MM-DD)\"`` when omitted."},"RotateKeyResponse":{"properties":{"key":{"type":"string","title":"Key"},"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"created_at":{"type":"string","title":"Created At"},"environment":{"type":"string","title":"Environment"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model"},"predecessor_key_id":{"type":"string","title":"Predecessor Key Id"},"predecessor_expires_at":{"type":"string","title":"Predecessor Expires At"},"grace_period_days":{"type":"integer","title":"Grace Period Days"}},"type":"object","required":["key","key_id","name","created_at","environment","predecessor_key_id","predecessor_expires_at","grace_period_days"],"title":"RotateKeyResponse","description":"Response after rotating an API key (v1.20.10).\n\nThe ``key`` field contains the full plaintext successor — shown ONCE\nand cannot be retrieved again. The predecessor continues to\nauthenticate until ``predecessor_expires_at``."},"SavedView":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"filters":{"additionalProperties":true,"type":"object","title":"Filters"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","name","filters","created_at"],"title":"SavedView"},"SavingsResponse":{"properties":{"total_compressions":{"type":"integer","title":"Total Compressions"},"total_tokens_in":{"type":"integer","title":"Total Tokens In"},"total_tokens_saved":{"type":"integer","title":"Total Tokens Saved"},"savings_pct":{"type":"number","title":"Savings Pct"},"estimated_cost_saved_usd":{"type":"number","title":"Estimated Cost Saved Usd"},"model":{"type":"string","title":"Model","description":"Canonical model name used for cost math."},"price_per_1k_in":{"type":"number","title":"Price Per 1K In","description":"USD per 1k input tokens."},"price_per_1k_out":{"type":"number","title":"Price Per 1K Out","description":"USD per 1k output tokens."}},"type":"object","required":["total_compressions","total_tokens_in","total_tokens_saved","savings_pct","estimated_cost_saved_usd","model","price_per_1k_in","price_per_1k_out"],"title":"SavingsResponse","description":"Cumulative compression savings for the authenticated user."},"SemanticCacheRollup":{"properties":{"hits":{"type":"integer","title":"Hits"},"misses":{"type":"integer","title":"Misses"},"hit_rate":{"type":"number","title":"Hit Rate"},"tokens_saved_via_hits":{"type":"integer","title":"Tokens Saved Via Hits"},"usd_saved_via_hits":{"type":"number","title":"Usd Saved Via Hits"}},"type":"object","required":["hits","misses","hit_rate","tokens_saved_via_hits","usd_saved_via_hits"],"title":"SemanticCacheRollup","description":"v1.3 — rollup of the semantic dedup cache hit rate + savings.\n\n``hits``/``misses`` sum over the window's ``UsageEvent`` rows; free\ntier and pre-v1.3 rows are ``NULL`` in ``semantic_cache_status``\nand excluded from both counts. ``hit_rate`` is a fraction in\n``[0, 1]``. ``tokens_saved_via_hits`` is the ``tokens_saved`` sum\non hit rows; ``usd_saved_via_hits`` multiplies that by the user's\nmost-common-model input price (same basis as ``compression_only``)."},"ShareResponse":{"properties":{"id":{"type":"string","title":"Id"},"item_id":{"type":"string","title":"Item Id"},"owner_project_id":{"type":"string","title":"Owner Project Id"},"peer_id":{"type":"string","title":"Peer Id"},"manifest_jws":{"type":"string","title":"Manifest Jws"},"status":{"type":"string","title":"Status"},"granted_at":{"type":"string","title":"Granted At"},"granted_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Granted By User Id"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At"}},"type":"object","required":["id","item_id","owner_project_id","peer_id","manifest_jws","status","granted_at","granted_by_user_id","expires_at","revoked_at"],"title":"ShareResponse"},"SilenceUserBody":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":1,"title":"Reason"},"duration_hours":{"anyOf":[{"type":"integer","maximum":720.0,"minimum":1.0},{"type":"null"}],"title":"Duration Hours"}},"type":"object","required":["reason"],"title":"SilenceUserBody"},"SingleItemIngestRequest":{"properties":{"source_slug":{"type":"string","maxLength":64,"minLength":1,"title":"Source Slug"},"external_id":{"type":"string","maxLength":256,"minLength":1,"title":"External Id"},"url":{"type":"string","maxLength":2048,"minLength":1,"title":"Url"},"title":{"type":"string","maxLength":512,"minLength":1,"title":"Title"},"raw_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw Summary"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["source_slug","external_id","url","title"],"title":"SingleItemIngestRequest"},"StatusChangeResponse":{"properties":{"clerk_id":{"type":"string","title":"Clerk Id"},"previous_status":{"type":"string","title":"Previous Status"},"new_status":{"type":"string","title":"New Status"},"changed_at":{"type":"string","title":"Changed At"}},"type":"object","required":["clerk_id","previous_status","new_status","changed_at"],"title":"StatusChangeResponse"},"StatusTransitionRequest":{"properties":{"status":{"type":"string","enum":["draft","in_review","approved"],"title":"Status"}},"type":"object","required":["status"],"title":"StatusTransitionRequest"},"StatusTransitionResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["item_id","status"],"title":"StatusTransitionResponse"},"StructuralCompressRequest":{"properties":{"files":{"items":{"$ref":"#/components/schemas/StructuralFile"},"type":"array","title":"Files","description":"The code bundle to analyse. 1–1000 files, ≤512 KB each, ≤5 MB total."},"focus_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Symbol","description":"Symbol name to focus the blast-radius on. When omitted, tg returns the global map — still useful for BM25-only ranking."},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Free-form query used as the BM25 input. Defaults to focus_symbol."},"top_k":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Top K","description":"Cap on the size of the returned ranked_context list.","default":50}},"type":"object","title":"StructuralCompressRequest"},"StructuralCompressResponse":{"properties":{"ranked_context":{"items":{"$ref":"#/components/schemas/RankedContextItem"},"type":"array","title":"Ranked Context"},"stats":{"$ref":"#/components/schemas/StructuralCompressStats"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Populated only on degraded paths (missing tg, timeout, non-zero exit)."}},"type":"object","required":["ranked_context","stats"],"title":"StructuralCompressResponse"},"StructuralCompressStats":{"properties":{"files_in":{"type":"integer","title":"Files In"},"files_ranked":{"type":"integer","title":"Files Ranked"},"symbols_in":{"type":"integer","title":"Symbols In"},"degraded":{"type":"boolean","title":"Degraded"}},"type":"object","required":["files_in","files_ranked","symbols_in","degraded"],"title":"StructuralCompressStats"},"StructuralFile":{"properties":{"path":{"type":"string","minLength":1,"title":"Path","description":"POSIX-style relative path within the submitted tree."},"content":{"type":"string","title":"Content","description":"File content as UTF-8 text."}},"type":"object","required":["path","content"],"title":"StructuralFile"},"SubscribeResponse":{"properties":{"status":{"type":"string","title":"Status"}},"type":"object","required":["status"],"title":"SubscribeResponse"},"SubscriptionInfo":{"properties":{"plan":{"type":"string","title":"Plan"},"renewal_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Renewal At"},"amount_cents":{"type":"integer","title":"Amount Cents"},"currency":{"type":"string","title":"Currency"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"trial_ends_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trial Ends At"}},"type":"object","required":["plan","amount_cents","currency"],"title":"SubscriptionInfo","description":"Current plan and subscription billing details."},"TeamActivityEntry":{"properties":{"id":{"type":"string","title":"Id"},"action":{"type":"string","title":"Action"},"actor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Id"},"actor_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Email"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","action","actor_id","actor_email","target_id","metadata","created_at"],"title":"TeamActivityEntry","description":"Single audit log entry for a team."},"TeamActivityResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/TeamActivityEntry"},"type":"array","title":"Entries"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["entries","total"],"title":"TeamActivityResponse","description":"Paginated team activity log."},"TeamInviteResponse":{"properties":{"invite":{"$ref":"#/components/schemas/TeamMembershipResponse"},"email_delivery_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Delivery Id"},"email_delivery_status":{"type":"string","title":"Email Delivery Status","default":"sent"}},"type":"object","required":["invite","email_delivery_id"],"title":"TeamInviteResponse","description":"Created invite row plus email delivery metadata."},"TeamListResponse":{"properties":{"teams":{"items":{"$ref":"#/components/schemas/TeamWithMembershipResponse"},"type":"array","title":"Teams"}},"type":"object","required":["teams"],"title":"TeamListResponse","description":"List of teams available to the caller."},"TeamMembersResponse":{"properties":{"members":{"items":{"$ref":"#/components/schemas/TeamMembershipResponse"},"type":"array","title":"Members"}},"type":"object","required":["members"],"title":"TeamMembersResponse","description":"Full member roster for a team, including pending invites."},"TeamMembershipResponse":{"properties":{"id":{"type":"string","title":"Id"},"team_id":{"type":"string","title":"Team Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"invited_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invited Email"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","team_id","user_id","role","status","invited_email","expires_at","created_at"],"title":"TeamMembershipResponse","description":"Serialized team membership or invite."},"TeamResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"owner_id":{"type":"string","title":"Owner Id"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","name","owner_id","created_at"],"title":"TeamResponse","description":"Serialized team details."},"TeamTransferResponse":{"properties":{"team":{"$ref":"#/components/schemas/TeamResponse"},"previous_owner_membership":{"$ref":"#/components/schemas/TeamMembershipResponse"},"new_owner_membership":{"$ref":"#/components/schemas/TeamMembershipResponse"}},"type":"object","required":["team","previous_owner_membership","new_owner_membership"],"title":"TeamTransferResponse","description":"Ownership transfer result."},"TeamUsageMemberResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"role":{"type":"string","title":"Role"},"total_compressions":{"type":"integer","title":"Total Compressions"},"total_tokens_in":{"type":"integer","title":"Total Tokens In"},"total_tokens_saved":{"type":"integer","title":"Total Tokens Saved"}},"type":"object","required":["user_id","email","role","total_compressions","total_tokens_in","total_tokens_saved"],"title":"TeamUsageMemberResponse","description":"Usage aggregation for one active member."},"TeamUsageResponse":{"properties":{"team_id":{"type":"string","title":"Team Id"},"total_tokens_in":{"type":"integer","title":"Total Tokens In"},"total_tokens_saved":{"type":"integer","title":"Total Tokens Saved"},"total_compressions":{"type":"integer","title":"Total Compressions"},"by_member":{"items":{"$ref":"#/components/schemas/TeamUsageMemberResponse"},"type":"array","title":"By Member"}},"type":"object","required":["team_id","total_tokens_in","total_tokens_saved","total_compressions","by_member"],"title":"TeamUsageResponse","description":"Team-wide aggregated usage plus per-member breakdown."},"TeamWithMembershipResponse":{"properties":{"team":{"$ref":"#/components/schemas/TeamResponse"},"membership":{"$ref":"#/components/schemas/TeamMembershipResponse"}},"type":"object","required":["team","membership"],"title":"TeamWithMembershipResponse","description":"Team plus the caller-specific membership context."},"TestKeyListItem":{"properties":{"key_id":{"type":"string","title":"Key Id"},"name":{"type":"string","title":"Name"},"plan":{"type":"string","title":"Plan"},"created_by_admin_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Admin Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"last_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used"},"status":{"type":"string","title":"Status"}},"type":"object","required":["key_id","name","plan","created_by_admin_id","created_at","expires_at","last_used","status"],"title":"TestKeyListItem"},"TestKeyUsageResponse":{"properties":{"compressions":{"type":"integer","title":"Compressions"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"last_7_days_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Last 7 Days Events"}},"type":"object","required":["compressions","tokens_in","tokens_saved","last_7_days_events"],"title":"TestKeyUsageResponse"},"TestPushResponse":{"properties":{"sent":{"type":"integer","title":"Sent"},"status":{"type":"string","title":"Status"}},"type":"object","required":["sent","status"],"title":"TestPushResponse"},"TestWebhookResponse":{"properties":{"delivery":{"$ref":"#/components/schemas/WebhookDeliveryResponse"}},"type":"object","required":["delivery"],"title":"TestWebhookResponse","description":"Immediate result from a manual test ping."},"ThresholdPutRequest":{"properties":{"threshold":{"anyOf":[{"type":"number","maximum":0.99,"minimum":0.8},{"type":"null"}],"title":"Threshold","description":"Cosine similarity cutoff in [0.80, 0.99]; null resets to the server-wide default (currently ~0.95)."}},"type":"object","title":"ThresholdPutRequest"},"ThresholdResponse":{"properties":{"threshold":{"type":"number","maximum":0.99,"minimum":0.8,"title":"Threshold"},"source":{"type":"string","enum":["user","global"],"title":"Source"}},"type":"object","required":["threshold","source"],"title":"ThresholdResponse"},"ToggleWebhookResponse":{"properties":{"id":{"type":"string","title":"Id"},"is_active":{"type":"boolean","title":"Is Active"}},"type":"object","required":["id","is_active"],"title":"ToggleWebhookResponse","description":"Result of enable/disable toggle."},"ToolAllowlistBody":{"properties":{"tool_allowlist":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Tool Allowlist","description":"List of MCP tool names to allow for this project. The gateway intersects this with the plan/profile allowlist — you cannot grant tools beyond your plan tier."}},"type":"object","required":["tool_allowlist"],"title":"ToolAllowlistBody","description":"Request body for PUT /v1/projects/{id}/tool-allowlist."},"ToolAllowlistResponse":{"properties":{"project_id":{"type":"string","title":"Project Id"},"tool_allowlist":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tool Allowlist"},"recommended_starter":{"items":{"type":"string"},"type":"array","title":"Recommended Starter"},"recommended_starter_size":{"type":"integer","title":"Recommended Starter Size"}},"type":"object","required":["project_id","tool_allowlist","recommended_starter","recommended_starter_size"],"title":"ToolAllowlistResponse","description":"Response for GET /v1/projects/{id}/tool-allowlist."},"ToolInfo":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"available":{"type":"boolean","title":"Available"},"tier":{"type":"string","title":"Tier"}},"type":"object","required":["name","description","category","available","tier"],"title":"ToolInfo"},"ToolRollupItem":{"properties":{"tool":{"type":"string","title":"Tool"},"calls":{"type":"integer","title":"Calls"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"pct_of_total":{"type":"number","title":"Pct Of Total"}},"type":"object","required":["tool","calls","tokens_in","tokens_saved","pct_of_total"],"title":"ToolRollupItem"},"TransferTeamOwnershipRequest":{"properties":{"new_owner_id":{"type":"string","format":"uuid","title":"New Owner Id"}},"type":"object","required":["new_owner_id"],"title":"TransferTeamOwnershipRequest","description":"Body for POST /v1/teams/{id}/transfer."},"TrendPoint":{"properties":{"date":{"type":"string","title":"Date"},"compressions":{"type":"integer","title":"Compressions"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"}},"type":"object","required":["date","compressions","tokens_in","tokens_saved"],"title":"TrendPoint"},"UnsubscribeResponse":{"properties":{"status":{"type":"string","title":"Status"}},"type":"object","required":["status"],"title":"UnsubscribeResponse"},"UpdateKeyRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name"},"default_model":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Default Model"},"monthly_quota":{"anyOf":[{"type":"integer","maximum":100000000.0,"minimum":1.0},{"type":"null"}],"title":"Monthly Quota"},"enforce_quota":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enforce Quota"},"environment":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Environment"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"}},"type":"object","title":"UpdateKeyRequest","description":"Request body for ``PATCH /v1/keys/{key_id}``.\n\nAll fields are optional — supply only what you want to change.\nPass ``monthly_quota: null`` to clear the quota (key becomes\nuncapped again)."},"UpdateMemberRoleRequest":{"properties":{"role":{"type":"string","title":"Role"}},"type":"object","required":["role"],"title":"UpdateMemberRoleRequest","description":"Body for PATCH /v1/teams/{id}/members/{user_id}/role."},"UpdateProfileRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name"},"fidelity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fidelity"},"chunk_size":{"anyOf":[{"type":"integer","maximum":1000.0,"minimum":50.0},{"type":"null"}],"title":"Chunk Size"},"skeleton_ratio":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.05},{"type":"null"}],"title":"Skeleton Ratio"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"}},"type":"object","title":"UpdateProfileRequest","description":"Body for PUT /v1/profiles/{id} — all fields optional."},"UpdateProjectRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"}},"type":"object","title":"UpdateProjectRequest","description":"Body for PUT /v1/projects/{project_id} — all fields optional."},"UploadCompleteResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["upload_id","status"],"title":"UploadCompleteResponse","description":"200 response for POST /uploads/{upload_id}/complete."},"UsageAlert":{"properties":{"severity":{"type":"string","title":"Severity"},"message":{"type":"string","title":"Message"}},"type":"object","required":["severity","message"],"title":"UsageAlert","description":"Usage milestone alert — returned when pct_used crosses a threshold."},"UsageByCacheResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"compression_only_savings_usd":{"type":"number","title":"Compression Only Savings Usd"},"combined_savings_usd":{"type":"number","title":"Combined Savings Usd"},"by_target":{"items":{"$ref":"#/components/schemas/CacheRollupRow"},"type":"array","title":"By Target"},"semantic_cache":{"$ref":"#/components/schemas/SemanticCacheRollup"},"by_source":{"$ref":"#/components/schemas/HitSourceBreakdown"}},"type":"object","required":["period_days","compression_only_savings_usd","combined_savings_usd","by_target","semantic_cache","by_source"],"title":"UsageByCacheResponse"},"UsageByClientResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"total_calls":{"type":"integer","title":"Total Calls"},"items":{"items":{"$ref":"#/components/schemas/ClientRollupItem"},"type":"array","title":"Items"}},"type":"object","required":["period_days","total_calls","items"],"title":"UsageByClientResponse"},"UsageByKeyResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"by_key":{"items":{"$ref":"#/components/schemas/KeyRollupRow"},"type":"array","title":"By Key"},"total_compressions":{"type":"integer","title":"Total Compressions"},"total_savings_usd":{"type":"number","title":"Total Savings Usd"}},"type":"object","required":["period_days","by_key","total_compressions","total_savings_usd"],"title":"UsageByKeyResponse"},"UsageByModelResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"items":{"items":{"$ref":"#/components/schemas/ModelRollupItem"},"type":"array","title":"Items"}},"type":"object","required":["period_days","items"],"title":"UsageByModelResponse"},"UsageByToolResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days"},"total_calls":{"type":"integer","title":"Total Calls"},"items":{"items":{"$ref":"#/components/schemas/ToolRollupItem"},"type":"array","title":"Items"}},"type":"object","required":["period_days","total_calls","items"],"title":"UsageByToolResponse"},"UsageHistoryPoint":{"properties":{"date":{"type":"string","title":"Date"},"compressions":{"type":"integer","title":"Compressions"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"}},"type":"object","required":["date","compressions","tokens_in","tokens_saved"],"title":"UsageHistoryPoint","description":"Usage data for a single day."},"UsageHistoryResponse":{"properties":{"period":{"type":"string","title":"Period"},"days":{"type":"integer","title":"Days"},"data":{"items":{"$ref":"#/components/schemas/UsageHistoryPoint"},"type":"array","title":"Data"}},"type":"object","required":["period","days","data"],"title":"UsageHistoryResponse","description":"Time-series usage history."},"UsageResponse":{"properties":{"period":{"type":"string","title":"Period"},"compressions_used":{"type":"integer","title":"Compressions Used"},"compressions_limit":{"type":"integer","title":"Compressions Limit"},"pct_used":{"type":"number","title":"Pct Used"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_saved":{"type":"integer","title":"Tokens Saved"},"resets_at":{"type":"string","title":"Resets At"},"alert":{"anyOf":[{"$ref":"#/components/schemas/UsageAlert"},{"type":"null"}]},"plan":{"type":"string","title":"Plan","default":"free"},"rate_limit_per_minute":{"type":"integer","title":"Rate Limit Per Minute","default":30}},"type":"object","required":["period","compressions_used","compressions_limit","pct_used","tokens_in","tokens_saved","resets_at"],"title":"UsageResponse","description":"Monthly usage statistics for the authenticated user."},"UserNotification":{"properties":{"id":{"type":"string","title":"Id"},"severity":{"type":"string","title":"Severity"},"category":{"type":"string","title":"Category"},"title":{"type":"string","title":"Title"},"message":{"type":"string","title":"Message"},"dismissible":{"type":"boolean","title":"Dismissible"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","severity","category","title","message","dismissible","created_at"],"title":"UserNotification","description":"A notification visible to the user."},"UsernameRequest":{"properties":{"username":{"type":"string","title":"Username"}},"type":"object","required":["username"],"title":"UsernameRequest","description":"Payload for PATCH /v1/account/username."},"UsernameResponse":{"properties":{"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"}},"type":"object","required":["username"],"title":"UsernameResponse","description":"Response for GET and PATCH /v1/account/username."},"ValidateLicenseRequest":{"properties":{"license_key":{"type":"string","minLength":20,"title":"License Key"}},"type":"object","required":["license_key"],"title":"ValidateLicenseRequest","description":"Body for POST /v1/licenses/validate."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VapidPublicKeyResponse":{"properties":{"public_key":{"type":"string","title":"Public Key"}},"type":"object","required":["public_key"],"title":"VapidPublicKeyResponse"},"VisibilityRequest":{"properties":{"visibility":{"type":"string","enum":["private","project","org","external"],"title":"Visibility","description":"Visibility level. 'org' and 'external' return 501 until v1.39 (requires Clerk org webhook integration)."}},"type":"object","required":["visibility"],"title":"VisibilityRequest","description":"Body for PATCH …/visibility."},"VoteRequest":{"properties":{"item_id":{"type":"string","title":"Item Id"},"value":{"type":"integer","maximum":1.0,"minimum":-1.0,"title":"Value"}},"type":"object","required":["item_id","value"],"title":"VoteRequest"},"VoteResult":{"properties":{"item_id":{"type":"string","title":"Item Id"},"net_score":{"type":"integer","title":"Net Score"},"upvote_count":{"type":"integer","title":"Upvote Count"},"downvote_count":{"type":"integer","title":"Downvote Count"},"user_vote":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Vote"}},"type":"object","required":["item_id","net_score","upvote_count","downvote_count"],"title":"VoteResult"},"WebhookDeliveriesResponse":{"properties":{"deliveries":{"items":{"$ref":"#/components/schemas/WebhookDeliveryResponse"},"type":"array","title":"Deliveries"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["deliveries","page","page_size","total"],"title":"WebhookDeliveriesResponse","description":"Paginated delivery history."},"WebhookDeliveryResponse":{"properties":{"id":{"type":"string","title":"Id"},"webhook_id":{"type":"string","title":"Webhook Id"},"event":{"type":"string","title":"Event"},"status":{"type":"string","title":"Status"},"attempts":{"type":"integer","title":"Attempts"},"response_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Code"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"last_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Attempt At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","webhook_id","event","status","attempts","response_code","latency_ms","last_attempt_at","created_at"],"title":"WebhookDeliveryResponse","description":"Serialized delivery attempt sequence."},"WebhookListResponse":{"properties":{"webhooks":{"items":{"$ref":"#/components/schemas/WebhookResponse"},"type":"array","title":"Webhooks"}},"type":"object","required":["webhooks"],"title":"WebhookListResponse","description":"List of configured webhooks."},"WebhookResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"secret":{"type":"string","title":"Secret"},"is_active":{"type":"boolean","title":"Is Active"},"deleted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","url","events","secret","is_active","deleted_at","created_at"],"title":"WebhookResponse","description":"Serialized webhook configuration."},"WithdrawRequest":{"properties":{"reason":{"type":"string","minLength":1,"title":"Reason"},"dmca":{"type":"boolean","title":"Dmca","default":false}},"type":"object","required":["reason"],"title":"WithdrawRequest"},"WithdrawResponse":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["id","status"],"title":"WithdrawResponse"},"api__app__routers__v1__audit_logs__AuditLogResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/AuditLogEntry"},"type":"array","title":"Entries"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"}},"type":"object","required":["entries","total","page","page_size"],"title":"AuditLogResponse","description":"Paginated audit log response."},"api__app__routers__v1__context_hub__IngestResponse":{"properties":{"slug":{"type":"string","title":"Slug"},"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"}},"type":"object","required":["slug","item_id","version_id"],"title":"IngestResponse"},"api__app__routers__v1__governance__AuditLogResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/AuditEventResponse"},"type":"array","title":"Events"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"total_matching":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Matching"}},"type":"object","required":["events"],"title":"AuditLogResponse"},"api__app__routers__v1__knowledge__IngestResponse":{"properties":{"item_id":{"type":"string","title":"Item Id"},"version_id":{"type":"string","title":"Version Id"}},"type":"object","required":["item_id","version_id"],"title":"IngestResponse"},"api__app__routers__v1__news_admin__IngestResponse":{"properties":{"created":{"items":{"$ref":"#/components/schemas/IngestItemResult"},"type":"array","title":"Created"},"duplicates":{"items":{"$ref":"#/components/schemas/IngestItemResult"},"type":"array","title":"Duplicates"},"errors":{"items":{"$ref":"#/components/schemas/IngestErrorResult"},"type":"array","title":"Errors"}},"type":"object","required":["created","duplicates","errors"],"title":"IngestResponse"}}}}