DOCUMENTATION

Errors

POST /api/v1/ingest — errors, 404 probes and security events from a server.

A server sender posts its application's errors, 404 probes and security events here, one at a time or up to 50 in one request.

Request

POST /api/v1/ingest
X-Codesafe-Key: <api_key>
Content-Type: application/json

The body is one event object, or a JSON array of up to 50 of them, at most 256 KB in all. Every field is optional except a name: see the line under the table.

Example

curl

curl -X POST https://codesafe.example/api/v1/ingest \
  -H "X-Codesafe-Key: $CODESAFE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runtime": "php", "kind": "error", "priority": 3,
       "message": "Call to undefined method Cart::total()",
       "events": [{"className": "Error", "file": "/var/www/app/src/Checkout.php", "line": 42}]}'

JSON

[
  {
    "v": 1, "runtime": "php", "entry": "web", "kind": "error", "priority": 3,
    "timestamp": "2026-10-30T14:05:00+01:00",
    "release": "2.14.1",
    "environment": "production",
    "tags": ["checkout", "tenant:acme"],
    "client": "my-sender/1.0.0",
    "message": "Call to undefined method Cart::total()",
    "events": [{
      "className": "Error",
      "file": "/var/www/app/src/Checkout.php",
      "line": 42,
      "backtrace": "#0 /var/www/app/public/index.php(17): Checkout->pay()\n#1 {main}"
    }],
    "context": {
      "host": "www.example.com", "uri": "/checkout?step=2",
      "method": "POST", "status": 500, "ip": "203.0.113.7",
      "ua": "Mozilla/5.0 (X11; Linux x86_64; rv:131.0) Gecko/20100101 Firefox/131.0",
      "userId": "1234", "dir": "/var/www/app",
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "extra": {"orderId": 7}
    }
  }
]

Fields

FieldTypeRequiredLimitWhat it does
vintegerno1The contract version
runtimestringnosee the noteWhat ran the code; an unknown one is stored as php
entrystringnoweb, cli, workerHow the code ran: a request, a command, a worker; web when absent
kindstringnoerror, not_found, securityWhat the event is; error when absent. See Kinds
priorityintegerno0–7Syslog severity, 0 emergency to 7 debug; 3 when absent
timestampstring or numbernoISO 8601, epoch s or msWhen it happened; the receive time is kept apart
releasestringno≤ 64 charsThe deploy label: a git sha, a version, a build number
environmentstringno≤ 64 charsThe stage; a stage other than production groups apart
tagsarray or stringno≤ 10 tagsFilterable tags; one string is split on , ; and spaces
clientstringno≤ 64 charsYour sender, as name/version
messagestringone name≤ 2,048 charsThe headline; events[0].message when absent
eventsarrayone namefirst 10 keptThe exception chain, outermost first
events[].messagestringone name≤ 2,048 charsThis exception's message
events[].classNamestringone name≤ 256 charsThe exception class; a security event's name
events[].filestringone name≤ 512 charsThe file that threw
events[].lineintegernoThe line; never part of the grouping
events[].backtracestringno≤ 8,192 charsThe stack trace as text
events[].previousbooleannotrue for a chained (previous) exception
events[].codeobjectno≤ 25 lines of 300 charsSource around the throw: start, line, lines
context.hoststringno≤ 255 charsThe site's host: the EVENTS grid's application column
context.uristringno≤ 2,048 charsThe request's path and query
context.methodstringno≤ 16 charsThe HTTP method
context.statusintegerno100–599The status the request ended with
context.refererstringno≤ 2,048 charsThe referring page
context.ipstringnoan IP addressThe visitor's address; anything else is dropped
context.uastringno≤ 512 charsThe visitor's user agent
context.sessionIdstringno≤ 128 charsThe session
context.userIdstringno≤ 64 charsYour internal user id, never a login name
context.traceIdstringno≤ 64 charsThe trace id: links one request across services
context.countrystringnoISO 3166 alpha-2The visitor's country as your CDN resolved it
context.dirstringno≤ 512 charsThe deploy root, stripped from file paths
context.argsarrayno50 of 512 charsThe command line, for entry: "cli"
context.requestobjectnosee belowThe request that failed, for display and replay
context.extraobjectno64 KBAnything else; a few keys are read, see below

One name: every event needs at least one of message, events[0].message, events[0].className or events[0].file. runtime is one of php, node, python, go, java, dotnet, ruby, rust or browser.

Kinds

