{"openapi":"3.0.3","info":{"title":"ContextStellar API","version":"1.0.0","description":"Project telemetry and account APIs. Public browser prompt analysis is not a hosted optimize API. Application request limits are 100/min globally and 30/min for APIs, per client IP and server process; honor RateLimit and Retry-After. Organization ingestion quotas are separately enforced. Scoped project keys and Clerk cookie sessions have different permissions; neither is advertised as OAuth. No hosted sandbox is promised."},"servers":[{"url":"/","description":"Use the origin serving this specification."}],"externalDocs":{"url":"https://contextstellar.com/docs","description":"ContextStellar developer documentation"},"tags":[{"name":"Public","description":"Public information only."},{"name":"Application API","description":"Authenticated tenant-scoped application operations."}],"paths":{"/api/v1/ingest":{"post":{"operationId":"ingestEvents","summary":"Ingest project events","description":"Requires an ingest-scoped project key. Batch projectId must match the key. Accepts 1–100 trace, segment or span events and enforces the organization monthly event quota. Returns 207 even for partial acceptance: inspect accepted, rejected and errors. idempotencyKey is required by validation; do not assume whole-batch replay suppression. Event IDs and ownership checks govern writes.","tags":["Application API"],"security":[{"projectApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestBatch"},"example":{"projectId":"YOUR_PROJECT_ID","idempotencyKey":"example-batch-1","events":[{"eventType":"trace","id":"example-trace-1","projectId":"YOUR_PROJECT_ID","name":"Example trace","startedAt":"2026-11-01T00:00:00Z","timestamp":"2026-11-01T00:00:00Z"}]}}}},"x-required-api-key-scope":"ingest","responses":{"207":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestResult"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/traces":{"get":{"operationId":"listTraces","summary":"List authorized project traces","description":"A read-scoped API key fixes the project to its own project. Alternatively a Clerk session must specify projectId or X-Project-Id and have organization membership. Session authentication does not make this an anonymous endpoint.","tags":["Application API"],"security":[{"projectApiKey":[]},{"clerkSession":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"description":"Project identifier. For API-key auth, the project is fixed by the key.","schema":{"type":"string"}},{"name":"X-Project-Id","in":"header","required":false,"description":"Session-only alternative to projectId.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"One-based page.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"description":"Items per page; the server clamps to 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"minScore","in":"query","required":false,"description":"Inclusive minimum efficiency score.","schema":{"type":"number"}},{"name":"maxScore","in":"query","required":false,"description":"Inclusive maximum efficiency score.","schema":{"type":"number"}},{"name":"startDate","in":"query","required":false,"description":"Inclusive earliest creation time.","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","required":false,"description":"Inclusive latest creation time.","schema":{"type":"string","format":"date-time"}}],"x-required-api-key-scope":"read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceList"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/traces/{traceId}":{"get":{"operationId":"getTrace","summary":"Read a trace and its context","description":"Returns a trace, ordered segments, spans, scores and project volatility. A read-scoped project key or an authorized Clerk session is required. Missing or inaccessible traces return 404 or 403 according to existing membership checks.","tags":["Application API"],"security":[{"projectApiKey":[]},{"clerkSession":[]}],"parameters":[{"name":"traceId","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"x-required-api-key-scope":"read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceDetail"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/traces/{traceId}/segments/reorder":{"patch":{"operationId":"reorderTraceSegments","summary":"Reorder trace segments","description":"Clerk session only, with project owner/admin permissions. Supply a nonempty complete ordering of segment IDs for the trace. Recomputes cache-related estimates and scores; does not call a language model.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"traceId","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segmentIds":{"type":"array","minItems":1,"items":{"type":"string"}}},"required":["segmentIds"]}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderResult"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects":{"get":{"operationId":"listProjects","summary":"List your projects","description":"Clerk session only. Lists projects belonging to organizations in which the current user is a member.","tags":["Application API"],"security":[{"clerkSession":[]}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["projects"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createProject","summary":"Create an organization project","description":"Clerk session only. Requires owner/admin membership of the existing organization. This does not create an organization or grant membership.","tags":["Application API"],"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string"}},"required":["orgId","name"]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}},"required":["project"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}":{"get":{"operationId":"getProject","summary":"Read a project","description":"Clerk session and organization membership required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}},"required":["project"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateProject","summary":"Update a project","description":"Clerk session with owner/admin permissions required. Updates the project name and slug.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}},"required":["project"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteProject","summary":"Delete a project","description":"Destructive. Clerk session and organization owner role required. Deletes the project and its cascading records.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}/stats":{"get":{"operationId":"getProjectStats","summary":"Read project statistics","description":"Clerk session and organization membership required. Aggregates project data over a clamped 1–90 day window.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Days to aggregate.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectStats"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"List project key metadata","description":"Clerk session and project membership required. Never returns raw keys or key hashes.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"description":"Project identifier. For API-key auth, the project is fixed by the key.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["apiKeys"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createApiKey","summary":"Create a scoped project key","description":"Clerk session with project owner/admin role required. Returns the secret once; only its hash is stored. Current keys receive ingest and read scopes. Save the key in a secret manager, not a URL or prompt.","tags":["Application API"],"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string"},"name":{"type":"string"}},"required":["projectId"]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string"}},"required":["key"]}]},"warning":{"type":"string"}},"required":["apiKey","warning"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"revokeApiKey","summary":"Revoke a project key","description":"Clerk session with project owner/admin role required. Marks the key revoked; it can no longer authenticate.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"Key identifier to revoke.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/policies":{"get":{"operationId":"listPolicies","summary":"List project policies","description":"Clerk session and project membership required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"description":"Project identifier. For API-key auth, the project is fixed by the key.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}}},"required":["policies"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createPolicy","summary":"Create a project policy","description":"Clerk session and project owner/admin permissions required. Rules are free-form JSON policy entries in the current service.","tags":["Application API"],"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string"},"name":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRule"}}},"required":["projectId","name","rules"]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/Policy"}},"required":["policy"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/policies/{id}":{"get":{"operationId":"getPolicy","summary":"Read a policy","description":"Clerk session with membership of the policy project required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/Policy"}},"required":["policy"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updatePolicy","summary":"Update a policy","description":"Clerk session with project owner/admin permissions required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRule"}}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/Policy"}},"required":["policy"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePolicy","summary":"Delete a policy","description":"Destructive. Clerk session with project owner/admin permissions required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of a resource you are authorized to access.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List project alerts","description":"Clerk session and project membership required.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"description":"Project identifier. For API-key auth, the project is fixed by the key.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"One-based page.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"description":"Items per page; the server clamps to 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"severity","in":"query","required":false,"description":"Filter by alert severity.","schema":{"type":"string"}},{"name":"unresolved","in":"query","required":false,"description":"Set true to return unresolved alerts only.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertList"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/claude-code":{"post":{"operationId":"recordClaudeCodeHook","summary":"Record and score a Claude Code hook","description":"Requires an ingest-scoped project key. Accepts native snake_case or legacy camelCase fields. Handles PreToolUse, PostToolUse, PostToolUseFailure and Stop. Unrecognized hook types pass through with decision allow. This endpoint is not an anonymous optimizer.","tags":["Application API"],"security":[{"projectApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookRequest"},"example":{"session_id":"example-session","hook_event_name":"PreToolUse","tool_name":"Task","tool_input":{"prompt":"Review this code for bugs."}}}}},"x-required-api-key-scope":"ingest","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookResult"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/stats":{"get":{"operationId":"getHookStats","summary":"Read hook statistics","description":"A read-scoped key fixes the project. A Clerk session must specify projectId and have organization membership.","tags":["Application API"],"security":[{"projectApiKey":[]},{"clerkSession":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"description":"Project identifier. For API-key auth, the project is fixed by the key.","schema":{"type":"string"}}],"x-required-api-key-scope":"read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookStats"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/shell-stats":{"get":{"operationId":"getShellStats","summary":"Read compact shell statistics","description":"Requires a read-scoped project key. Returns compact aggregate prompt-scoring metrics for terminal display.","tags":["Application API"],"security":[{"projectApiKey":[]}],"x-required-api-key-scope":"read","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShellStats"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/learning-progress":{"get":{"operationId":"getLearningProgress","summary":"Read your learning progress","description":"Clerk session required. Returns only the current user’s learning progress.","tags":["Application API"],"security":[{"clerkSession":[]}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearningProgress"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"saveLearningProgress","summary":"Save your learning progress","description":"Clerk session required. Saves completed nodes and optional path/last-visited node for the current user.","tags":["Application API"],"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearningProgress"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/waitlist":{"get":{"operationId":"getWaitlistCount","summary":"Read the displayed waitlist count","description":"Public. Depends on the configured Google Sheets connection. The legacy implementation returns count 0 on dependency failure; zero is not evidence of an empty waitlist.","tags":["Public"],"security":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"joinWaitlist","summary":"Join the waitlist","description":"Clerk session required. Uses the authenticated account email; if email is supplied it must match that account. Requires the configured Google Sheets connection and spreadsheet access. Duplicate submissions return 409.","tags":["Application API"],"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"}},"required":["success","count"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/user/data":{"get":{"operationId":"exportUserData","summary":"Export your application data","description":"Clerk session required. Exports current user data; download=true adds an attachment disposition. Treat the export as private.","tags":["Application API"],"security":[{"clerkSession":[]}],"parameters":[{"name":"download","in":"query","required":false,"description":"Request an attachment by setting download=true.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserExport"}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteUserData","summary":"Delete your application data","description":"Destructive. Clerk session required. Deletes application data handled by the existing deletion service, not an assertion that external Clerk or Google Sheets records are erased.","tags":["Application API"],"security":[{"clerkSession":[]}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deletedCounts":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["message","deletedCounts"]}}}},"400":{"description":"400 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"405 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until request rate-limit reset, when applicable. Not a monthly-quota reset.","schema":{"type":"integer"}},"RateLimit":{"description":"Request rate-limit counters when available.","schema":{"type":"string"}}}},"500":{"description":"500 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"503 structured error. Follow the hint; never expose credentials in reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"cs_live_ project API key","description":"Scoped project key, NOT an OAuth token. Required scopes are described per operation and in x-required-api-key-scope."},"clerkSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Existing Clerk browser session. Use the browser sign-in flow; do not copy session cookies into prompts or source. OAuth tokens are not currently accepted."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Legacy human-readable error, retained for existing clients."},"code":{"type":"string","description":"Stable machine-readable category, e.g. UNAUTHORIZED or RATE_LIMITED."},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","code","message","hint"]},"Project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"orgId":{"type":"string","minLength":1},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orgId","name","slug","createdAt","updatedAt"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"name":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","keyPrefix","scopes","createdAt"]},"PolicyRule":{"type":"object","properties":{"field":{"type":"string"},"operator":{"type":"string","enum":["gt","lt","gte","lte","eq","neq"]},"value":{"oneOf":[{"type":"number"},{"type":"string"}]},"segmentType":{"type":"string"}},"required":["field","operator","value"]},"Policy":{"type":"object","properties":{"id":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"name":{"type":"string"},"enabled":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRule"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","projectId","name","enabled","rules","createdAt","updatedAt"]},"Trace":{"type":"object","properties":{"id":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"name":{"type":"string","nullable":true},"externalUserId":{"type":"string","nullable":true},"contextEfficiencyScore":{"type":"number","nullable":true},"prefixStabilityScore":{"type":"number","nullable":true},"segmentComposition":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"tokens":{"type":"integer"}},"required":["count","tokens"]},"nullable":true},"totalInputTokens":{"type":"integer"},"totalOutputTokens":{"type":"integer"},"totalCostUsd":{"type":"number"},"outputContent":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"startedAt":{"type":"string","format":"date-time","nullable":true},"endedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","projectId","totalInputTokens","totalOutputTokens","totalCostUsd","createdAt"]},"Segment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"traceId":{"type":"string","minLength":1},"type":{"type":"string","enum":["system_prompt","rag_chunk","conversation_history","tool_output","few_shot_example","user_message","metadata","guardrail","custom"]},"content":{"type":"string"},"tokenCount":{"type":"integer"},"position":{"type":"integer"},"source":{"type":"string","nullable":true},"retrievalScore":{"type":"number","nullable":true},"relevanceScore":{"type":"number","nullable":true},"redundancyScore":{"type":"number","nullable":true},"contentHash":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","traceId","type","content","tokenCount","position","createdAt"]},"Span":{"type":"object","properties":{"id":{"type":"string","minLength":1},"traceId":{"type":"string","minLength":1},"name":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true},"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheCreationTokens":{"type":"integer"},"costUsd":{"type":"number"},"latencyMs":{"type":"integer","nullable":true},"outputContent":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"startedAt":{"type":"string","format":"date-time","nullable":true},"endedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","traceId","inputTokens","outputTokens","cacheReadTokens","cacheCreationTokens","costUsd","createdAt"]},"ContextScore":{"type":"object","properties":{"id":{"type":"string","minLength":1},"traceId":{"type":"string","minLength":1},"scoreType":{"type":"string"},"value":{"type":"number"},"breakdown":{"type":"object","additionalProperties":true,"nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","traceId","scoreType","value"]},"Volatility":{"type":"object","properties":{"type":{"type":"string","enum":["system_prompt","rag_chunk","conversation_history","tool_output","few_shot_example","user_message","metadata","guardrail","custom"]},"changeRate":{"type":"number"},"classification":{"type":"string","enum":["static","near-static","volatile","always-volatile"]},"avgTokenCount":{"type":"number"},"sampleCount":{"type":"integer"}},"required":["type","changeRate","classification","avgTokenCount","sampleCount"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]},"TraceList":{"type":"object","properties":{"traces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["traces","pagination"]},"TraceDetail":{"type":"object","properties":{"trace":{"$ref":"#/components/schemas/Trace"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"}},"scores":{"type":"array","items":{"$ref":"#/components/schemas/ContextScore"}},"volatility":{"type":"array","items":{"$ref":"#/components/schemas/Volatility"}}},"required":["trace","segments","spans","scores","volatility"]},"TraceEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string","enum":["trace"]},"projectId":{"type":"string","minLength":1},"name":{"type":"string"},"userId":{"type":"string"},"output":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"}},"required":["eventType","id","projectId","startedAt","timestamp"]},"SegmentEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string","enum":["segment"]},"traceId":{"type":"string","minLength":1},"type":{"type":"string","enum":["system_prompt","rag_chunk","conversation_history","tool_output","few_shot_example","user_message","metadata","guardrail","custom"]},"content":{"type":"string"},"position":{"type":"integer","minimum":0},"source":{"type":"string"},"retrievalScore":{"type":"number","minimum":0,"maximum":1},"contentHash":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}},"required":["eventType","id","traceId","type","content","position","timestamp"]},"SpanEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string","enum":["span"]},"traceId":{"type":"string","minLength":1},"name":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"integer","minimum":0},"outputTokens":{"type":"integer","minimum":0},"cacheReadTokens":{"type":"integer","minimum":0},"cacheCreationTokens":{"type":"integer","minimum":0},"output":{"type":"string"},"latencyMs":{"type":"integer","minimum":0},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true}},"required":["eventType","id","traceId","startedAt","timestamp"]},"IngestBatch":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"idempotencyKey":{"type":"string","minLength":1},"events":{"type":"array","minItems":1,"maxItems":100,"items":{"oneOf":[{"$ref":"#/components/schemas/TraceEvent"},{"$ref":"#/components/schemas/SegmentEvent"},{"$ref":"#/components/schemas/SpanEvent"}],"discriminator":{"propertyName":"eventType","mapping":{"trace":"#/components/schemas/TraceEvent","segment":"#/components/schemas/SegmentEvent","span":"#/components/schemas/SpanEvent"}}}}},"required":["projectId","idempotencyKey","events"]},"IngestResult":{"type":"object","properties":{"accepted":{"type":"integer"},"rejected":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"error":{"type":"string"}},"required":["index","error"]}},"policyViolations":{"type":"array","items":{"type":"object","properties":{"policyId":{"type":"string"},"policyName":{"type":"string"},"rule":{"$ref":"#/components/schemas/PolicyRule"},"actualValue":{"oneOf":[{"type":"number"},{"type":"string"}]},"severity":{"type":"string","enum":["info","warning","critical"]},"message":{"type":"string"}},"required":["policyId","policyName","rule","actualValue","severity","message"]}}},"required":["accepted","rejected","errors","policyViolations"]},"LearningProgress":{"type":"object","properties":{"completedNodes":{"type":"array","items":{"type":"string"}},"activePath":{"type":"string","nullable":true},"lastVisitedNode":{"type":"string","nullable":true}},"required":["completedNodes"]},"HookRequest":{"type":"object","properties":{"session_id":{"type":"string"},"sessionId":{"type":"string"},"hook_event_name":{"type":"string","description":"Native Claude Code name: PreToolUse, PostToolUse, PostToolUseFailure, or Stop."},"type":{"type":"string","description":"Legacy camelCase hook name."},"tool_name":{"type":"string"},"toolName":{"type":"string"},"tool_use_id":{"type":"string"},"toolUseId":{"type":"string"},"tool_input":{"type":"object","additionalProperties":true},"toolInput":{"type":"object","additionalProperties":true},"tool_result":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]},"toolResult":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]},"toolOutput":{"type":"object","additionalProperties":true},"error":{"type":"string"},"stopReason":{"type":"string"},"stop_reason":{"type":"string"},"totalTokensUsed":{"type":"integer"},"totalCostUsd":{"type":"number"},"metadata":{"type":"object","additionalProperties":true},"cwd":{"type":"string"},"permission_mode":{"type":"string"}},"allOf":[{"anyOf":[{"required":["session_id"]},{"required":["sessionId"]}]},{"anyOf":[{"required":["hook_event_name"]},{"required":["type"]}]}]},"HookResult":{"type":"object","properties":{"decision":{"type":"string","enum":["allow"]},"additionalContext":{"type":"string"}},"required":["decision"]},"ShellStats":{"type":"object","properties":{"avgScore":{"type":"number"},"avgGrade":{"type":"string"},"successRate":{"type":"number"},"totalEvents":{"type":"integer"},"tokensSaved":{"type":"number"},"rlmConfidence":{"type":"number"},"rlmSamples":{"type":"integer"},"trend":{"type":"string","enum":["up","down","stable"]}},"required":["avgScore","avgGrade","successRate","totalEvents","tokensSaved","rlmConfidence","rlmSamples","trend"]},"HookStats":{"type":"object","properties":{"eventCounts":{"type":"object","additionalProperties":{"type":"integer"}},"outcomes":{"type":"object","properties":{"total":{"type":"integer"},"successRate":{"type":"number"},"avgScore":{"type":"number","nullable":true},"avgLatencyMs":{"type":"number","nullable":true}},"nullable":true},"learnedWeights":{"type":"array","items":{"type":"object","properties":{"promptType":{"type":"string"},"cognitiveMode":{"type":"string"},"weights":{"type":"object","additionalProperties":true},"sampleCount":{"type":"integer"},"confidence":{"type":"number"},"updatedAt":{"type":"string","format":"date-time"}}},"nullable":true},"defaultWeights":{"type":"object","additionalProperties":true},"gradeDistribution":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["eventCounts","outcomes","learnedWeights","defaultWeights","gradeDistribution"]},"ProjectStats":{"type":"object","properties":{"summary":{"type":"object","properties":{"totalTraces":{"type":"integer"},"avgEfficiencyScore":{"type":"number"},"avgPrefixStability":{"type":"number"},"totalInputTokens":{"type":"integer"},"totalOutputTokens":{"type":"integer"},"totalCost":{"type":"number"},"activeAlerts":{"type":"integer"},"cacheHitRate":{"type":"number"},"totalCacheReadTokens":{"type":"integer"},"totalCacheCreationTokens":{"type":"integer"}},"required":["totalTraces","avgEfficiencyScore","avgPrefixStability","totalInputTokens","totalOutputTokens","totalCost","activeAlerts","cacheHitRate","totalCacheReadTokens","totalCacheCreationTokens"]},"daily":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"traceCount":{"type":"integer"},"avgEfficiencyScore":{"type":"number"},"totalTokens":{"type":"integer"}},"required":["day","traceCount","avgEfficiencyScore","totalTokens"]}}},"required":["summary","daily"]},"Alert":{"type":"object","properties":{"id":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"policyId":{"type":"string","nullable":true},"traceId":{"type":"string","nullable":true},"severity":{"type":"string"},"message":{"type":"string"},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","projectId","severity","message","createdAt"]},"AlertList":{"type":"object","properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["alerts","pagination"]},"ReorderResult":{"type":"object","properties":{"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"trace_id":{"type":"string","minLength":1},"type":{"type":"string","enum":["system_prompt","rag_chunk","conversation_history","tool_output","few_shot_example","user_message","metadata","guardrail","custom"]},"content":{"type":"string"},"token_count":{"type":"integer"},"position":{"type":"integer"},"source":{"type":"string","nullable":true},"retrieval_score":{"type":"number","nullable":true},"relevance_score":{"type":"number","nullable":true},"redundancy_score":{"type":"number","nullable":true},"content_hash":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}}},"prefixStability":{"type":"object","properties":{"score":{"type":"number"},"breakdown":{"type":"object","properties":{"stablePrefixTokens":{"type":"integer"},"totalTokens":{"type":"integer"},"stablePrefixLength":{"type":"integer"},"totalSegments":{"type":"integer"},"hasPreviousTrace":{"type":"boolean"}},"required":["stablePrefixTokens","totalTokens","stablePrefixLength","totalSegments","hasPreviousTrace"]}},"required":["score","breakdown"]},"efficiency":{"type":"object","properties":{"score":{"type":"number"},"breakdown":{"type":"object","additionalProperties":true}}},"estimatedCacheRate":{"type":"number"}},"required":["segments","prefixStability","efficiency","estimatedCacheRate"]},"UserExport":{"type":"object","properties":{"exportVersion":{"type":"string"},"exportedAt":{"type":"string","format":"date-time"},"userId":{"type":"string"},"profile":{"type":"object","additionalProperties":true,"nullable":true},"organizations":{"type":"array","items":{"type":"object","additionalProperties":true}},"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"traces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"}},"contextScores":{"type":"array","items":{"$ref":"#/components/schemas/ContextScore"}},"hookEvents":{"type":"array","items":{"type":"object","additionalProperties":true}},"learnedWeights":{"type":"array","items":{"type":"object","additionalProperties":true}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}},"required":["exportVersion","exportedAt","userId","profile","organizations","projects","traces","segments","spans","contextScores","hookEvents","learnedWeights","policies","alerts"]}}}}