Error Reporting API Endpoints

These API endpoints allow you to interact with the Error Reporting (Backtrace) platform.

Getting Started

What You'll Need

• A Backtrace account (log in or sign up for a free trial license).
• Your subdomain name (used to connect to your Backtrace instance). For example, https://example-subdomain.sp.backtrace.io.
• A Backtrace project and an API token generated with the corresponding scope(s).

Accessing the APIs

All Backtrace submission APIs are accessible via HTTPS at the following base URL, depending on your instance type:

Hosted Instance

Base URL for hosted environments: https://submit.backtrace.io/.

To submit data, the URL format is: <BaseURL>/<subdomain>/<token>/<format>.

subdomain	If your instance address is https://example.sp.backtrace.io, your subdomain will be example.
token	The API token generated with the specific scope(s).
format	The format of the archive being sent.

On-premise Instance

Base URL for all submission APIs when running an On-Premise instance: https://<onpremHost>/api/post.

To submit data, the URL format is: https://<onpremHost>/api/post?<format>&token=<apiToken>.

onpremHost	The hostname to your on-premise instance of Backtrace.
format	The format of the archive being sent.
token	The API token generated with the specific scope(s).

API Tokens

API tokens are essential for submitting data to your Backtrace project. They are generated within your project settings and must be configured with the necessary scope(s) (permissions) for the type of data you intend to upload (submitting crash reports or symbols).

Scope	Description
error:post	Error and dump submission
symbol:post	Symbol and source map submission
object:get	Fetching objects
query:post	Enables queries to be issued
sync:post	Enables synchronous post. Required for submission buckets

Supported Format Types

The {format} parameter in the request URL specifies the format of the data being submitted. Different formats are used for different types of submissions, such as JSON for generic error reports or minidump for native crash files. Below are the primary format types supported by Backtrace:

Format	Description
btt	Files generated by Backtrace's ptrace tool.
json	Generic JSON payload for structured error reports or exceptions.
minidump	Native crash files (dumps) typically generated by libraries like Breakpad or Crashpad.
plcrash	Crash files generated by the PLCrashReporter.
sourcemap	JavaScript Source Maps used to un-minify/un-uglify production code for debugging.
symbols	Symbol and executable files for symbolication of native crashes.

---

NOTE

This APIs below are intended for hosted Backtrace instances. If you are an on-premise user, please use the appropriate endpoint format: https://{onpremHost}/api/post?{format}&token={apiToken}.

Errors

Submit Error

POST https://submit.backtrace.io/{subdomain}/{apiToken}/{format}

Submits Error Object to Backtrace. For large files, include the header flag -H "Expect:" to override some default curl behavior, which can cause issues when uploading to Backtrace.

Parameters

subdomain	| QUERY | REQUIRED | STRING | Your Backtrace universe name.
apiToken	| QUERY | REQUIRED | STRING | API token with the necessary scope(s) generated in your Backtrace project settings.
format	| QUERY | REQUIRED | STRING | The format of the error object being submitted.
upload_file	| BODY | REQUIRED | STRING | The error data file (minidump or core dump) containing the crash information.
attachment.{extension}	| BODY | OPTIONAL | STRING | Attach additional files (logs, etc.) with the error data file. The field name is dynamic, consisting of a required prefix and a file extension: Field Name: Must start with attachment. followed by the file extension ( attachment.log, attachment.json). Supported Extensions: JSON, log, and txt. Note: Files with the txt & log extension require the type to be set to text/plain.
{attribute}	| BODY | OPTIONAL | STRING | User-defined key-value metadata to attach to the crash report, where {attribute} is the key and the value is the data. Example: -F "version=1.0"

Sample Requests

Sample Request

curl -v \
-F "upload_file=@example_error.json" \
-F "version=1.0.1" \
-F "platform=Windows" \
-H "Expect:" \
"https://submit.backtrace.io/saucebot/685f2e33a75f0f4623584389...6f34a46a84b3ec64e482b/json"

Sample Request w/ Attachments

curl -v \
-F "upload_file=@example_error.json" \
-F "attachment_test.json=@test.json; type=application/json" \
-F "version=1.0.1" \
-F "platform=Windows" \
-H "Expect: " \
"https://submit.backtrace.io/saucebot/685f2e33a75f0f4623584389...6f34a46a84b3ec64e482b/json"

Responses

Status Code	Description
200	Success
400	Malformed Request
403	Invalid Token
503	Invalid Subdomain or Missing Format

Sample Response

A successful response contains an _rxid, which is the unique identifier for the received error object.

Sample Response

{"response":"ok","_rxid":"01000000-7e23-7a1e-0000-000000000000"}

---

Symbols

Submit Symbol

POST https://submit.backtrace.io/{subdomain}/{apiToken}/symbols

Submits debug symbol files to Backtrace. The symbol archive must contain both the executable and symbol files for proper symbolication. Any archive format supported by libarchive 3.2.3 is supported, such as .tar, .tar.gz, .zip. Archives should be pre-compressed and should not exceed 10GB in size, where possible.

Parameters

subdomain	| QUERY | REQUIRED | STRING | Your Backtrace universe name.
apiToken	| QUERY | REQUIRED | STRING | API token with the necessary scope(s) generated in your Backtrace project settings.
upload_file	| BODY | REQUIRED | STRING | The archive file (compressed ZIP) containing the symbol and binary files for symbolication.
{tag}	| BODY | OPTIONAL | STRING | User-defined key-value tags to attach to the symbols, where {tag} is the tag key and the value is the tag data. Example: -F "tag=test"

Sample Request

Sample Request

curl -v \
-F "upload_file=@symbols.zip" \
-F "tag=test" \
-H "Expect:" \
"https://submit.backtrace.io/saucebot/685f2e33a75f0f4623584389...6f34a46a84b3ec64e482b/symbols"

Responses

Status Code	Description
200	Success
400	Malformed Request
403	Invalid Token
503	Invalid Subdomain or Missing Format

Sample Response

A successful response contains an _rxid, which is the unique identifier for the received object.

Sample Response

{"response":"ok","_rxid":"01000000-7e23-7a1e-0000-000000000000"}

---

Source Map

Submit Source Map

POST https://submit.backtrace.io/{subdomain}/{apiToken}/sourcemap

Upload source maps to symbolicate ES6/JavaScript errors.

Parameters

subdomain	| QUERY | REQUIRED | STRING | Your Backtrace universe name.
apiToken	| QUERY | REQUIRED | STRING | API token with the necessary scope(s) generated in your Backtrace project settings.
upload_file	| BODY | REQUIRED | STRING | The source map file or compressed archive containing debugging information.
{tag}	| BODY | OPTIONAL | STRING | User-defined key-value tags to attach to the source maps, where {tag} is the tag key and the value is the tag data. Example: -F "tag=test"

Sample Request

Sample Request

curl -v \
-F "upload_file=@test.js.map" \
-F "tag=test" \
-H "Expect:" \
"https://submit.backtrace.io/saucebot/685f2e33a75f0f4623584389...6f34a46a84b3ec64e482b/sourcemap"

Responses

Status Code	Description
200	Success
400	Malformed Request
403	Invalid Token
503	Invalid Subdomain or Missing Format

Sample Response

A successful response contains an _rxid, which is the unique identifier for the received object.

Sample Response

{"response":"ok","_rxid":"01000000-7e23-7a1e-0000-000000000000"}