# Releases and source maps

> Register a release with what changed in it, and upload its source maps so stacks show your own files and lines.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/releases-and-source-maps/

For agents: Reference of the Releases and source maps endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

A release is one version of your app. Its `version` is the string your SDK sends as `release`: use the short
git commit (`4f2a91c`). A release is created by itself the first time an event carries a new version. Create
it yourself, from your build, to add what the engine cannot know: the commit, the previous version and what
changed. That is what lets the agent say «since yesterday's change» and name the change.

Source maps turn `checkout-3f9c.js:1:48211` into `src/checkout/checkout.tsx:142`. Upload them during your
build, then delete them from what you publish. The `sypnia sourcemaps upload` command does all of it; see the
[CLI reference](https://docs.sypnia.com/cli/commands).

These endpoints write, so they need an API token with the `admin` scope. Keep that token in your CI's
secrets.

## The release object

**Fields:**

- `version` (string, optional): The release's name. Unique per project and environment.
- `environment` (string, optional)
- `deployed_at` (timestamp or null, optional): When it went live, as you said. `null` for a release the engine only learned from events.
- `first_seen` (timestamp or null, optional): The first event that carried it.
- `last_seen` (timestamp or null, optional)
- `commit` (string or null, optional)
- `previous_version` (string or null, optional)
- `repository` (string or null, optional)
- `source_maps` (object, optional): How many maps were registered and how many arrived.
- `new_problems` (integer, optional): Problems first seen in this release.
- `sessions` (integer, optional): Sessions that ran on it.
- `changes` (object or null, optional): What changed, as sent, or read from GitHub on Sypnia Cloud. `null` when unknown. Not in lists.

## List releases

`GET /v1/releases` \[Engine, Cloud]

The project's releases, newest first, each with how many problems were first seen in it.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `90d`): Only releases first seen or deployed after this moment.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/releases" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "version": "4f2a91c",
      "environment": "production",
      "deployed_at": "2026-03-11T18:40:00Z",
      "first_seen": "2026-03-11T18:41:12Z",
      "last_seen": "2026-03-12T10:31:58Z",
      "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
      "previous_version": "9c1e7b2",
      "repository": "https://github.com/acme/shop",
      "source_maps": {
        "files": 42,
        "uploaded": 42
      },
      "new_problems": 1,
      "sessions": 131
    },
    {
      "version": "9c1e7b2",
      "environment": "production",
      "deployed_at": "2026-03-09T15:12:00Z",
      "first_seen": "2026-03-09T15:13:40Z",
      "last_seen": "2026-03-12T02:10:07Z",
      "commit": "9c1e7b2a9f0b4c2d1e6f5a7b8c9d0e1f2a3b4c5d",
      "previous_version": "2e6b0f4",
      "repository": "https://github.com/acme/shop",
      "source_maps": {
        "files": 42,
        "uploaded": 42
      },
      "new_problems": 0,
      "sessions": 890
    }
  ],
  "next_cursor": null
}
```

## Create or update a release

`POST /v1/releases` \[Engine, Cloud]

Registers a release, or adds to one that exists (the same `version` and `environment`): fields you send
replace the stored ones, fields you leave out stay. Call it from your build or deploy, once per release.

`changes` is what lets the agent name the cause. Send the commits and the files changed since
`previous_version`. Patches (the diff of each file) are optional: they make the analysis sharper and they are
your source code, so they are only stored if you send them. On Sypnia Cloud, with the GitHub App connected, you
can leave `changes` out: Sypnia reads the comparison from GitHub.

**Authentication:** API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Body:**

- `version` (string, up to 40 characters, required): The release's name, the same string your SDK sends as `release`. Use the short git commit.
- `environment` (string, up to 40 characters, optional, default `production`): Where it was deployed.
- `deployed_at` (timestamp, optional): When it went live. Defaults to now.
- `commit` (string, up to 64 characters, optional): The full git commit.
- `previous_version` (string, up to 40 characters, optional): The release it replaced. Defaults to the latest release of the environment.
- `repository` (URL, up to 300 characters, optional): The repository's web URL. Links in the app and in prompts point into it.
- `changes` (object, optional): What changed since `previous_version`.

**Limits**

- `version`: 1 to 40 characters of `A-Z a-z 0-9 . _ - +`, the same limit as the `ver` field of events.
- `changes.commits`: up to 200. `changes.files`: up to 500.
- `patch`: up to 20,000 characters per file and 200,000 per release. Longer patches are cut and marked `truncated`.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/releases" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data @release.json
```

**Request body:**

```json
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }"
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2
      }
    ]
  }
}
```

**Response (200):**

```json
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "first_seen": "2026-03-11T18:41:12Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "source_maps": {
    "files": 42,
    "uploaded": 42
  },
  "new_problems": 1,
  "sessions": 131,
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }",
        "truncated": false
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2,
        "patch": null,
        "truncated": false
      }
    ]
  }
}
```

**Errors:**

