# ContextStellar API Reference

The [OpenAPI 3.0.3 specification](/openapi.json) is the current contract for typed requests/responses, unique operation IDs, authentication and examples. All paths are relative to the origin serving that specification. There is no anonymous hosted prompt optimizer.

## Authentication

- Public: GET /api/waitlist returns the displayed count; legacy dependency failures return count 0, not a health guarantee.
- Project key with ingest scope: POST /api/v1/ingest and POST /api/v1/hooks/claude-code.
- Project key with read scope or authorized Clerk session: GET /api/v1/traces, GET /api/v1/traces/{traceId}, GET /api/v1/hooks/stats.
- Project key with read scope only: GET /api/v1/hooks/shell-stats.
- Clerk browser session: projects, project statistics, key management, policies, alerts, segment reordering, learning progress, joining the waitlist and personal-data export/deletion.

Use `Authorization: Bearer $CONTEXTSTELLAR_API_KEY` only for operations supporting project keys. Cookie sessions and keys are not interchangeable, and OAuth tokens are not accepted. See [authentication and onboarding](/docs/authentication.md).

## Operation index

| Path | Methods | Purpose |
| --- | --- | --- |
| /api/v1/ingest | POST | Record 1–100 trace, segment or span events |
| /api/v1/traces | GET | List authorized project traces |
| /api/v1/traces/{traceId} | GET | Trace, segments, spans, scores and volatility |
| /api/v1/traces/{traceId}/segments/reorder | PATCH | Owner/admin browser operation |
| /api/v1/projects | GET, POST | List projects; create within an existing organization |
| /api/v1/projects/{id} | GET, PUT, DELETE | Read, update name, delete project |
| /api/v1/projects/{id}/stats | GET | Project statistics over 1–90 days |
| /api/v1/api-keys | GET, POST, DELETE | List metadata, create once-visible secret, revoke |
| /api/v1/policies | GET, POST | List or create project policies |
| /api/v1/policies/{id} | GET, PUT, DELETE | Read, update or delete a policy |
| /api/v1/alerts | GET | Paginated project alerts |
| /api/v1/hooks/claude-code | POST | Record native or legacy Claude Code hooks |
| /api/v1/hooks/stats | GET | Hook outcomes, grades and weights |
| /api/v1/hooks/shell-stats | GET | Compact scoring statistics |
| /api/learning-progress | GET, PUT | Current user's learning state |
| /api/waitlist | GET, POST | Display count or authenticated submission |
| /api/v1/user/data | GET, DELETE | Export or delete application data |

Management authorization still applies. Project keys cannot issue keys, create projects, edit policies or delete personal data. Missing/inaccessible resources may return 403 or 404 to avoid leaking tenancy information.

## Ingestion

Batch fields: projectId, idempotencyKey, events (1–100). Every event requires eventType, id and timestamp. Trace events also require projectId and startedAt; segment events require traceId, type, content and position; span events require traceId and startedAt. See the exact event schemas in OpenAPI.

HTTP 207 contains accepted, rejected, errors (event index/error) and policyViolations. Inspect the entire result; partial failure can occur within 2xx. The idempotencyKey field is required but does not implement full batch replay suppression. Event IDs and tenant ownership govern writes. Monthly quota reservation counts attempted events.

## Structured errors

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "hint": "Use the authentication scheme for this operation in /openapi.json. Browser sessions and project API keys are not interchangeable."
}
```

The legacy error string remains compatible with existing consumers. Codes include INVALID_REQUEST (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), METHOD_NOT_ALLOWED (405), CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500) and SERVICE_UNAVAILABLE (503). Validation details can include path/message entries. Internal exceptions are not exposed.

Unknown API paths return JSON 404. Unsupported methods return JSON 405 with Allow; OPTIONS describes allowed methods without requiring a credential. HEAD is available where GET exists and has no response body.

## Limits and privacy

The application limits requests to 100/minute globally and 30/minute for API routes, per client IP and process. Hosting can impose additional limits; these in-memory counters are not a distributed quota guarantee. Honor RateLimit and Retry-After. Ingestion enforces a separate organization monthly event quota; do not immediately retry quota failures.

Telemetry may contain prompt content. Only upload data you are authorized to store. The free editor's local analysis does not establish hash-only storage or retention guarantees for hosted telemetry. See [Privacy](/privacy).

## Machine-readable public content

Use Accept: text/markdown on /, /docs, /about, /contact, /editor and /guide for public readable representations. Both negotiated variants include Vary: Accept. This does not execute interactive controls. Unknown public markdown paths return 404 with links to docs, sitemap and agent instructions.
