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
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
v | integer | no | 1 | The contract version |
runtime | string | no | see the note | What ran the code; an unknown one is stored as php |
entry | string | no | web, cli, worker | How the code ran: a request, a command, a worker; web when absent |
kind | string | no | error, not_found, security | What the event is; error when absent. See Kinds |
priority | integer | no | 0–7 | Syslog severity, 0 emergency to 7 debug; 3 when absent |
timestamp | string or number | no | ISO 8601, epoch s or ms | When it happened; the receive time is kept apart |
release | string | no | ≤ 64 chars | The deploy label: a git sha, a version, a build number |
environment | string | no | ≤ 64 chars | The stage; a stage other than production groups apart |
tags | array or string | no | ≤ 10 tags | Filterable tags; one string is split on , ; and spaces |
client | string | no | ≤ 64 chars | Your sender, as name/version |
message | string | one name | ≤ 2,048 chars | The headline; events[0].message when absent |
events | array | one name | first 10 kept | The exception chain, outermost first |
events[].message | string | one name | ≤ 2,048 chars | This exception's message |
events[].className | string | one name | ≤ 256 chars | The exception class; a security event's name |
events[].file | string | one name | ≤ 512 chars | The file that threw |
events[].line | integer | no | The line; never part of the grouping | |
events[].backtrace | string | no | ≤ 8,192 chars | The stack trace as text |
events[].previous | boolean | no | true for a chained (previous) exception | |
events[].code | object | no | ≤ 25 lines of 300 chars | Source around the throw: start, line, lines |
context.host | string | no | ≤ 255 chars | The site's host: the EVENTS grid's application column |
context.uri | string | no | ≤ 2,048 chars | The request's path and query |
context.method | string | no | ≤ 16 chars | The HTTP method |
context.status | integer | no | 100–599 | The status the request ended with |
context.referer | string | no | ≤ 2,048 chars | The referring page |
context.ip | string | no | an IP address | The visitor's address; anything else is dropped |
context.ua | string | no | ≤ 512 chars | The visitor's user agent |
context.sessionId | string | no | ≤ 128 chars | The session |
context.userId | string | no | ≤ 64 chars | Your internal user id, never a login name |
context.traceId | string | no | ≤ 64 chars | The trace id: links one request across services |
context.country | string | no | ISO 3166 alpha-2 | The visitor's country as your CDN resolved it |
context.dir | string | no | ≤ 512 chars | The deploy root, stripped from file paths |
context.args | array | no | 50 of 512 chars | The command line, for entry: "cli" |
context.request | object | no | see below | The request that failed, for display and replay |
context.extra | object | no | 64 KB | Anything 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
kind | What it is | Stored priority | Taken while |
|---|---|---|---|
error | A fault in the code | as sent, 3 when absent | its priority is within accept errors for priority ≤ (DATA tab) |
not_found | A request for something missing; the path, without its query, is the message | always 6 | accept 404 access events is on (DATA tab) |
security | A refusal or audit line; its name in events[0].className | the name's default, or more severe | accept security events is on (SECURITY tab) |
| Security name | Default priority | Send it when |
|---|---|---|
auth_failure | 6 Info | a login fails |
auth_success | 4 Warning; 6 Info under 3 failures | a login succeeds after recent failures; the count in extra.failures |
csrf_reject | 6 Info | a request fails its CSRF token or nonce |
permission_denied | 6 Info | a user is refused an action |
rate_limited | 6 Info | your own rate limit refuses a request |
validation_refused | 6 Info | input is refused as invalid or hostile |
privileged_action | 5 Notice | a 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
| Name | Default priority | Sent when |
|---|---|---|
shield_observe | 6 Info | a Shield rule matches a request and lets it through |
shield_block | 6 Info | a Shield rule set to block refuses a request |
shield_rate | 6 Info | a Shield rate rule's limit is passed |
file_executed | 4 Warning | a PHP file nobody shipped runs on a WordPress site |
sensor_goodbye | 5 Notice | the WordPress plugin is deactivated |
sensor_settings | 5 Notice | the plugin's own settings change (names only) |
Responses
| Status | When | What the client does |
|---|---|---|
202 | Queued: {"success": true, "accepted": 1}; the event shows in EVENTS about a second later | Nothing; fewer than sent is normal |
400 | Malformed JSON, an empty batch, more than 50 events, an entry that is no object, or one without a name | Fix the sender; never retry |
401 | X-Codesafe-Key is missing, or no active project holds it | Stop sending; check the key |
405 | The method is not POST | Fix the sender |
413 | The body is over 256 KB | Send fewer or shorter events |
429 | The project's 3,000 requests or 15,000 events a minute are spent; Retry-After: 60 | Retry once after it, or drop |
503 | The queue or the registry is down, or intake pauses near the memory ceiling; often Retry-After: 30 | Retry once after it, or drop |
Notes
- Post the array itself: a batch wrapped in
{"errors": [...]}has no name and answers400. - One event without a name fails the whole batch.
acceptedcounts what passed the project's gates; a dropped event has no answer of its own.context.ipis 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
| Key | What it becomes |
|---|---|
failures | an integer 0–9999: the failures before an auth_success; rules ask for it |
action | a token [a-z][a-z0-9_]{0,31}: the kind of privileged_action, part of its grouping |
tags | more tags for this event, joined with the top-level tags |
webdriver | true flags the event webdriver |
scriptsNotLoaded, scriptsFailed | a non-empty list flags it scripts_missing or scripts_failed |
The request bag, context.request
| Key | What it holds |
|---|---|
get, post, cookies | the parsed query, form fields and cookies |
contentType | what the application parsed the body as |
body | the body; stored parsed and re-encoded, at most 8 KB |
headers | up 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,refererandargs. - 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.