- `400` `invalid_request`: `version` is missing or has characters that are not allowed, or a list is too long. `param` names the field.
- `413` `payload_too_large`: The body is larger than 2 MiB.

## Get a release

`GET /v1/releases/{version}` \[Engine, Cloud]

One release with its `changes`.

**Authentication:** API token (`read`)

**Path parameters:**

- `version` (string, up to 40 characters, required): The release's version, as your SDK sends it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/releases/4f2a91c" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "first_seen": "2026-03-11T18:41:12Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "source_maps": {
    "files": 42,
    "uploaded": 42
  },
  "new_problems": 1,
  "sessions": 131,
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }",
        "truncated": false
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2,
        "patch": null,
        "truncated": false
      }
    ]
  }
}
```

**Errors:**

- `404` `not_found`: The project has no release with this version in this environment.

## List a release's source maps

`GET /v1/releases/{version}/sourcemaps` \[Engine, Cloud]

The maps registered for a release and whether each one arrived in storage. Use it to check an upload from CI.

**Authentication:** API token (`read`)

**Path parameters:**

- `version` (string, up to 40 characters, required): The release's version, as your SDK sends it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "map_size": 48211,
      "uploaded": true,
      "uploaded_at": "2026-03-11T18:38:11Z"
    },
    {
      "url_path": "/assets/index-a41b.js",
      "map_size": 912044,
      "uploaded": true,
      "uploaded_at": "2026-03-11T18:38:12Z"
    }
  ],
  "next_cursor": null
}
```

**Errors:**

- `404` `not_found`: The project has no release with this version.

## Upload source maps

`POST /v1/releases/{version}/sourcemaps` \[Engine, Cloud]

Uploading source maps takes two steps, because maps are too large to pass through the API.

1. Call this endpoint with the list of files. For each one say which JavaScript file it belongs to
   (`url_path`, the path your site serves it from) and the map's size and SHA-256. The answer has one upload
   link per map that the engine does not have yet.
2. `PUT` each map to its link, with the headers given, within 15 minutes.

That is all: there is no «finish» call. The engine uses a map from the moment it is in storage. Maps already
uploaded with the same SHA-256 are listed in `skipped`, so running the upload twice is cheap. The release is
created if it does not exist.

The engine finds the map for a stack frame by the frame's file path, so `url_path` must be the path as it
appears in the browser, without the origin. Bundlers that name maps differently from their files (Turbopack)
are handled because you name the pair here.

Source maps are kept for 90 days after the release was last seen. Do not publish them: delete the `.map` files
from what you deploy.

**Authentication:** API token (`admin`)

**Path parameters:**

- `version` (string, up to 40 characters, required): The release's version, as your SDK sends it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Body:**

- `files` (array of object, up to 2,000 items, required): The maps to upload.
- `files[].url_path` (string, up to 1,000 characters): The path the JavaScript file is served from, starting with `/`, without the origin or a query.
- `files[].map_size` (integer, 1 to 67,108,864): The map's size in bytes.
- `files[].map_sha256` (string): The map's SHA-256, in hex.

**Limits**

- Files in one call: 2,000. Call again for more.
- One map: 64 MB. Larger maps are refused (`map_too_large` in `skipped`) and their frames stay minified.

**Request:**

```bash
# 1. Ask for upload links
curl -X POST "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data @maps.json

# 2. Upload each map to its link
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  --data-binary @dist/assets/checkout-3f9c.js.map
```

**Request body:**

```json
{
  "files": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "map_size": 48211,
      "map_sha256": "9b1f6c0a7d2e4b8f3a5c1e9d7b0f2a4c6e8d0b2f4a6c8e0d1b3f5a7c9e1d3b5f"
    },
    {
      "url_path": "/assets/index-a41b.js",
      "map_size": 912044,
      "map_sha256": "1d3b5f7a9c1e3d5b7f9a1c3e5d7b9f1a3c5e7d9b1f3a5c7e9d1b3f5a7c9e1d3b"
    }
  ]
}
```

**Response (200):**

```json
{
  "release": "4f2a91c",
  "uploads": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "method": "PUT",
      "upload_url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/sourcemaps/4f2a91c/…?X-Amz-Signature=…",
      "headers": {
        "Content-Type": "application/json"
      },
      "expires_at": "2026-03-11T18:52:00Z"
    }
  ],
  "skipped": [
    {
      "url_path": "/assets/index-a41b.js",
      "reason": "already_uploaded"
    }
  ]
}
```

**Errors:**

- `400` `invalid_request`: `files` is empty or longer than 2,000, or an entry lacks `url_path`, `map_size` or `map_sha256`.
- `409` `limit_reached`: The release already holds 20,000 maps.

## Delete a release's source maps

`DELETE /v1/releases/{version}/sourcemaps` \[Engine, Cloud]

Deletes every source map of the release. Stacks that were already translated stay translated; new failures in this release show minified frames.

**Authentication:** API token (`admin`)

**Path parameters:**

- `version` (string, up to 40 characters, required): The release's version, as your SDK sends it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errors:**

- `404` `not_found`: The project has no release with this version.

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
