Upload a trace

The Swift SDK handles this request, including persistence and retries. For a custom integration, save a valid envelope as trace.json and set LEDGE_WRITE_KEY in your shell.

curl --fail-with-body -i https://api.ledgekit.com/v1/traces \
  -H "Authorization: Bearer $LEDGE_WRITE_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa' \
  --data-binary @trace.json

The idempotency key must match trace.id. The example UUID matches the envelope on the schema page. The envelope specifies schemaVersion: 1. Maximum body size is 4 MiB.

Receipts and retries

A new trace returns 201 with an empty body. Replaying an identical stored trace returns 200, also with an empty body. Reusing the trace identity for a conflicting payload returns 409 trace_conflict. Keep the original payload and ID for retry attempts.

Only finalized traces and spans are accepted. Invalid timing, invalid names or versions, duplicate span IDs, and fields outside the contract return 400 invalid_envelope. See errors and retries.

Loading API schema…