Flare Flare Laravel Laravel PHP PHP JavaScript JavaScript Protocol Protocol

Sourcemaps

Sourcemaps allow Flare to map minified or bundled JavaScript stack traces back to your original source code. Without sourcemaps, error reports from production JavaScript will show obfuscated file names, line numbers, and column numbers that don't match your source.

How it works

  1. During your build step, upload your sourcemaps to Flare with a version_id.
  2. Configure your JavaScript SDK to send the same version_id as the sourcemapVersionId field on error reports.
  3. When Flare receives an error with a sourcemapVersionId, it looks up the matching sourcemaps and resolves each stack frame to the original source position.

Endpoint

POST https://flareapp.io/api/sourcemaps

Headers

Header Value Description
Content-Type application/json Required

Authentication

The sourcemap endpoint does not use the x-api-token header. Instead, authentication happens via the key field in the request body. Use your project's public API key for this endpoint. The public key is safe to use in build scripts and CI/CD pipelines since it can only be used to upload sourcemaps and send error reports.

Payload

Field Type Validation Description
key string required Project's public API key
version_id string required Unique identifier for this build version
relative_filename string required Relative path to the JS file from the domain root (e.g. /js/app.js)
sourcemap string required Base64-encoded, gzip-compressed sourcemap content

Example

{
    "key": "your-project-public-api-key",
    "version_id": "abc123-some-unique-build-id",
    "relative_filename": "/js/app.js",
    "sourcemap": "base64-encoded-gzipped-sourcemap-content"
}

Encoding

Sourcemap content must be gzip-compressed and then base64-encoded before sending:

payload.sourcemap = base64_encode(gzip_compress(sourcemap_json_string))

Responses

Status Description
204 Sourcemap uploaded successfully
403 Invalid or missing API key, or team has no active subscription
422 Validation error (missing required fields or invalid sourcemap)

Sourcemap validation will return a 422 when:

  • The base64 or gzip encoding is invalid
  • The decompressed content is empty or not valid JSON
  • Required sourcemap keys are missing (version, file, sources, names, or mappings)
  • The sourcemap version is not 3

Multiple files per version

A single build typically produces multiple JavaScript files, each with its own sourcemap. Upload one request per file, using the same version_id for all files in the same build. Flare groups sourcemaps by version_id and uses the relative_filename to match stack frames to the correct sourcemap.

Linking errors to sourcemaps

When sending an error report to the errors endpoint, include the sourcemapVersionId field with the same value you used as version_id during upload:

{
    "sourcemapVersionId": "abc123-some-unique-build-id",
    "exceptionClass": "TypeError",
    "stacktrace": [...]
}

Flare will then resolve each stack frame's file, lineNumber, and columnNumber against the uploaded sourcemaps for that version.

Attributes Payload