Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. The release object
  2. List releases
  3. Create or update a release
  4. Get a release
  5. List a release’s source maps
  6. Upload source maps
  7. Delete a release’s source maps

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.

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 EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Only releases first seen or deployed after this moment.

    Default: 90d

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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 EngineCloud

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

    Where it was deployed.

    Default: production

  • 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

Terminal
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
      }
    ]
  }
}

Response200

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

  • 400invalid_request

    version is missing or has characters that are not allowed, or a list is too long. param names the field.

  • 413payload_too_large

    The body is larger than 2 MiB.

Get a release

GET /v1/releases/{version} EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

Request

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

Response200

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

  • 404not_found

    The project has no release with this version in this environment.

List a release’s source maps

GET /v1/releases/{version}/sourcemaps EngineCloud

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

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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

  • 404not_found

    The project has no release with this version.

Upload source maps

POST /v1/releases/{version}/sourcemaps EngineCloud

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

Terminal
# 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"
    }
  ]
}

Response200

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

  • 400invalid_request

    files is empty or longer than 2,000, or an entry lacks url_path, map_size or map_sha256.

  • 409limit_reached

    The release already holds 20,000 maps.

Delete a release’s source maps

DELETE /v1/releases/{version}/sourcemaps EngineCloud

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

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

Errors

  • 404not_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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close