POST /ingest/:projectId/envelope — Event Ingest

The ingest endpoint is how the Argus SDKs send error events to the platform. You normally don’t call it directly — the SDK handles serialization, batching, and auth for you. However, this reference is useful when you’re building a custom integration, writing a platform-specific SDK, or debugging exactly what your client is transmitting.

Endpoint

POST /api/v1/ingest/:projectId/envelope

Authentication

This endpoint uses DSN key authentication, not a session cookie. Pass your project’s public key in the X-Sentry-Auth request header using the sentry_key= format. You can find your DSN public key in Project Settings → Client Keys.

X-Sentry-Auth: sentry_key=YOUR_PUBLIC_KEY

Alternatively, you can pass the key as a query parameter:

POST /api/v1/ingest/:projectId/envelope?sentry_key=YOUR_PUBLIC_KEY

Session-based auth tokens are not accepted here. Use the DSN key.

Path Parameters

projectId

string

required

The project ID extracted from your DSN. The DSN format is https://<publicKey>@<host>/<projectId> — the path segment after the host is your projectId.

Request Body

Send a JSON object conforming to the envelope schema below. The exception field is the only required top-level key.

Top-level fields

exception

object

required

The error payload. Contains the exception class, message, and full stack trace. See the Exception object section for the full shape.

level

string

Severity level of the event. Accepted values: fatal, error, warning, info, debug. Defaults to error.

timestamp

number

When the error occurred, expressed as milliseconds since the Unix epoch (i.e. the value of Date.now()). Must be ≥ 1577836800000 (2020-01-01). Omit this field to let the server use the receipt time.

environment

string

The deployment environment, e.g. production, staging, or development.

release

string

The release identifier for your application, e.g. a semantic version 1.4.2 or a Git SHA.

user

object

Information about the affected user. Both fields are optional but at least one improves issue triage.

Field	Type	Description
`id`	string	Your internal user ID
`email`	string	User’s email address

breadcrumbs

array

An ordered list of events that led up to the error — navigation changes, log lines, network requests, etc. Maximum 100 breadcrumbs per envelope.Each breadcrumb has the following fields:

Field	Type	Required	Description
`type`	string	✅	Category label, e.g. `navigation`, `http`
`message`	string	—	Human-readable description
`timestamp`	number	—	Milliseconds since epoch (Date.now())
`data`	object	—	Arbitrary key/value metadata

Field	Type	Description
`url`	string	Full request URL
`method`	string	HTTP method
`headers`	`Record<string, string>`	Request headers map

Field	Type	Description
`browser.name`	string	Browser name, e.g. `Chrome`
`browser.version`	string	Browser version, e.g. `125.0`
`os.name`	string	Operating system, e.g. `macOS`
`os.version`	string	OS version, e.g. `14.4`

Exception object

The exception object is required and must include a non-empty stack trace.

exception.type

string

required

The error class name, e.g. TypeError, RangeError, or your custom exception class.

exception.value

string

required

The error message string, e.g. Cannot read properties of undefined (reading 'id').

exception.stacktrace.frames

array

required

An array of stack frames in innermost-first order (the frame at index 0 is the throw site). Must contain at least one frame.

Field	Type	Required	Description
`filename`	string	✅	Source file path or URL
`lineno`	integer	✅	Line number (must be a positive integer)
`function`	string	—	Function or method name
`colno`	integer	—	Column number

Example Request

curl -X POST https://your-domain.com/api/v1/ingest/PROJECT_ID/envelope \
  -H 'Content-Type: application/json' \
  -H 'X-Sentry-Auth: sentry_key=YOUR_PUBLIC_KEY' \
  -d '{
    "level": "error",
    "timestamp": 1720000000000,
    "environment": "production",
    "release": "1.4.2",
    "exception": {
      "type": "TypeError",
      "value": "Cannot read property of undefined",
      "stacktrace": {
        "frames": [
          {
            "filename": "app.js",
            "function": "handleClick",
            "lineno": 42,
            "colno": 7
          },
          {
            "filename": "app.js",
            "function": "dispatchEvent",
            "lineno": 18
          }
        ]
      }
    },
    "user": {
      "id": "usr_01HX",
      "email": "alice@example.com"
    },
    "tags": {
      "region": "us-east-1"
    },
    "breadcrumbs": [
      {
        "type": "navigation",
        "message": "Navigated to /dashboard",
        "timestamp": 1719999990000
      }
    ],
    "contexts": {
      "browser": { "name": "Chrome", "version": "125.0" },
      "os": { "name": "macOS", "version": "14.4" }
    }
  }'

Responses

Status	Meaning
`200`	Event accepted and recorded.
`400`	Invalid envelope — validation failed. The response body contains field-level errors.
`401`	Missing or invalid DSN public key in `X-Sentry-Auth`.
`429`	Rate limit or monthly event quota exceeded.

200 — Accepted

{
  "statusCode": 200,
  "status": "success",
  "message": "Event received successfully"
}

400 — Validation Error

{
  "statusCode": 400,
  "status": "failed",
  "message": "Validation error",
  "error": [
    {
      "path": ["exception", "stacktrace", "frames"],
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

Timestamp must be in milliseconds, not seconds. Always use Date.now() (e.g. 1720000000000), never Math.floor(Date.now() / 1000). The validator enforces a lower bound of 1577836800000 (2020-01-01); a Unix seconds value (~1.7e9) falls well below this bound and is rejected with HTTP 400.

Transaction Envelopes (performance)

The same endpoint also accepts performance envelopes, discriminated by "type": "transaction". They pass the same DSN auth, rate limit, and quota chain as error envelopes.

type

'transaction'

required

Marks the envelope as a performance transaction instead of an error event.

name

string

required

Operation label, e.g. page.load /dashboard (1–200 chars).

duration

number

required

Total duration in milliseconds (≥ 0).

timestamp

number

required

Milliseconds since epoch — same rule as error envelopes.

status

string

Outcome, e.g. ok (default).

vitals

object

Optional web vitals: { lcp?, cls?, fcp?, ttfb? } — LCP/FCP/TTFB in ms, CLS unitless.

Example:

{
  "type": "transaction",
  "name": "page.load /dashboard",
  "duration": 1240,
  "timestamp": 1720000000000,
  "status": "ok",
  "vitals": { "lcp": 1800, "cls": 0.05, "fcp": 900, "ttfb": 250 }
}

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Top-level fields

​Exception object

​Example Request

​Responses

​200 — Accepted

​400 — Validation Error

​Transaction Envelopes (performance)

Endpoint

Authentication

Path Parameters

Request Body

Top-level fields

Exception object

Example Request

Responses

200 — Accepted

400 — Validation Error

Transaction Envelopes (performance)