1. Call it once per deploy, with the API key your pipeline already has
POST /api/v1/errors/releases with a read-write API key: { "projectId": "<id>", "release": "v2.4.1", "commitSha": "a1b2c3d", "repoUrl": "https://github.com/acme/widgets" }. Or, with the realuptime CLI: realuptime errors releases announce --project-id <id> --release v2.4.1 --commit-sha a1b2c3d --repo-url https://github.com/acme/widgets.
2. It is safe to retry
The call is idempotent on (projectId, release): a flaky step that runs it twice for the same release updates the same row instead of creating a duplicate. Fields you leave out are left alone; a field sent explicitly as null clears it.
3. Link it to the release before it, or let realuptime infer one
Pass previousRelease with the earlier version string to link them explicitly, or omit it and realuptime infers the project's most recently seen OTHER release. Naming a previousRelease that hasn't shipped yet is refused (RU-4008): announce releases in the order they ship.
4. See the health rollup and the diff-range link
Once two consecutive releases both carry a commitSha and a repoUrl on GitHub or GitLab, their pages on /errors show new-issue and regression counts against the previous release, and an issue that first appeared in one of them gets a "view the diff range" link. realuptime never clones or scans the repository: this is a link to the host's own compare view, never a claim about which commit caused anything.
Go deeper
The full reference lives in the docs: API documentation. Error codes named above are each explained in the error-code reference.