A deploy step announces each release here the moment it goes live, so codesafe knows the release before any event names it.
Request
POST /api/v1/ingest/release
X-Codesafe-Key: <api_key>
Content-Type: application/json
The body is one JSON object, at most 16 KB. Send it once the new code serves traffic.
Example
curl
curl -X POST https://codesafe.example/api/v1/ingest/release \
-H "X-Codesafe-Key: $CODESAFE_KEY" \
-H "Content-Type: application/json" \
-d "{\"release\": \"$(git rev-parse --short HEAD)\", \"ref\": \"main\", \"source\": \"deploy.sh\"}"JSON
{
"release": "a3f9c21",
"at": "2026-10-30T14:05:00Z",
"ref": "main",
"source": "deploy.sh",
"environment": "production"
}Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
release | string or integer | yes | 1–64 chars, no control characters | The label your events carry in release |
at | string or number | no | ISO 8601, epoch s or ms; ≤ 5 minutes ahead | When the release went live; the time of the request when absent |
ref | string | no | ≤ 128 chars | The VCS ref, shown beside the release |
source | string | no | ≤ 32 chars: letters, digits, space, . _ / - | Who announced it, such as deploy.sh |
environment | string | no | ≤ 64 chars | The stage the release went to |
Responses
| Status | When | What the client does |
|---|---|---|
202 | Taken: {"success": true, "accepted": 1, "duplicate": false, "release": "a3f9c21", "at": 1793369100} | Nothing |
400 | Malformed JSON, or a field codesafe refuses; error names it | Fix the deploy step |
401 | X-Codesafe-Key is missing, or no active project holds it | Fix the key |
405 | The method is not POST | Fix the deploy step |
413 | The body is over 16 KB | Send only the fields above |
429 | The project's budget is spent; Retry-After: 60 | Retry once after it |
503 | codesafe cannot store it at the moment | Retry once a few seconds later |
Notes
releasemust be the exact string your senders put in each event'srelease; that string joins the two.- A repeat is a duplicate: it answers
accepted: 0,duplicate: true, and keeps the earliestat. A deploy is one moment. - The answer's
atis the stored moment, in epoch seconds. - No project switch gates this endpoint: the key is the only gate.
- The announce is safe to resend after a timeout.
What the announce changes in codesafe
STATS shows the release on its release rail from the moment of the announce, with no event yet. Release comparison, also the MCP tool compare_releases, and the check whether a resolved issue stays quiet measure from the real deploy time instead of the first event that names the release.
How at is read
A number below 100,000,000,000 is epoch seconds, anything larger epoch milliseconds. A string must start with a date, YYYY-MM-DD; a word such as yesterday is refused. A moment in the past is fine, so a missed release can be announced later; more than 5 minutes in the future answers 400.
Repeats and how many are kept
A repeat keeps the earliest at, and a non-empty ref, source or environment it carries replaces the stored one. A project keeps its 200 newest announced releases.