Box
Send events Built
One HTTPS request with two headers. No SDK required, no agent to install, and nothing to rename before you start.
Your first event
export ENTRAIL_SECRET='...' # keep it out of shell history and argv
curl -sS https://<your-box>/v1/events \
-H "content-type: application/json" \
-H "x-entrail-access-id: <your access id>" \
-H "x-entrail-secret: $ENTRAIL_SECRET" \
-d '{
"action": "record.update",
"actor.type": "user",
"actor.id": "u_1043",
"outcome": "success",
"ts": "2026-09-26T02:33:02Z",
"event.description": "changed the amount on invoice 88123"
}'{ "status": "accepted",
"event_id": "01a0db8f-15ab-7235-85bc-bd56dc964dd0",
"received_at": "2026-09-26T02:33:02.635Z",
"payload_sha256": "89c0e2a9bd699bcf…6728",
"contract_version": "1.0.0-rc.5",
"seal_eta_seconds": 120 }Keep payload_sha256. It is our hash of the exact bytes you sent, and you can compute it yourself. If the two ever disagree, something changed your bytes in transit and you will know without asking us.
202 means accepted and on disk. It does not mean sealed; that follows within about seal_eta_seconds.
The six fields
Five are required, and the description is required too. What a project can choose is how strictly OPTIONAL fields are treated: fail-closed or fail-open, in project settings.
| Field | Rule |
|---|---|
| action | Dotted, such as record.update. The entrail. prefix is reserved. |
| actor.type | user · service_account · machine · db_account · ai_agent · api_key · system |
| actor.id | Any non-blank identifier, no control characters. |
| outcome | success · failure · denied · error · partial · pending |
| ts | RFC 3339. Your claim about when it happened. |
| event.description | Free text. |
Everything else is optional, and there are 140 fields in all: severity, correlation id, session, target, actor email, the AI fields and more. Fields we do not know are kept, not dropped. They are sealed with the rest and stay queryable, just unanalysed, so you never have to strip anything before sending.
About your timestamp
It is sealed exactly as you send it and never rewritten. Chain order, though, is ingest order, never your timestamps. That is deliberate: it removes any argument about whose clock was right. Your timestamp is recorded as a claim, and the box's own timestamps sit beside it.
Batches
Up to 1000 events or 5 MiB per request, with events as the body's only key. A single event may be up to 256 KiB. Each event is judged on its own, so one bad event does not reject the batch.
Getting the receipt
curl -sS https://<your-box>/v1/events/<event_id>/receipt \
-H "x-entrail-access-id: <your access id>" \
-H "x-entrail-secret: $ENTRAIL_SECRET"You get 404 until it is sealed, so poll every few seconds. There is no deadline: a receipt you did not collect at the time is still collectable later. What to do with it is in verify a receipt.
When something is refused
| Response | Meaning |
|---|---|
| 400 malformed_json | Not parseable, including a leading byte-order mark, which is invisible and will cost you an hour. Also duplicate JSON keys, invalid UTF-8, and an empty batch. |
| 400 body_hash_mismatch | You sent your own body hash and the bytes that arrived hash differently. |
| 401 unauthorized | Bad access id or secret. It never says which. |
| 409 conflict | A client id reused with a different body. Same id and same body is a duplicate, not an error. |
| 403 | The key was revoked or disabled. Distinct from 401, which means the credentials did not match. |
| 413 | Over the event or batch size limit. |
| 422 | Failed validation. The reason names the field, never the value. |
| 429 | Too many requests. Back off for the period in the Retry-After header. |
| 503 | Not accepting right now. Retry with backoff; nothing was stored. |
Two limits are a wall clock at the proxy rather than a processing budget: ten seconds to send your headers, 120 seconds to send your body. A client that stalls mid-upload is closed rather than left hanging.
Sending your own field names
You do not have to rename anything. A mapping profile is a dictionary held on your environment, your key to our field, and you send your native format untouched with an x-entrail-source header. Values are never altered, only keys are mapped, and the raw payload is sealed byte for byte regardless.
Send us a sample of real or realistic log lines and we will write the profile for you. Improving it later re-derives the readable projection from the sealed bytes, so a better mapping applies backwards across everything you have already sent. Nothing is ever re-sealed.
Coming soon: mapping your own custom fields yourself, in the console, without asking us. Until then we write the profile, which is usually a same-day job.