DOCUMENTATION

API reference

Every endpoint a client sends to: its keys, its answers and its limits.

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

EndpointMethod and pathAuthPage
Errors, 404s, security eventsPOST /api/v1/ingestapi_key headerErrors
Browser reportsPOST /api/v1/ingest/js/<js_key>js_key in the path, OriginBrowser reports
DOM snapshotsPOST /api/v1/ingest/snapshot/<js_key>js_key in the path, OriginBrowser reports
OpenTelemetry logsPOST /api/v1/ingest/otel/v1/logsapi_key headerOpenTelemetry
OpenTelemetry metricsPOST /api/v1/ingest/otel/v1/metricsapi_key headerOpenTelemetry
ReleasesPOST /api/v1/ingest/releaseapi_key headerReleases
Traffic rollupsPOST /api/v1/ingest/rollupapi_key headerRollups
Source mapsPOST /api/v1/ingest/sourcemapapi_key headerSource maps
Cron pingGET /api/v1/ping/<ping_key>ping_key in the pathPing

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

KeyWhere it goesSecretWhere to find it
api_keythe X-Codesafe-Key headeryes, server-side onlyPROJECTS: the row menu's COPY API KEY, or the project dialog's SECURITY tab under API KEY
js_keythe URL pathno, public by designthe project dialog's REPORTING tab under BROWSER JS KEY, once accept browser reports is ticked; the row menu's COPY JS KEY
ping_keythe URL pathkeep the URL privateMONITORS: 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:

StatusWhenWhat the client does
200The OpenTelemetry endpoint took the export; partialSuccess counts what it droppedNothing
202Accepted; accepted counts the events past the project's gatesNothing; fewer than sent is normal
204codesafe recorded a ping, or a browser endpoint's CORS preflight passedNothing
400Malformed JSON, or a field the endpoint refuses; error names itFix the sender; never retry
401X-Codesafe-Key is missing, or no active project holds itStop sending; check the key
403Browser: the Origin is not allowed or browser reports are off. Rollups and OTLP metrics: the project takes no rollupsFix the project's settings; never retry
404The ping key is unknown or inactive, an OTLP signal is not logs or metrics, or snapshots are offDrop it
405The method is wrong: every ingest endpoint takes POST onlyFix the sender
409A snapshot id is already taken; the first upload winsDrop it; the snapshot is not stored
413The body is over the endpoint's capSend less; never resend the same body
415OpenTelemetry: protobuf, or a Content-Encoding codesafe does not decodeExport JSON, gzip or uncompressed
429A budget is spent: the project's, an address's, or the day's snapshotsRetry once after Retry-After, or drop
503codesafe cannot store it: its store or registry is down, or intake pauses near its memory ceilingRetry once after Retry-After, or drop

Limits

The defaults below hold on every instance unless its operator changes them.

LimitDefaultPast it
Events per error request50400
Error request body256 KB413
Browser reports per request10400
Browser request body64 KB413
Browser and snapshot requests30 a minute per address429
Snapshot body512 KB413
Snapshots per project2,000 or 256 MiB a day429, Retry-After: 3600
OTLP log records per request200dropped, counted in partialSuccess
OTLP body1 MiB on the wire, 8 MiB inflated413, 400
Release and rollup body16 KB413
Source map32 MiB, and 16 MiB compressed400, 413
Requests per project3,000 a minute, across every api_key endpoint and the browser reports your server forwards429, Retry-After: 60
Events per project15,000 a minute, from error batches, OTLP log records and forwarded browser reports429, Retry-After: 60
Shield pulls per project and address60 a minute, counted apart from the requests429, 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 429 or a 503, or a 502 or 504 from a proxy in front of codesafe: each says the batch never arrived. Wait the Retry-After seconds when the answer carries them, else a second.
  • Drop everything else. Every other 4xx is 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