SDK-to-API batch ingest wire format specification. Propagation headers, event fields, and operation kinds.

Wire Format Reference

The Incidentary wire format defines how SDKs send captured events to the ingest server. This reference describes each field from the operator's perspective — what it is for, not how it is processed internally.

The format is at version 1 and is frozen. See the versioning section below for what this means.

Propagation Headers

These headers must be forwarded on every outbound HTTP call between instrumented services. Without them, the receiving service's events will not be connected to the calling service in the causal graph.

Header	Type	Required	Purpose
`x-incidentary-trace-id`	UUID v4 string	Yes	Groups all events in a distributed trace. Every service in a single request chain shares this value.
`x-incidentary-parent-ce`	UUID v4 string	No	Names the specific event in the calling service that triggered this call. Required for causal linkage. If absent, the receiving service's events appear as a separate root in the graph, not connected to the caller.

The SDKs inject these headers automatically when you use the instrumented fetch/HTTP clients. If you use a custom HTTP client, inject them manually from the current request context.

Batch Ingest Payload

All events are sent as a batch to:

POST /api/v1/ingest/batch
Content-Type: application/json
Authorization: Bearer <api_key>
X-Incidentary-SDK-Version: <semver>

Batch envelope fields

Field	Type	Purpose
`schema_version`	string	Always `"1"` in the current format
`workspace_id`	string	Your workspace identifier
`service_id`	string	The service name for all events in this batch
`environment`	string	Environment label (`production`, `staging`, etc.)
`flushed_at`	int64	Unix nanosecond timestamp when this batch was assembled
`capture_mode`	string	`"SKELETON"` (normal) or `"FULL"` (elevated capture mode)
`events`	array	The events (see event fields below)

Event fields

Field	Type	Purpose
`ce_id`	UUID	Unique identifier for this event. Used to deduplicate on retry.
`trace_id`	UUID	Which trace this event belongs to. All events in a distributed request chain share this value.
`parent_ce_id`	UUID or null	Which event caused this one. Null for trace roots (the first event in a chain).
`service_id`	string	Which service produced this event.
`wall_ts_ns`	int64	When the event occurred, in Unix nanoseconds.
`kind`	string	The operation type. See operation kinds below.
`event_type`	string	Refined operation label (optional; derived from `kind` if absent).
`status`	int32	HTTP status code or equivalent. `200` for success, `5xx` for server errors.
`duration_ns`	int64	How long the operation took, in nanoseconds.
`event_attrs`	object or null	Optional metadata specific to the operation type.

Operation kinds

`kind`	Meaning
`HTTP_IN`	Inbound HTTP request received by this service
`HTTP_OUT`	Outbound HTTP request sent by this service
`QUEUE_PUBLISH`	Message published to a queue or topic
`QUEUE_CONSUME`	Message consumed from a queue or topic
`JOB_START`	Background job or worker started
`JOB_END`	Background job or worker completed
`WEBHOOK_IN`	Webhook received from an external system
`WEBHOOK_OUT`	Webhook sent to an external system
`INTERNAL_TASK`	Internal operation that doesn't fit other categories

Refined event types

The event_type field provides a more specific label within an operation kind. If absent, it is derived from kind.

`event_type`	`kind`	Meaning
`http_in`	`HTTP_IN`	Standard inbound HTTP request
`http_out`	`HTTP_OUT`	Standard outbound HTTP request
`grpc_in`	`HTTP_IN`	Inbound gRPC call (gRPC runs over HTTP/2)
`grpc_out`	`HTTP_OUT`	Outbound gRPC call
`queue_publish`	`QUEUE_PUBLISH`	Message published to a queue
`queue_consume`	`QUEUE_CONSUME`	Message consumed from a queue
`db_query`	`INTERNAL_TASK`	Database query (SQL text, no parameters)
`job_start`	`JOB_START`	Background job started
`job_end`	`JOB_END`	Background job completed
`webhook_in`	`WEBHOOK_IN`	Inbound webhook
`webhook_out`	`WEBHOOK_OUT`	Outbound webhook

Capture Modes

Mode	When	What is captured
`SKELETON`	Normal operation	Timing, status, and causal structure only
`FULL`	Elevated capture (pre-arm or active incident)	Skeleton plus optional detail metadata: headers, retry information, route templates, request/response size estimates

The SDK manages capture mode automatically based on observed anomaly signals. You do not configure this manually unless you need to tune the thresholds.

Versioning

The format is frozen at version 1. This means:

No field removals: if a field exists in v1, it will always be present in the schema
No semantic changes: the meaning of existing fields will not change
No new required fields: new optional fields may be added with safe defaults

SDKs below the minimum supported version receive HTTP 426 Upgrade Required:

{
  "error": {
    "code": "SDK_VERSION_TOO_OLD",
    "message": "SDK version X.Y.Z is below minimum A.B.C.",
    "minimum_version": "A.B.C",
    "current_version": "X.Y.Z"
  }
}

Keep your SDK up to date to avoid this.

Example payload

{
  "schema_version": "1",
  "workspace_id": "ws_01ABCDEF",
  "service_id": "checkout-api",
  "environment": "production",
  "flushed_at": 1733103000000000000,
  "capture_mode": "SKELETON",
  "events": [
    {
      "ce_id": "550e8400-e29b-41d4-a716-446655440000",
      "trace_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "parent_ce_id": null,
      "service_id": "checkout-api",
      "wall_ts_ns": 1733103000000000001,
      "kind": "HTTP_IN",
      "event_type": "http_in",
      "status": 200,
      "duration_ns": 45000000,
      "event_attrs": {
        "route_template": "/orders/:id/checkout"
      }
    },
    {
      "ce_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "trace_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "parent_ce_id": "550e8400-e29b-41d4-a716-446655440000",
      "service_id": "checkout-api",
      "wall_ts_ns": 1733103000010000000,
      "kind": "HTTP_OUT",
      "event_type": "http_out",
      "status": 503,
      "duration_ns": 35000000,
      "event_attrs": null
    }
  ]
}

Wire Format

On this page