Every endpoint lives on your codesafe instance's own address, for example https://codesafe.example, and speaks JSON over HTTPS. These pages say what each endpoint takes and returns; the guides at the end show how to set a client up.
Endpoints
| Endpoint | Method and path | Auth | Page |
|---|---|---|---|
| Errors, 404s, security events | POST /api/v1/ingest | api_key header | Errors |
| Browser reports | POST /api/v1/ingest/js/<js_key> | js_key in the path, Origin | Browser reports |
| DOM snapshots | POST /api/v1/ingest/snapshot/<js_key> | js_key in the path, Origin | Browser reports |
| OpenTelemetry logs | POST /api/v1/ingest/otel/v1/logs | api_key header | OpenTelemetry |
| OpenTelemetry metrics | POST /api/v1/ingest/otel/v1/metrics | api_key header | OpenTelemetry |
| Releases | POST /api/v1/ingest/release | api_key header | Releases |
| Traffic rollups | POST /api/v1/ingest/rollup | api_key header | Rollups |
| Source maps | POST /api/v1/ingest/sourcemap | api_key header | Source maps |
| Cron ping | GET /api/v1/ping/<ping_key> | ping_key in the path | Ping |
The official WordPress plugin also uses endpoints of its own: its switches, the software inventory, the integrity scan and CONNECT. They are not part of this reference.
Authentication
| Key | Where it goes | Secret | Where to find it |
|---|---|---|---|
api_key | the X-Codesafe-Key header | yes, server-side only | PROJECTS: the row menu's COPY API KEY, or the project dialog's SECURITY tab under API KEY |
js_key | the URL path | no, public by design | the project dialog's REPORTING tab under BROWSER JS KEY, once accept browser reports is ticked; the row menu's COPY JS KEY |
ping_key | the URL path | keep the URL private | MONITORS: the row menu's COPY PING URL |
An api_key is 64 hex characters and opens every server endpoint of its project. Rotating it stops the old key at once. A js_key is 32 hex characters: the request's Origin must be one of the project's ALLOWED ORIGINS, and a per-address limit holds a leaked key. The WordPress plugin receives both keys through CONNECT, without anyone copying them.
Responses
Every endpoint but two answers with one JSON envelope: success says whether codesafe took the request, error says why not, and the endpoint adds its own fields.
Accepted
{"success": true, "accepted": 3}Refused
{"success": false, "error": "batch too large, max 50"}The OpenTelemetry endpoint answers as OTLP/HTTP prescribes ({}, partialSuccess or a google.rpc.Status), and a ping answers 204 with no body. These are every status the endpoints can return:
| Status | When | What the client does |
|---|---|---|
200 | The OpenTelemetry endpoint took the export; partialSuccess counts what it dropped | Nothing |
202 | Accepted; accepted counts the events past the project's gates | Nothing; fewer than sent is normal |
204 | codesafe recorded a ping, or a browser endpoint's CORS preflight passed | Nothing |
400 | Malformed JSON, or a field the endpoint refuses; error names it | Fix the sender; never retry |
401 | X-Codesafe-Key is missing, or no active project holds it | Stop sending; check the key |
403 | Browser: the Origin is not allowed or browser reports are off. Rollups and OTLP metrics: the project takes no rollups | Fix the project's settings; never retry |
404 | The ping key is unknown or inactive, an OTLP signal is not logs or metrics, or snapshots are off | Drop it |
405 | The method is wrong: every ingest endpoint takes POST only | Fix the sender |
409 | A snapshot id is already taken; the first upload wins | Drop it; the snapshot is not stored |
413 | The body is over the endpoint's cap | Send less; never resend the same body |
415 | OpenTelemetry: protobuf, or a Content-Encoding codesafe does not decode | Export JSON, gzip or uncompressed |
429 | A budget is spent: the project's, an address's, or the day's snapshots | Retry once after Retry-After, or drop |
503 | codesafe cannot store it: its store or registry is down, or intake pauses near its memory ceiling | Retry once after Retry-After, or drop |
Limits
The defaults below hold on every instance unless its operator changes them.
| Limit | Default | Past it |
|---|---|---|
| Events per error request | 50 | 400 |
| Error request body | 256 KB | 413 |
| Browser reports per request | 10 | 400 |
| Browser request body | 64 KB | 413 |
| Browser and snapshot requests | 30 a minute per address | 429 |
| Snapshot body | 512 KB | 413 |
| Snapshots per project | 2,000 or 256 MiB a day | 429, Retry-After: 3600 |
| OTLP log records per request | 200 | dropped, counted in partialSuccess |
| OTLP body | 1 MiB on the wire, 8 MiB inflated | 413, 400 |
| Release and rollup body | 16 KB | 413 |
| Source map | 32 MiB, and 16 MiB compressed | 400, 413 |
| Requests per project | 3,000 a minute, across every api_key endpoint and the browser reports your server forwards | 429, Retry-After: 60 |
| Events per project | 15,000 a minute, from error batches, OTLP log records and forwarded browser reports | 429, Retry-After: 60 |
| Shield pulls per project and address | 60 a minute, counted apart from the requests | 429, Retry-After: 60 |
A 503 carries Retry-After: 30 when the registry is down or intake pauses near the event store's memory ceiling. The browser endpoints and the ping take no api_key and spend no project budget, except a browser report your server forwards with the api_key (Browser reports).
Retries
- Never retry what may have arrived. A timeout after the body went out may already be stored, and sent again it is stored twice.
- Retry once, off the request path, and only a connection that never opened, a
429or a503, or a502or504from a proxy in front of codesafe: each says the batch never arrived. Wait theRetry-Afterseconds when the answer carries them, else a second. - Drop everything else. Every other
4xxis permanent: the same request gets the same answer. - Some endpoints are safe to resend. A rollup fragment and an OTLP metrics point count once, a release keeps its first moment, a source map replaces itself and a ping records a time.
Kinds
Every event says what it is in kind: error (a fault in the code), not_found (a request for something that does not exist, usually a scanner probe) or security (a refusal or audit line the application reports on purpose). All three use one endpoint and one envelope. The Errors page lists the security names and their default priorities.
Guides
- Send your first error: one request, in every language
- Build your own client: the rules a good client follows
- Browser client: the shipped script, origins and options
- OpenTelemetry: a collector instead of a client
- Connect your AI agent: read and act on events over MCP