kindWhat it isStored priorityTaken while
errorA fault in the codeas sent, 3 when absentits priority is within accept errors for priority ≤ (DATA tab)
not_foundA request for something missing; the path, without its query, is the messagealways 6accept 404 access events is on (DATA tab)
securityA refusal or audit line; its name in events[0].classNamethe name's default, or more severeaccept security events is on (SECURITY tab)
Security nameDefault prioritySend it when
auth_failure6 Infoa login fails
auth_success4 Warning; 6 Info under 3 failuresa login succeeds after recent failures; the count in extra.failures
csrf_reject6 Infoa request fails its CSRF token or nonce
permission_denied6 Infoa user is refused an action
rate_limited6 Infoyour own rate limit refuses a request
validation_refused6 Infoinput is refused as invalid or hostile
privileged_action5 Noticea role grant, a plugin install, an option flip; extra.action names it

A security event may carry a more severe priority (a lower number) than its default; a less severe one is ignored. A name not on the list is dropped while the request still answers 202, so read accepted. Report auth_success only after failures, never for every login.

Names the official clients send
NameDefault prioritySent when
shield_observe6 Infoa Shield rule matches a request and lets it through
shield_block6 Infoa Shield rule set to block refuses a request
shield_rate6 Infoa Shield rate rule's limit is passed
file_executed4 Warninga PHP file nobody shipped runs on a WordPress site
sensor_goodbye5 Noticethe WordPress plugin is deactivated
sensor_settings5 Noticethe plugin's own settings change (names only)

Responses

StatusWhenWhat the client does
202Queued: {"success": true, "accepted": 1}; the event shows in EVENTS about a second laterNothing; fewer than sent is normal
400Malformed JSON, an empty batch, more than 50 events, an entry that is no object, or one without a nameFix the sender; never retry
401X-Codesafe-Key is missing, or no active project holds itStop sending; check the key
405The method is not POSTFix the sender
413The body is over 256 KBSend fewer or shorter events
429The project's 3,000 requests or 15,000 events a minute are spent; Retry-After: 60Retry once after it, or drop
503The queue or the registry is down, or intake pauses near the memory ceiling; often Retry-After: 30Retry once after it, or drop

Notes

  • Post the array itself: a batch wrapped in {"errors": [...]} has no name and answers 400.
  • One event without a name fails the whole batch.
  • accepted counts what passed the project's gates; a dropped event has no answer of its own.
  • context.ip is the only source of the visitor's address: the connection's address is your server's, and codesafe never uses it.
  • Redact before you send. codesafe's own scrub is a backstop, not the plan.
What accepted leaves out

An error less severe than the project's accept priority; a not_found or security event while the project's switch for it is off, or a security name not on the list; a runtime: "browser" event thrown by a browser extension, an in-app browser or, with the first-party filter on, a script on another host.

The context.extra keys codesafe reads
KeyWhat it becomes
failuresan integer 0–9999: the failures before an auth_success; rules ask for it
actiona token [a-z][a-z0-9_]{0,31}: the kind of privileged_action, part of its grouping
tagsmore tags for this event, joined with the top-level tags
webdrivertrue flags the event webdriver
scriptsNotLoaded, scriptsFaileda non-empty list flags it scripts_missing or scripts_failed
The request bag, context.request
KeyWhat it holds
get, post, cookiesthe parsed query, form fields and cookies
contentTypewhat the application parsed the body as
bodythe body; stored parsed and re-encoded, at most 8 KB
headersup to 24 headers; only accept*, content-type, x-requested-with and your own x-… names are kept

request and extra keep 6 levels, 100 entries per level and 4,096 chars per value. events, request, args and extra keep 64 KB of JSON each; past it the whole value is stored as {"_truncated": true}. get, post, cookies and body are stripped from an event after 30 days by default.

What codesafe redacts and masks
  • A key with a secret name (password, token, secret, authorization, cookie, api key, nonce, csrf, otp …) keeps its name; its value becomes [redacted].
  • E-mail addresses and username fields are masked, and so are secret query parameters in uri, referer and args.
  • A body is parsed by its contentType; one that does not parse is dropped. A login or password-reset endpoint stores no body at all.
  • Names, phone numbers, addresses, IBANs and card numbers in stored request data are pseudonymised.
How events group into issues

An event's fingerprint is its project, kind, runtime, class, message and file (relative to context.dir), plus its environment when that is not production. Line numbers, the entry and the numbers and quoted values in a message are left out, so one fault groups across deploys. A browser error leaves the file out too. A security event groups by name, extra.action and context.userId, never by its message. An auth_success issue is titled by the login with the most failures before it, and anew when it comes back after a resolve. A project keeps 10 stages other than production and, per security name, 200 accounts apart; past that they share an issue.

Legacy names, and other fields in the answer

X-Console-Key is read when X-Codesafe-Key is absent. A type field from older senders (http, cli, js, node, 404, security) is read as the runtime, entry and kind it stands for. New senders use neither.

In the answer, processed: true means codesafe stored the events during the request instead of queueing them. shield and software are version tokens for the official clients; ignore them.