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.
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
-
versionstring optionalThe release’s name. Unique per project and environment.
-
environmentstring optional -
deployed_attimestamp or null optionalWhen it went live, as you said.
nullfor a release the engine only learned from events. -
first_seentimestamp or null optionalThe first event that carried it.
-
last_seentimestamp or null optional -
commitstring or null optional -
previous_versionstring or null optional -
repositorystring or null optional -
source_mapsobject optionalHow many maps were registered and how many arrived.
-
new_problemsinteger optionalProblems first seen in this release.
-
sessionsinteger optionalSessions that ran on it.
-
changesobject or null optionalWhat changed, as sent, or read from GitHub on Sypnia Cloud.
nullwhen unknown. Not in lists.
List releases
/v1/releases EngineCloud The project’s releases, newest first, each with how many problems were first seen in it.
Query parameters
-
projectstring optionalThe 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. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalOnly releases first seen or deployed after this moment.
Default:
90d -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/releases" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"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
/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.
Query parameters
-
projectstring optionalThe 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
-
versionstring, up to 40 characters requiredThe release’s name, the same string your SDK sends as
release. Use the short git commit. -
environmentstring, up to 40 characters optionalWhere it was deployed.
Default:
production -
deployed_attimestamp optionalWhen it went live. Defaults to now.
-
commitstring, up to 64 characters optionalThe full git commit.
-
previous_versionstring, up to 40 characters optionalThe release it replaced. Defaults to the latest release of the environment.
-
repositoryURL, up to 300 characters optionalThe repository’s web URL. Links in the app and in prompts point into it.
-
changesobject optionalWhat changed since
previous_version.
Limits
version: 1 to 40 characters ofA-Z a-z 0-9 . _ - +, the same limit as theverfield 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 markedtruncated.
Request
curl -X POST "https://api.sypnia.com/v1/releases" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
--data @release.jsonRequest body
{
"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
{
"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_requestversionis missing or has characters that are not allowed, or a list is too long.paramnames the field. - 413
payload_too_largeThe body is larger than 2 MiB.
Get a release
/v1/releases/{version} EngineCloud One release with its changes.
Path parameters
-
versionstring, up to 40 characters requiredThe release’s version, as your SDK sends it. URL-encode it.
Query parameters
-
projectstring optionalThe 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. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production
Request
curl "https://api.sypnia.com/v1/releases/4f2a91c" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"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_foundThe project has no release with this version in this environment.
List a release’s source maps
/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.
Path parameters
-
versionstring, up to 40 characters requiredThe release’s version, as your SDK sends it. URL-encode it.
Query parameters
-
projectstring optionalThe 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. -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"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_foundThe project has no release with this version.
Upload source maps
/v1/releases/{version}/sourcemaps EngineCloud Uploading source maps takes two steps, because maps are too large to pass through the API.
- 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. PUTeach 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.
Path parameters
-
versionstring, up to 40 characters requiredThe release’s version, as your SDK sends it. URL-encode it.
Query parameters
-
projectstring optionalThe 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
-
filesarray of object, up to 2,000 items requiredThe maps to upload.
-
files[].url_pathstring, up to 1,000 charactersThe path the JavaScript file is served from, starting with
/, without the origin or a query. -
files[].map_sizeinteger, 1 to 67,108,864The map’s size in bytes.
-
files[].map_sha256stringThe 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_largeinskipped) and their frames stay minified.
Request
# 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.mapRequest body
{
"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
{
"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_requestfilesis empty or longer than 2,000, or an entry lacksurl_path,map_sizeormap_sha256. - 409
limit_reachedThe release already holds 20,000 maps.
Delete a release’s source maps
/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.
Path parameters
-
versionstring, up to 40 characters requiredThe release’s version, as your SDK sends it. URL-encode it.
Query parameters
-
projectstring optionalThe 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
curl -X DELETE "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Errors
- 404
not_foundThe project has no release with this version.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.