Source maps API

The source maps API stores the JavaScript source maps of a service release. Squasher uses them to resolve minified stack frames to the original file, line, column, and function. See Upload source maps for how Squasher matches a frame to a map.

Operations

Operation	Method and path	Access	Purpose
`sourcemaps.list`	`GET /v1/projects/{project_id}/sourcemaps`	`sourcemaps:read`	List uploaded source maps, optionally filtered by service and release.
`sourcemaps.upload`	`POST /v1/projects/{project_id}/sourcemaps`	`sourcemaps:write`	Upload source map files for a service release using multipart form data.
`sourcemaps.delete`	`DELETE /v1/projects/{project_id}/sourcemaps/{sourcemap_id}`	`sourcemaps:write`	Delete a source map by ID.
`sourcemaps.symbolicate`	`POST /v1/projects/{project_id}/sourcemaps/symbolicate`	`errors:read`	Resolve minified stack frames with the uploaded source maps. Reads only.

Uploads should include the release value that the SDK sends. Keep release names stable between event capture and upload.

Upload source maps

Send a multipart form with these fields:

Field	Description
`release`	Required. The release name that the SDK sends as `service.version`.
`service_name`	Optional. The `service.name` of the events that use these maps.
`files`	One or more map files. Repeat the field for each file. The file name is the map name.

Limits: at most 200 files, 32 MiB for each file, and 96 MiB for each request. A larger request gets status 413; send the files in more than one request. A file name must be a relative path without . or .. parts, and names must not contain control characters (status 400). Each upload is stored as a new object, so a new upload of the same file name does not change older uploads. The response has status 201:

{
  "release": "3f9a2c1",
  "service_name": "web",
  "files_uploaded": 1,
  "files": [
    {
      "id": "c2f1d7a4-5b8e-4a3c-9f61-2d0e7b4a8c19",
      "filename": "app-3f9a.js.map",
      "size_bytes": 482113,
      "debug_id": "0b6a1d6c-8a5e-4f4b-9a3f-2c1e5d7f9a10"
    }
  ]
}

debug_id is the debugId field of the map, or null when the bundler did not write one. A frame with this debug ID resolves to this map in any release. Each entry of sourcemaps.list also has debug_id.

Resolve stack frames

sourcemaps.symbolicate resolves up to 100 frames in one request. It changes no data.

Field	Description
`frames`	Required. 1 to 100 frames, each with `filename` and optional `lineno`, `colno`, `function`, `in_app`, and `debug_id`. Lines and columns start at 1.
`release`	The event release (`service.version`). Needed unless every frame has a debug ID.
`service_name`	The event service. Maps uploaded for another service are not used.
`context_lines`	Lines of original source on each side of the error line. Default 5, at most 10.

curl --request POST \
  --url "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/sourcemaps/symbolicate" \
  --header "x-squasher-key: $SQUASHER_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "release": "3f9a2c1",
    "service_name": "web",
    "context_lines": 2,
    "frames": [
      { "filename": "https://example.com/assets/app-3f9a.js", "lineno": 1, "colno": 5023, "function": "r" },
      { "filename": "https://example.com/assets/chunk-77b1.js", "lineno": 3, "colno": 12 }
    ]
  }'

The response lists the frames in request order:

{
  "frames": [
    {
      "status": "symbolicated",
      "reason": null,
      "hint": null,
      "raw": {
        "filename": "https://example.com/assets/app-3f9a.js",
        "lineno": 1,
        "colno": 5023,
        "function": "r"
      },
      "original": {
        "filename": "src/checkout/total.ts",
        "function": "applyDiscount",
        "lineno": 42,
        "colno": 11,
        "context": {
          "pre": ["export function applyDiscount(cart: Cart) {", "  const code = cart.discount;"],
          "line": "  return code.percent * cart.total;",
          "post": ["}", ""]
        }
      },
      "source_map": {
        "id": "c2f1d7a4-5b8e-4a3c-9f61-2d0e7b4a8c19",
        "filename": "app-3f9a.js.map",
        "release": "3f9a2c1",
        "matched_by": "filename"
      }
    },
    {
      "status": "unchanged",
      "reason": "no_matching_file",
      "hint": "No source map uploaded for this release matches the file name. Upload <file>.map with the release.",
      "raw": { "filename": "https://example.com/assets/chunk-77b1.js", "lineno": 3, "colno": 12 },
      "original": null,
      "source_map": null
    }
  ],
  "summary": { "symbolicated": 1, "total": 2 }
}

matched_by is debug_id or filename. context is null when the map has no sourcesContent for the file. When the map does not name the function, original.function is the function name of the raw frame. A frame that keeps its minified location has status: "unchanged", a reason, and a hint:

`reason`	Meaning
`missing_position`	The frame has no line and column.
`no_release`	The request has no release, and the frame has no debug ID.
`no_source_map`	No source maps are uploaded for this release, or none has the frame’s debug ID.
`no_matching_file`	Maps exist for the release, but none matches the frame’s file name.
`map_too_large`	The map is larger than 24 MB. Squasher does not read it.
`map_unreadable`	The map is not valid JSON.
`no_mapping`	The map has no mapping at this line and column.
`storage_unavailable`	Source map storage is not available. Try again later.

CLI and MCP

squasher sourcemaps list --project <project_id> --release <release>
squasher sourcemaps upload --project <project_id> --release <release> --service <service> dist
squasher sourcemaps symbolicate --project <project_id> --release <release> --service <service> FRAME...
squasher sourcemaps delete --project <project_id> <sourcemap_id>

squasher sourcemaps upload accepts .map files, bundle .js files, and directories. For a bundle, it uploads the map that the sourceMappingURL comment names, as <bundle>.map. squasher sourcemaps symbolicate takes frames as arguments, or a stack trace with --stack-file <file>. The hosted MCP server can list maps and resolve frames. Uploads need files, so they are an API or CLI task, not an MCP task.

const { frames, summary } = await client.sourcemaps.symbolicate({
  release: "3f9a2c1",
  service_name: "web",
  frames: [{ filename: "https://example.com/assets/app-3f9a.js", lineno: 1, colno: 5023 }],
});

Agent handoff

Check Squasher source maps for project <project_id> and release <release>. List current uploads, compare the release to SDK config, resolve one minified frame with sourcemaps.symbolicate, and ask before uploading or deleting source maps.

Related: Upload source maps.

Start here

Resources

Operations

Upload source maps

Resolve stack frames

CLI and MCP

Agent handoff

​Operations

​Upload source maps

​Resolve stack frames

​CLI and MCP

​Agent handoff

Operations

Upload source maps

Resolve stack frames

CLI and MCP

Agent handoff