Source Maps API - Proliferate

Overview

The Source Maps API allows you to upload source map files and manage releases. Source maps enable Proliferate to resolve minified production stack traces back to original source code, making errors much easier to debug.

Authentication

Source map operations use Bearer token in header authentication with your project API key. See Authentication for details.

Upload Source Map

Upload a source map file for a specific release.

curl -X POST https://api.proliferate.com/api/v1/sourcemaps \
  -H "Authorization: Bearer pk_abc123def456ghi789" \
  -F "release=v1.2.3" \
  -F "url=~/static/js/main.abc123.js" \
  -F "url_prefix=~/" \
  -F "sourcemap=@dist/static/js/main.abc123.js.map"

Endpoint

POST /api/v1/sourcemaps

Request Parameters

release

string

required

Release version this source map belongs to

url

string

required

The URL of the JavaScript file (as it appears in stack traces)

sourcemap

file

required

The .map file (multipart form upload)

url_prefix

string

default:"~/"

URL prefix for matching stack trace URLs. Use ~/ for root-relative paths.

Response

Success (201 Created):

{
  "id": 42,
  "url": "~/static/js/main.abc123.js",
  "storage_path": "projects/123/releases/v1.2.3/static/js/main.abc123.js.map",
  "content_hash": "sha256:abc123...",
  "file_size": 524288,
  "created_at": "2025-01-15T10:30:00Z"
}

Error (401 Unauthorized):

{
  "detail": "Invalid authorization header. Use 'Bearer <api_key>'"
}

Create Release

Create a new release to associate source maps with.

curl -X POST https://api.proliferate.com/api/v1/releases \
  -H "Authorization: Bearer pk_abc123def456ghi789" \
  -F "version=v1.2.3" \
  -F "url_prefix=~/"

Endpoint

POST /api/v1/releases

Request Parameters

version

string

required

Version identifier (max 128 characters). Typically git SHA or semantic version.

url_prefix

string

default:"~/"

URL prefix for matching stack traces (max 512 characters)

Response

Success (201 Created):

{
  "id": 42,
  "project_id": 123,
  "version": "v1.2.3",
  "url_prefix": "~/",
  "created_at": "2025-01-15T10:30:00Z",
  "finalized_at": null,
  "source_map_count": 0
}

If a release with the same version already exists, it returns the existing release instead of creating a duplicate.

Finalize Release

Mark a release as complete after all source maps are uploaded.

curl -X POST https://api.proliferate.com/api/v1/releases/v1.2.3/finalize \
  -H "Authorization: Bearer pk_abc123def456ghi789"

Endpoint

POST /api/v1/releases/{version}/finalize

Path Parameters

version

string

required

Release version to finalize

Response

Success (200 OK):

{
  "id": 42,
  "project_id": 123,
  "version": "v1.2.3",
  "url_prefix": "~/",
  "created_at": "2025-01-15T10:30:00Z",
  "finalized_at": "2025-01-15T10:35:00Z",
  "source_map_count": 5
}

Error (404 Not Found):

{
  "detail": "Release 'v1.2.3' not found"
}

List Releases

Get all releases for a project.

GET /api/v1/projects/{project_id}/releases?limit=50&offset=0

Path Parameters

project_id

integer

required

Project ID

Query Parameters

limit

integer

default:50

Max releases to return

offset

integer

default:0

Pagination offset

Response

{
  "releases": [
    {
      "id": 42,
      "project_id": 123,
      "version": "v1.2.3",
      "url_prefix": "~/",
      "created_at": "2025-01-15T10:30:00Z",
      "finalized_at": "2025-01-15T10:35:00Z",
      "source_map_count": 5
    },
    {
      "id": 41,
      "project_id": 123,
      "version": "v1.2.2",
      "url_prefix": "~/",
      "created_at": "2025-01-14T15:00:00Z",
      "finalized_at": "2025-01-14T15:05:00Z",
      "source_map_count": 5
    }
  ],
  "total": 2
}

Get Release

Get details for a specific release.

GET /api/v1/projects/{project_id}/releases/{version}

Path Parameters

project_id

integer

required

Project ID

version

string

required

Release version

Response

{
  "id": 42,
  "project_id": 123,
  "version": "v1.2.3",
  "url_prefix": "~/",
  "created_at": "2025-01-15T10:30:00Z",
  "finalized_at": "2025-01-15T10:35:00Z",
  "source_map_count": 5
}

List Source Maps for Release

Get all source maps for a specific release.

