Create a release

Registers a new release. A release registered at build time shows up in Better Stack immediately, before its first error arrives.

POST https://errors.betterstack.com/api/v1/releases

Headers

Authorization

required string

Bearer $TOKEN

Content-Type

required string

application/json

Body parameters

version

required string

Release version or commit reference (e.g., v1.2.3).

applications

array

Array of application IDs to attach the release to. When omitted, the release is attached to every application that already reports this version, and nothing is registered when no application reports it yet. Omitting it is the typical choice when recording a deploy.

environment

string

Environment this release was deployed to (e.g., production). Pass an array to record multiple environments.

team_name

string

Scopes the registration to one team's applications when using global API token, which spans all your teams.

team_id

string

The SENTRY_ORG value, which the Sentry CLI integration forwards. Scopes the registration the same way as team_name. Prefer team_name when you call this endpoint directly.

201

Returns the registered release. The releases array lists the affected release IDs, one per application. An empty array means no application matched the version and nothing was recorded.

Response body

{
  "version": "v1.2.3",
  "applications": [
    123
  ],
  "environment": "production",
  "releases": [
    {
      "id": 456,
      "application_id": 123
    }
  ]
}

401

Unauthorized

Response body

{
  "errors": "Invalid authentication"
}

422

Unprocessable Entity - Missing Required Attributes

Response body

{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": [
    "version"
  ]
}

422

Unprocessable Entity - Unknown Application

Response body

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "applications": "Unknown applications: 999"
  }
}

422

Unprocessable Entity - Unknown Team. The ID in your browser URL is rejected here even though it names your team, so pass the SENTRY_ORG value instead.

Response body

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "team_id": "Unknown team: 123456"
  }
}

Example cURL

Example

Copied!

curl --request POST \
  --url https://errors.betterstack.com/api/v1/releases \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "version": "v1.2.3",
    "applications": [123],
    "environment": "production"
  }'

Registering a brand new version?

Pass applications. Without it, Better Stack only attaches the environment to applications that already report the version, so a version nothing has reported yet returns 201 with an empty releases array and records nothing. Fail your CI step when releases comes back empty.

Get a single release

Remove a release

Explore documentation

Create a release

Example cURL

Registering a brand new version?

Please accept cookies