> ## Documentation Index
> Fetch the complete documentation index at: https://sentrydocs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Releases

> Create releases and associate commits via the API

Releases let Sentry correlate errors with the version of your code that introduced them. When you create a release and associate it with commits, Sentry can identify the likely commit that caused a regression and suggest owners.

***

## List releases

```
GET /api/0/organizations/{organization_id_or_slug}/releases/
```

Returns a paginated list of releases for the organization.

**Required scope:** `project:releases`

### Query parameters

<ParamField query="query" type="string">
  Filters releases whose version string starts with this value.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from the `Link` response header.
</ParamField>

### Example request

```bash theme={null}
curl https://sentry.io/api/0/organizations/my-org/releases/ \
  -H "Authorization: Bearer sntrys_TOKEN"
```

### Example response

```json theme={null}
[
  {
    "id": 2,
    "version": "2.0rc2",
    "shortVersion": "2.0rc2",
    "ref": "6ba09a7c53235ee8a8fa5ee4c1ca8ca886e7fdbb",
    "url": null,
    "dateCreated": "2018-11-06T21:20:08.033Z",
    "dateReleased": null,
    "commitCount": 0,
    "deployCount": 0,
    "newGroups": 0,
    "firstEvent": null,
    "lastEvent": null,
    "lastCommit": null,
    "lastDeploy": null,
    "authors": [],
    "projects": [
      { "name": "Pump Station", "slug": "pump-station" }
    ]
  }
]
```

***

## Create a release

```
POST /api/0/organizations/{organization_id_or_slug}/releases/
```

Creates a new release and optionally associates it with commits. You can supply commit data directly or use `refs` to have Sentry pull commits from a connected repository integration.

**Required scope:** `project:releases`

### Request body

<ParamField body="version" type="string" required>
  A version identifier for this release. This can be a version number, a commit hash, a semantic version string, or any value that uniquely identifies the build.
</ParamField>

<ParamField body="projects" type="array" required>
  An array of project slugs to associate with this release. At least one project is required.
</ParamField>

<ParamField body="ref" type="string">
  An optional commit reference, useful when a tagged version has been provided.
</ParamField>

<ParamField body="url" type="string">
  A URL to the release — for example, a link to the changelog or the source code at this version.
</ParamField>

<ParamField body="dateReleased" type="string">
  An ISO 8601 datetime indicating when the release went live. Defaults to the current time if omitted.
</ParamField>

<ParamField body="refs" type="array">
  An array of repository references. Use this to tell Sentry which commits are included in this release by specifying the HEAD commit of each repository. Sentry will automatically resolve the commit range since the previous release.

  <Expandable title="refs object fields">
    <ParamField body="repository" type="string" required>
      The full name of the repository, e.g. `my-org/my-repo`.
    </ParamField>

    <ParamField body="commit" type="string" required>
      The HEAD commit SHA for this release. You can also supply a range in the form `previousCommit..commit`.
    </ParamField>

    <ParamField body="previousCommit" type="string">
      The HEAD commit SHA of the previous release. Include this the first time you send commit data so Sentry knows where to start the range.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="commits" type="array">
  An explicit list of commit objects. Use this when you want to send commit metadata directly rather than using a repository integration.

  <Expandable title="commit object fields">
    <ParamField body="id" type="string" required>
      The commit SHA.
    </ParamField>

    <ParamField body="repository" type="string">
      The full repository name. If omitted, Sentry generates one from the organization ID.
    </ParamField>

    <ParamField body="message" type="string">
      The commit message.
    </ParamField>

    <ParamField body="author_name" type="string">
      The commit author's name.
    </ParamField>

    <ParamField body="author_email" type="string">
      The commit author's email. Required to enable the suggested assignee feature.
    </ParamField>

    <ParamField body="timestamp" type="string">
      ISO 8601 timestamp of the commit. Used to sort commits in the release.
    </ParamField>

    <ParamField body="patch_set" type="array">
      List of files changed in this commit. Include this to enable suspect commit detection.

      <Expandable title="patch_set object fields">
        <ParamField body="path" type="string" required>
          The file path. Both forward and backward slashes are supported.
        </ParamField>

        <ParamField body="type" type="string" required>
          The change type: `A` (added), `M` (modified), or `D` (deleted).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://sentry.io/api/0/organizations/my-org/releases/ \
  -H "Authorization: Bearer sntrys_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "refs": [{"repository": "my-org/my-repo", "commit": "abc123"}],
    "projects": ["my-project"]
  }'
```

### Example response

```json theme={null}
{
  "id": 2,
  "version": "1.0.0",
  "shortVersion": "1.0.0",
  "ref": null,
  "url": null,
  "dateCreated": "2019-01-03T00:12:55.109Z",
  "dateReleased": null,
  "commitCount": 0,
  "deployCount": 0,
  "newGroups": 0,
  "firstEvent": null,
  "lastEvent": null,
  "lastCommit": null,
  "lastDeploy": null,
  "authors": [],
  "projects": [
    { "name": "My Project", "slug": "my-project" }
  ]
}
```

***

## List commits for a release

```
GET /api/0/organizations/{organization_id_or_slug}/releases/{version}/commits/
```

Returns the commits associated with a release.

**Required scope:** `project:releases`

### Path parameters

<ParamField path="version" type="string" required>
  The release version identifier.
</ParamField>

### Example request

```bash theme={null}
curl "https://sentry.io/api/0/organizations/my-org/releases/1.0.0/commits/" \
  -H "Authorization: Bearer sntrys_TOKEN"
```

***

## List files for a release

```
GET /api/0/organizations/{organization_id_or_slug}/releases/{version}/files/
```

Returns the source map and other files uploaded for a release.

**Required scope:** `project:releases`

### Example request

```bash theme={null}
curl "https://sentry.io/api/0/organizations/my-org/releases/1.0.0/files/" \
  -H "Authorization: Bearer sntrys_TOKEN"
```

<Tip>
  To upload source maps, use the Sentry CLI (`sentry-cli releases files upload-sourcemaps`) rather than the API directly. The CLI handles chunked uploads and source map processing automatically.
</Tip>