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
On-premise 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.

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 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"}

Submit Raw Error Data

POST http://api.backtrace.io/post

Submit raw error data to Backtrace.

Parameters

`token`	\| QUERY \| REQUIRED \| STRING \| Your API token.
`format`	\| QUERY \| REQUIRED \| STRING \| The format of the crash you are submitting. Default value is `json`.
`body`	\| BODY \| REQUIRED \| STRING \| The JSON body of the crash dump. The required fields for `body` are: `uuid` `timestamp` `lang` `langVersion` `agent` `agentVersion` `threads` `mainThread`
`uuid`	\| BODY \| REQUIRED \| STRING \| 16 bytes of randomness in human readable UUID format. The server will reject the request if UUID is already found.
`timestamp`	\| BODY \| REQUIRED \| INTEGER \| The UTC timestamp in seconds.
`lang`	\| BODY \| REQUIRED \| STRING \| The name of the programming language/environment this error originates from.
`langVersion`	\| BODY \| REQUIRED \| STRING \| The version of the programming language/environment this error originates from.
`agent`	\| BODY \| REQUIRED \| STRING \| The name of the client that is sending this error report.
`agentVersion`	\| BODY \| REQUIRED \| STRING \| The version of the client that is sending this error report.
`threads`	\| BODY \| REQUIRED \| OBJECT \| Contains a map of all threads running in the environment. It could be only one. The object is composed by the `main` object that is the key of the `threads` object and represents the unique ID of a thread. The object contains the following fields: `name` - A string that provides a small description of what the thread does. `fault` - A boolean value that denotes if a thread is a faulting thread. Rarely two faulted threads can be seen, if it happens, the first faulting thread listed gets the status of `mainThread` `stack` - An array composed by the following fields: `guessed_frame` - A boolean value that is `true` if the stack frame is created by hueristic method due to missing CFI, and `false` otherwise. `funcName` - A string value that identifies the function, method, or procedure name. If not provided then `address` must be provided. `address` - A string value that identifies the address of the stack frame. Required if `funcName` is not provided. `line` - A string value that identifies the line number in the source code of the stack frame. First line is 1. `column` - A string value that identifies the column number in the source code of the stack frame. First column is 1. `sourceCode` - A string value that identifies the ID of the source code file the stack frame is contained in. `library` - A string value that identifies the shared object, the library or the module name. `debug_identifier` - A string value that identifies the debug identifier for the library associated with this frame. `faulted` - A boolean value that indicates if this frame is known to to the faulting frame. `registers` - In this object the keys are the register names. Use any names that make sense for the architecture. These must correspond to the values in the `arch` definition. JSON does not support 64 bit integers, so you must set the correct type and then encode the 64 bit integers as a string.
`mainThread`	\| BODY \| REQUIRED \| STRING \| It represent the thread that either triggered the error or generated this object. The value of this field should be one of the keys in the `threads` object and cannot be `null`.
`symbolication`	\| BODY \| OPTIONAL \| STRING \| Specifies the symbolication that needs to be applied. Supported values are: `minidump`. `sourcemap`. `proguard`. This should not be specified for client-symbolicated objects.
`entryThread`	\| BODY \| OPTIONAL \| STRING \| Specifies which thread is the entry point or the starting thread. This must correspond to an entry in the `threads` field.
`arch`	\| BODY \| OPTIONAL \| OBJECT \| Specifies the CPU architecture information. It is required if you want to have registers in the stack frame. The object has two fields: `name` - On some systems the running program can be run with a different arch than the system itself. `attributes.uname.machine` has to do with the system arch; this field has to do with the running process arch. `registers` - It corresponds with registers in the stack frame. Specifies the names of the registers for this arch. The values are the types. Valid types are: `i32`, `u32`, `i64`, `u64`, `f32`, `string`. If you use `string`, you can format the value as you want.
`fingerprint`	\| BODY \| OPTIONAL \| STRING \| This is a base64 encoded unique ID that groups the report with the same fingerprint (32 bytes). If omitted, a fingerprint will be generated from the submitted stack trace.
`classifiers`	\| BODY \| OPTIONAL \| ARRAY of STRINGS \| List of strings which are report classifications.
`attributes`	\| BODY \| OPTIONAL \| OBJECT of KEY:VALUE Pairs \| This is a set of key-value pairs that belong to the error report. The exact fields are not defined by this specification. It is up to the JSON consumer how to display or otherwise represent key/value pairs in this object. The value of a key-value pair can be a string, integer, or boolean. These attributes are indexed and searchable. Some of the possible values: `application: foo` `cpu.iowait: 1234143` `system.memory.buffers: 1234` `uname.machine: x86_64` `vm.swap.size: 1234` `error.message: Unexpected token h`
`sourceCode`	\| BODY \| OPTIONAL \| OBJECT \| The object include the source code for better debugging experience. The object is composed by the `sourceCodeId` object that is the ID of the source code. The object is composed by the following fields: `text` - A string that provides the full source file or a subset of it. If provided, then also `startline` should be provided. If not provided, then `path` must be provided. `startLine` - An integer value that provides the line number that the provided text starts on. It is required if `text` is provided. First line is 1. `startColumn` - An integer value that provides the column number that the first byte in the `text` segment is. First column is 1. `startPos` - An integer value that provides the absolute byte index in the original file that the provided segment is part of. First byte is 0. `path` - A string value that provides the file system path to the original source code file. If not provided, then `text` must be provided. `tabWidth` - An integer value that informs source code display how many spaces a tab should represent.
`memory`	\| BODY \| OPTIONAL \| ARRAY \| Provides arbitrary slices of memory. The array is composed by the following keys: `start` - An integer offset that this slice of memory starts at. The 64 bit integers are represented as strings. `size` - The number of bytes of the slice. Optional if you include `data`. `data` - Base64 encoded bytes of the slice of memory. If provided, `size` can be inferred from it. `perms` - The object that sets of permissions of this slice of memory. It is composed by the boolean properties: `read` `write` `exec`
`annotations`	\| BODY \| OPTIONAL \| ARRAY or OBJECT or STRING \| A generic, non-indexed user-provided property. The names are free, the values can be of any type, and there is no limit to nesting.
`modules`	\| BODY \| OPTIONAL \| ARRAY \| A list of modules as loaded in memory, used to symbolicate stack traces. The array is composed by the following keys: `start` - An integer offset that the module starts at. 64 bit integers are represented as strings. `size` - The number of bytes occupied by the module. `code_file` - A string that indicates the path that the module is loaded from. `version` - The human-readable version string for the module. `debug_file` - The file containing debug information for the module. `debug_identifier` - The debug file identifier. `debug_file_exists` - A boolean value that indicates if symbolication was able to locate the debug file.

