Event Ingestion

The ingestion endpoint accepts events from SDKs, CLIs, and direct API calls. It validates, persists raw events to object storage, and enqueues processing — no heavy synchronous work in the request path.

Endpoint

POST /v1/events

Authentication: Project token via Authorization header.

For static-only browser sites that send directly to the cloud API, project tokens can include allowed_origins. When configured, requests must include an Origin header matching that allowlist. Requests from server SDKs or backend relays usually do not include Origin, so those paths should use project tokens without allowed_origins. This is abuse reduction for normal browser traffic, not a secret boundary.

curl -X POST https://api.debugbundle.com/v1/events \
  -H "Authorization: Bearer dbundle_proj_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_type": "backend_exception",
        "timestamp": "2026-03-24T10:30:00.000Z",
        "service": { "name": "api-server", "environment": "production" },
        "payload": {
          "error_class": "TypeError",
          "message": "Cannot read properties of undefined",
          "stacktrace": "TypeError: Cannot read properties of undefined\n    at handler (/app/src/routes.js:42:10)"
        }
      }
    ]
  }'

Request Format

{
  "events": [
    {
      "event_type": "string",
      "timestamp": "ISO8601",
      "service": {
        "name": "string",
        "environment": "string"
      },
      "sdk": {
        "name": "string",
        "version": "string"
      },
      "context": {},
      "payload": {}
    }
  ]
}

Event Types

Batch Size

There is no hard limit on events per batch, but SDKs typically send 25–50 events per request. Extremely large batches may hit request body size limits (default: 1 MB).

Response Format

Success (202 Accepted):

{
  "accepted": 5,
  "rejected": 1,
  "errors": [
    {
      "index": 3,
      "reason": "Invalid event_type: unknown_type"
    }
  ],
  "probe_directives": {
    "active_probes": [
      {
        "activation_id": "act_01HXYZ...",
        "label_pattern": "db_*",
        "service": "api-server",
        "environment": "production",
        "expires_at": "2026-03-24T11:30:00.000Z",
        "trigger_expires_at": "2026-03-25T10:30:00.000Z"
      }
    ]
  }
}

Error Responses

Rate Limiting

Ingestion rate limits are tier-based:

When exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds). SDKs automatically respect this header and retry.

Quota Enforcement

Each plan includes a monthly event allowance. When the quota is exceeded:

• Events are still accepted (not rejected)
• A quota warning is logged
• Over-quota events count toward the next billing period
• The dashboard and API surface quota status

Check your quota via Billing API or the web dashboard.

Capture Policy and Rules

Projects can configure a capture policy that filters events at ingestion time:

Events filtered by capture policy are counted as rejected in the response with reason "capture_policy_rejected".

Active project capture rules are also evaluated during ingestion. Matching drop rules return "capture_rule_dropped", matching sampled-out sample rules return "capture_rule_sampled_out", and matching demote rules are accepted as context signals so they cannot open or reopen incidents.

Configure capture policy and capture rules via the API, CLI, MCP, or dashboard.

Processing Pipeline

After ingestion, events flow through the asynchronous processing pipeline:

The ingestion endpoint returns immediately after persisting and enqueuing. Bundle generation, incident grouping, and webhook delivery happen asynchronously in the worker.

Next Steps

• Authentication — Token types and auth model
• Incidents API — Retrieve incidents and bundles
• Probes API — Remote probe activation
• SDKs Overview — SDK-based event capture