GET /api/v1/projects/{project_id}/releases/{version}/sourcemaps?limit=100&offset=0

Path Parameters

project_id

integer

required

Project ID

version

string

required

Release version

Query Parameters

limit

integer

default:100

Max source maps to return

offset

integer

default:0

Pagination offset

Response

{
  "source_maps": [
    {
      "id": 101,
      "release_id": 42,
      "url": "~/static/js/main.abc123.js",
      "content_hash": "sha256:abc...",
      "file_size": 524288,
      "created_at": "2025-01-15T10:32:00Z"
    },
    {
      "id": 102,
      "release_id": 42,
      "url": "~/static/js/vendors.def456.js",
      "content_hash": "sha256:def...",
      "file_size": 1048576,
      "created_at": "2025-01-15T10:33:00Z"
    }
  ],
  "total": 2
}

Delete Release

Delete a release and all its source maps.

DELETE /api/v1/projects/{project_id}/releases/{version}

Path Parameters

project_id

integer

required

Project ID

version

string

required

Release version to delete

Response

Success (204 No Content) No response body.

Deleting a release is permanent. Errors with this release version will no longer have resolved stack traces.

The Upload Workflow

Source map uploads follow a recommended three-step workflow:

Create Release

POST /api/v1/releases
# Body: version=v1.2.3

Upload Source Maps

Upload all source map files for this release:

POST /api/v1/sourcemaps
# Body: release=v1.2.3, url=..., sourcemap=...
# Repeat for each .js file

Finalize Release

Mark the release as complete:

POST /api/v1/releases/v1.2.3/finalize

Build plugins (Next.js, Webpack, Vite) handle this workflow automatically during your build process.

URL Matching

When an error occurs, Proliferate matches stack trace URLs to source maps using:

Release version: Error’s release field must match a release
URL prefix: Stack trace URL must start with the release’s url_prefix
Exact URL match: The remaining path must match a source map’s url

Example

Release:

version: v1.2.3
url_prefix: ~/

Source Map:

release: v1.2.3
url: ~/static/js/main.abc123.js

Stack Trace URL:

https://example.com/static/js/main.abc123.js:42:15

Match Process:

Strip protocol and domain: ~/static/js/main.abc123.js
Match prefix: ~/ ✓
Match URL: ~/static/js/main.abc123.js ✓
Use this source map to resolve line 42, column 15

URL Prefix Patterns

Root-Relative (`~/`)

For URLs like https://example.com/static/js/main.js:

url_prefix: "~/"
url: "~/static/js/main.js"

This is the most common pattern for web apps.

Absolute URL

For CDN-hosted assets:

url_prefix: "https://cdn.example.com/"
url: "https://cdn.example.com/v1.2.3/app.js"

No Prefix (`""`)

For relative URLs:

url_prefix: ""
url: "app.js"

How Stack Trace Resolution Works

Error Captured

SDK captures error with minified stack trace and release field

Match Release

Backend finds release matching the error’s version

Match Source Maps

For each stack frame, find the source map matching the URL

Resolve Position

Use the source map to convert minified position (line:column) to original source

Return Resolved Stack

Display original file names, line numbers, and function names in the dashboard

Example Resolution

Minified Stack Frame:

