# Create a release

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

[endpoint]
base_url = "https://errors.betterstack.com"
path = "/api/v1/releases"
method = "POST"

[[body_param]]
name = "version"
description = "Release version or commit reference (e.g., `v1.2.3`)."
required = true
type = "string"

[[body_param]]
name = "applications"
description = "Array of application IDs to attach the release to. When omitted, the release is attached to every application that already reports this version. Omitting it is the typical choice when recording a deploy."
required = false
type = "array"

[[body_param]]
name = "environment"
description = "Environment this release was deployed to (e.g., `production`). Pass an array to record multiple environments."
required = false
type = "string"

[[body_param]]
name = "team_id"
description = "ID of the team to register the release for, bare or `t`-prefixed (e.g., `123456` or `t123456`). Scopes a version-only registration to that team's applications. Needed with a global API token, which spans all your teams."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''Returns the registered release. The `releases` array lists the affected release IDs, one per application.'''
body = '''{
  "version": "v1.2.3",
  "applications": [123],
  "environment": "production",
  "releases": [
    {
      "id": 456,
      "application_id": 123
    }
  ]
}'''

[[response]]
status = 401
description = '''Unauthorized'''
body = '''{
  "errors": "Invalid authentication"
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Missing Required Attributes'''
body = '''{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": ["version"]
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Unknown Application'''
body = '''{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "applications": "Unknown applications: 999"
  }
}'''
[/responses]

#### Example cURL

```shell
[label Example]
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"
  }'
```