Sample Request
curl --request POST 'https://api.backtrace.io/post?token=<your_token>&format=<format>' \
-H 'Content-Type: application/json' \
-d '{
  "body": {
    "uuid": "123e4567-e89b-12d3-a456-426655440000",
    "timestamp": 1475530543,
    "lang": "nodejs",
    "langVersion": "v4.5.0",
    "agent": "backtrace-node",
    "agentVersion": "0.4.0",
    "threads": {
      "main": {
        "name": "my super cool thread",
        "fault": true,
        "stack": [
          {
            "guessed_frame": "false",
            "funcName": "main",
            "address": "16045690984833335023",
            "line": "10",
            "column": "19",
            "sourceCode": "o9BYbg2uO+1m",
            "library": "/home/example/nodebt/test.js",
            "callstack_state": "1",
            "registers": {
              "rax": "16045690984833335023",
              "rip": 1234,
              "FLAGS": "E:1 B:0 C:1"
            }
          }
        ]
      }
    },
    "mainThread": "main>"
  }
}'

Responses

`200`	Success.
`400`	Malformed request.
`403`	Invalid token.

Sample Response
{
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "timestamp": 1475530543,
  "lang": "nodejs",
  "langVersion": "v4.5.0",
  "agent": "backtrace-node",
  "agentVersion": "0.4.0",
  "threads": {
    "main": {
      "name": "my super cool thread",
      "fault": true,
      "stack": [
        {
          "guessed_frame": "false",
          "funcName": "main",
          "address": "16045690984833335023",
          "line": "10",
          "column": "19",
          "sourceCode": "o9BYbg2uO+1m",
          "library": "/home/example/nodebt/test.js",
          "callstack_state": "1",
          "registers": {
            "rax": "16045690984833335023",
            "rip": 1234,
            "FLAGS": "E:1 B:0 C:1"
          }
        }
      ]
    }
  },
  "mainThread": "main",
  "entryThread": "12341324",
  "arch": {
    "name": "x64",
    "registers": {
      "rax": "u64",
      "rip": "u32",
      "FLAGS": "string"
    }
  },
  "fingerprint": "kqJB7mgd22nvWGxYU2MvCpLRTiNWO1C8KFS434eTz1M=",
  "callstack": {
    "frames": ["one@foo.js:123", "two@bar.js", "three"]
  },
  "classifiers": ["SyntaxError"],
  "attributes": {
    "application": "foo",
    "cpu.boottime": 1234234234,
    "cpu.context": 1234,
    "cpu.idle": 1234234,
    "cpu.iowait": 1234143,
    "cpu.irq": 1234113,
    "cpu.kernel": "foo",
    "cpu.nice": "foo",
    "cpu.process.blocked": 1234,
    "cpu.process.count": 1234,
    "cpu.process.running": 1234,
    "cpu.softirq": "foo",
    "cpu.user": 1234,
    "descriptor.count": 1234,
    "fault.address": "foo",
    "fingerprint": "foo",
    "hostname": "foo",
    "process.age": 1234,
    "sched.cs.involuntary": 1234,
    "sched.cs.voluntary": 1234,
    "system.memory.active": 1234,
    "system.memory.buffers": 1234,
    "system.memory.cached": 1234,
    "system.memory.dirty": 1234,
    "system.memory.free": 1234,
    "system.memory.inactive": 1234,
    "system.memory.slab": 1234,
    "system.memory.swap.cached": 1234,
    "system.memory.swap.free": 1234,
    "system.memory.swap.total": 1234,
    "system.memory.total": 1234,
    "system.memory.vmalloc.chunk": 1234,
    "system.memory.vmalloc.total": 1234,
    "system.memory.vmalloc.used": 1234,
    "system.memory.writeback": 1234,
    "uname.machine": "x86_64",
    "uname.release": "4.4.0-38-generic",
    "uname.sysname": "Linux",
    "uname.version": "#57-Ubuntu SMP Tue Sep 6 15:42:33 UTC 2016",
    "vm.data.size": 1234,
    "vm.locked.size": 1234,
    "vm.pte.size": 1234,
    "vm.rss.peak": 1234,
    "vm.rss.size": 1234,
    "vm.shared.size": 1234,
    "vm.stack.size": 1234,
    "vm.swap.size": 1234,
    "vm.vma.peak": 1234,
    "vm.vma.size": 1234,
    "mem.rss": 1234,
    "mem.heap.total": 1234,
    "mem.heap.used": 1234,
    "error.message": "Unexpected token h"
  },
  "sourceCode": {
    "o9BYbg2uO+1m": {
      "text":
        "var bt = require('backtrace.io');\nbt.initialize({\n  debugBacktrace: true,\n  timeout: 9999999,\n});\n\nmain();\n\nfunction main() {\n  var json = JSON.parse(\"example\");\n}\n",
      "startLine": 1,
      "startColumn": 1,
      "startPos": 0,
      "path": "/home/andy/tmp/nodebt/test.js",
      "tabWidth": 8
    }
  },
  "memory": [
    {
      "start": "16045690984833335023",
      "size": 1024,
      "data": "R56cuNuwpqEJe8n3i4Ojlxt59fpPMU74RygKv5byWJzoHYwCr",
      "perms": {
        "read": true,
        "write": true,
        "exec": false
      }
    }
  ],
  "annotations": {
    "Environment Variables": {
      "ENV_VAR_EXAMPLE": "example value"
    },
    "Some Property Name": true,
    "Dependencies": {
      "dependencyName": {
        "requestedVersion": "~1.2.0",
        "installedVersion": "1.2.0",
        "dependencies": {}
      }
    }
  }
}

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"}

Getting Started​

What You'll Need​

Accessing the APIs​

API Tokens​

Supported Format Types​

Errors​

Submit Error​

Parameters​

Sample Requests​

Responses​

Sample Response​

Submit Raw Error Data​

Parameters​

Responses​

Symbols​

Submit Symbol​

Parameters​

Sample Request​

Responses​

Sample Response​

Source Map​

Submit Source Map​

Parameters​

Sample Request​

Responses​

Sample Response​

Getting Started

What You'll Need

Accessing the APIs

API Tokens

Supported Format Types

Errors

Submit Error

Parameters

Sample Requests

Responses

Sample Response

Submit Raw Error Data

Parameters

Responses

Symbols

Submit Symbol

Parameters

Sample Request

Responses

Sample Response

Source Map

Submit Source Map

Parameters

Sample Request

Responses

Sample Response