DOCUMENTATION

Releases

The deploy step tells codesafe a release went out.

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

FieldTypeRequiredLimitWhat it does
releasestring or integeryes1–64 chars, no control charactersThe label your events carry in release
atstring or numbernoISO 8601, epoch s or ms; ≤ 5 minutes aheadWhen the release went live; the time of the request when absent
refstringno≤ 128 charsThe VCS ref, shown beside the release
sourcestringno≤ 32 chars: letters, digits, space, . _ / -Who announced it, such as deploy.sh
environmentstringno≤ 64 charsThe stage the release went to

Responses

StatusWhenWhat the client does
202Taken: {"success": true, "accepted": 1, "duplicate": false, "release": "a3f9c21", "at": 1793369100}Nothing
400Malformed JSON, or a field codesafe refuses; error names itFix the deploy step
401X-Codesafe-Key is missing, or no active project holds itFix the key
405The method is not POSTFix the deploy step
413The body is over 16 KBSend only the fields above
429The project's budget is spent; Retry-After: 60Retry once after it
503codesafe cannot store it at the momentRetry once a few seconds later

Notes

  • release must be the exact string your senders put in each event's release; that string joins the two.
  • A repeat is a duplicate: it answers accepted: 0, duplicate: true, and keeps the earliest at. A deploy is one moment.
  • The answer's at is 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.