at r (https://example.com/static/js/main.abc123.js:1:2345)

Resolved Stack Frame:

at processData (src/utils/data.ts:42:15)

Build Plugin Integration

Build plugins automate source map uploads during your build:

Next.js

next.config.js

const { withProliferate } = require('@proliferate/nextjs');

module.exports = withProliferate({
  // Your Next.js config
}, {
  apiKey: process.env.PROLIFERATE_API_KEY,
  autoUploadSourcemaps: true,
  release: process.env.VERCEL_GIT_COMMIT_SHA,
});

Webpack

webpack.config.js

const ProliferatePlugin = require('@proliferate/webpack-plugin');

module.exports = {
  plugins: [
    new ProliferatePlugin({
      apiKey: process.env.PROLIFERATE_API_KEY,
      release: process.env.GIT_SHA,
      include: './dist',
    }),
  ],
};

Vite

vite.config.js

import { proliferate } from '@proliferate/vite-plugin';

export default defineConfig({
  plugins: [
    proliferate({
      apiKey: process.env.PROLIFERATE_API_KEY,
      release: process.env.GIT_SHA,
    }),
  ],
});

Best Practices

Use Git Commit SHA as Version

version=$(git rev-parse HEAD)

This ensures each deployment has a unique version tied to exact source code.

Upload in CI/CD

Automate source map uploads in your deployment pipeline:

.github/workflows/deploy.yml

- name: Build and upload source maps
  env:
    PROLIFERATE_API_KEY: ${{ secrets.PROLIFERATE_API_KEY }}
    GIT_SHA: ${{ github.sha }}
  run: |
    npm run build
    # Source maps uploaded by build plugin

Don’t Deploy Source Maps

Keep .map files out of production bundles:

webpack.config.js

{
  devtool: 'hidden-source-map', // Generates maps but doesn't link them
}

This keeps your source code private while still allowing Proliferate to resolve stack traces.

Clean Up Old Releases

Delete releases older than your retention policy:

# Delete releases older than 90 days
curl -X DELETE https://api.proliferate.com/api/v1/projects/123/releases/old-version \
  -H "Authorization: Bearer $API_KEY"

Verify Uploads

Check that source maps were uploaded successfully:

curl https://api.proliferate.com/api/v1/projects/123/releases/v1.2.3/sourcemaps \
  -H "Authorization: Bearer $SESSION_TOKEN"

Testing

Test source map upload and resolution:

Build with Source Maps

npm run build
# Generates dist/main.js and dist/main.js.map

Upload Source Map

curl -X POST https://api.proliferate.com/api/v1/sourcemaps \
  -H "Authorization: Bearer $API_KEY" \
  -F "release=test-$(date +%s)" \
  -F "url=~/main.js" \
  -F "sourcemap=@dist/main.js.map"

Trigger Test Error

Deploy your app with the same release version and trigger an error

Verify Resolution

Check the error in the dashboard - stack trace should show original source

Troubleshooting

Source Maps Not Resolving

Check:

Error’s release field matches a release version
Source maps were uploaded for that release
Stack trace URLs match source map URLs
Source maps contain valid mappings

Debug:

# Check release exists
curl /api/v1/projects/{project_id}/releases/{version}

# Check source maps uploaded
curl /api/v1/projects/{project_id}/releases/{version}/sourcemaps

# Verify URL patterns match
# Error URL: https://example.com/static/js/main.js
# Source map URL should be: ~/static/js/main.js (with url_prefix: ~/)

Upload Fails with 401

Check that you’re using Bearer authentication in the header:

-H "Authorization: Bearer pk_your_api_key"

Not in the request body.

Missing Source Maps

If you’re using a build plugin, ensure:

API key is set in environment variables
Plugin is configured correctly in build config
Build process completes successfully (check logs)

API Reference

​Overview

​Authentication

​Upload Source Map

​Endpoint

​Request Parameters

​Response

​Create Release

​Endpoint

​Request Parameters

​Response

​Finalize Release

​Endpoint

​Path Parameters

​Response

​List Releases

​Path Parameters

​Query Parameters

​Response

​Get Release

​Path Parameters

​Response

​List Source Maps for Release

​Path Parameters

​Query Parameters

​Response

​Delete Release

​Path Parameters

​Response

​The Upload Workflow

​URL Matching

​Example

​URL Prefix Patterns

​Root-Relative (~/)

​Absolute URL

​No Prefix ("")

​How Stack Trace Resolution Works

​Example Resolution

​Build Plugin Integration

​Next.js

​Webpack

​Vite

​Best Practices

​Use Git Commit SHA as Version

​Upload in CI/CD

​Don’t Deploy Source Maps

​Clean Up Old Releases

​Verify Uploads

​Testing

​Troubleshooting

​Source Maps Not Resolving

​Upload Fails with 401

​Missing Source Maps

Overview

Authentication

Upload Source Map

Endpoint

Request Parameters

Response

Create Release

Endpoint

Request Parameters

Response

Finalize Release

Endpoint

Path Parameters

Response

List Releases

Path Parameters

Query Parameters

Response

Get Release

Path Parameters

Response

List Source Maps for Release

Path Parameters

Query Parameters

Response

Delete Release

Path Parameters

Response

The Upload Workflow

URL Matching

Example

URL Prefix Patterns

Root-Relative (`~/`)

Absolute URL

No Prefix (`""`)

How Stack Trace Resolution Works

Example Resolution

Build Plugin Integration

Next.js

Webpack

Vite

Best Practices

Use Git Commit SHA as Version

Upload in CI/CD

Don’t Deploy Source Maps

Clean Up Old Releases

Verify Uploads

Testing

Troubleshooting

Source Maps Not Resolving

Upload Fails with 401

Missing Source Maps