API Documentation

Base URL

All endpoints in this documentation are relative to the base URL below. Always use HTTPS in production to ensure data confidentiality in transit.

https://api.immutablelog.com

Authentication*

Every API request requires an access token sent in the `Authorization` header using the Bearer scheme. You can generate your token in the customer area, under API Keys. Production tokens are prefixed with `iml_live_`. Keep it secure — it authenticates all read and write operations for your tenant.

Authorization: Bearer iml_live_xxxxxxxxxxxxxxxx

Security tip: Never expose your token in client-side code (frontend) or public repositories. Use server-side environment variables.

Idempotency-Key*

The `Idempotency-Key` header is required for event ingestion — a request without it (or with an empty value) gets a `400`. Use a unique value per request. If the same key is resent (e.g., in a retry after a network timeout), the server recognizes the duplicate and responds `200 OK` with the same result (`duplicate: true`), without creating a second event in the ledger.

Idempotency-Key: seed-42-550e8400-e29b-41d4-a716-446655440000
Request-Id: 8d0b5f06-6d1f-4d3c-9b4f-9f5a2d7b3c1a

When to use: Recommended for automatic retries, async workers, and event-driven integrations where at-least-once delivery is guaranteed by the broker.

`meta.immutable_trail` is a trail identifier that groups related events within the same business flow — for example, the complete lifecycle of an order, an audit session, or a subscription flow. The field is optional: if not sent, the event is created normally without being associated with any trail.

{
  "payload": "{\"order_id\":\"ORD-2026-00441\",\"status\":\"paid\"}",
  "meta": {
    "type": "info",
    "event_name": "order.payment_confirmed",
    "immutable_trail": "order-2026-00441"
  }
}

curl "https://api.immutablelog.com/v1/events?trail=order-2026-00441&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Client timezone (optional)

To avoid “date confusion” (UTC vs local time), you can send the client local time via headers. The server keeps canonical UTC time for ordering/proof and persists these values only as untrusted metadata for dashboard display.

X-Client-Time: 2026-02-05T21:13:22-03:00
X-Client-TZ: America/Sao_Paulo
X-Client-Offset-Minutes: -180

`X-Client-Time` (ISO8601) is the most important. `X-Client-TZ` and `X-Client-Offset-Minutes` are optional and help the UI render correctly. `Request-Id` is recommended for traceability (logs/support).

curl -X POST https://api.immutablelog.com/v1/events \
  -H "X-Client-Time: 2026-02-05T21:00:00-03:00" \
  -H "X-Client-TZ: America/Sao_Paulo" \
  -H "X-Client-Offset-Minutes: -180" \
  -H "Request-Id: req-123" \
  -d '{"payload":"..."}'

Payload Structure

The body of each ingestion request contains two fields: `payload` and `meta`. The `payload` field is treated as an opaque string by the server — its content is not interpreted, only stored and hashed. This ensures the hash is computed over exactly what you sent, without any transformation.

{
  "payload": "{\"id\":\"d6b6c2e5-0c1a-4b92-9a62-2f2c4c2e9a2a\",\"kind\":\"info\",\"message\":\"http.GET.user-me\",\"context\":{\"user_id\":123,\"email\":\"user@example.com\"},\"timestamp\":\"2026-02-05T12:00:00Z\"}",
  "meta": {
    "type": "info",
    "event_name": "http.GET.user-me",
    "service": "api",
    "env": "prod",
    "trace_id": "2c3f4f1e-7d2d-4d10-9c47-0f8d7a1b2c3d"
  }
}

Limit: Size limit: ~16KB per event. Larger payloads should be stored externally (e.g., S3, database) and the event should contain only the identifier and relevant metadata.

meta fields

Beyond the payload, the meta object carries the fields the SIEM uses to normalize (ECS) and enrich the event. All meta values are strings.

client_ip — end-user IP

The problem it solves

Between the browser and the core there are proxies/ALB. The IP the core sees on the connection is the previous hop (the client's backend or an AWS proxy), not the user's. Without action, source.ip would be the proxy IP — useless for geo, threat and IP-based detection. (Real example: XFF arrived as 44.192.13.3 (AWS) while the user was 179.110.4.205.)

The solution

The client's backend is the only one that sees the browser's real IP — so it forwards that IP in meta.client_ip when calling POST /v1/events.

How the SIEM handles it

• Validates it is an IP (v4/v6). A non-IP value is ignored — it does not drop the event.
• Writes to source.ip with maximum precedence (see order below).
• Stamps imtbl.source_ip_origin = "client_asserted" — the UI shows the “User IP” badge.
• Feeds GeoIP, threat intel and IP-based detection rules.

Provenance and trust

client_ip is asserted by the tenant — the client's backend claims the IP, and it is spoofable by whoever controls that backend. However it is self-contained to the tenant (it never crosses another tenant's boundary). A threat/geo hit on a client_asserted value is a claim, not an edge observation.

How to obtain the IP in your backend

Take the first IP from X-Forwarded-For (closest to the user); as a fallback, use the connection IP.

function getClientIp(req: Request): string | undefined {
  const xff = req.headers["x-forwarded-for"];
  if (typeof xff === "string" && xff.length) return xff.split(",")[0].trim(); // primeiro hop
  return req.socket.remoteAddress ?? undefined;
}

const meta = { event_name: "user.login", client_ip: getClientIp(req) };

Payload example

{
  "payload": "{\"user\":\"bob\",\"action\":\"login\"}",
  "meta": {
    "event_name": "user.login",
    "client_ip": "179.110.4.205",
    "immutable_trail": "user-bob"
  }
}

Event ingestion

Send events via `POST /v1/events`. The server computes the SHA-256 hash of the payload, stores the event, and includes it in the next block of the immutable ledger. The response returns the `tx_id` (unique transaction identifier) and the `payload_hash`, which you can use to verify integrity later.

curl -X POST https://api.immutablelog.com/v1/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: seed-42-550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "{\"id\":\"d6b6c2e5-0c1a-4b92-9a62-2f2c4c2e9a2a\",\"kind\":\"info\",\"message\":\"http.GET.user-me\"}",
    "meta": {
      "type": "info",
      "event_name": "http.GET.user-me",
      "immutable_trail": "order-2026-00441",
      "service": "api",
      "env": "prod",
      "trace_id": "2c3f4f1e-7d2d-4d10-9c47-0f8d7a1b2c3d"
    }
  }'

Important: Save the `tx_id` from the response in your system. It is required to query the event individually and to generate the proof of inclusion.

Querying events

The API offers two query modes: listing with filters and pagination, or direct lookup by transaction ID. Use listing for period scans and audits; use the ID lookup when you need to verify a specific event.

curl "https://api.immutablelog.com/v1/events?from_ts=1704067200&to_ts=1704153600&limit=100&type=info" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl "https://api.immutablelog.com/v1/events?trail=order-2026-00441&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "events": [
    {
      "tx_id": "a1b2c3d4-...",
      "timestamp": 1746631234,
      "event_type": "info",
      "event_name": "order.payment_confirmed",
      "immutable_trail": "order-2026-00441",
      "payload_preview": "{\"order_id\":\"ORD-2026-00441\",...}",
      "block_index": 1234
    }
  ],
  "cursor_next": null,
  "count": 7
}

curl "https://api.immutablelog.com/v1/events/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1704067200,
  "payload": "{\"id\":\"d6b6c2e5\",\"kind\":\"info\",\"message\":\"Event received\"}",
  "payload_parsed": { "id": "d6b6c2e5", "kind": "info", "message": "Event received" },
  "payload_hash": "4f2b8e9a3c5d7f1e2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7",
  "meta": {
    "tenant_id": "...",
    "type": "info",
    "event_name": "Event received"
  }
}

Statistics

The statistics endpoint returns event volume grouped by day, with breakdown by type (`success`, `info`, `warning`, `error`). Useful for operational dashboards, audit reports, and volume anomaly monitoring.

curl "https://api.immutablelog.com/v1/events/stats?days=7&tz_offset_minutes=-180" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl "https://api.immutablelog.com/v1/events/stats?from_ts=1769904000&to_ts=1770422399&tz_offset_minutes=-180" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "stats": [
    {
      "date": "2026-02-01",
      "count": 8186,
      "timestamp": 1769904000,
      "by_type": {
        "success": 4523,
        "info": 2103,
        "error": 1203,
        "warning": 357
      }
    },
    {
      "date": "2026-02-02",
      "count": 7892,
      "timestamp": 1769990400,
      "by_type": { "success": 4201, "info": 2145, "error": 1198, "warning": 348 }
    }
  ],
  "total": 54600,
  "total_by_type": {
    "success": 30003,
    "info": 15087,
    "error": 6657,
    "warning": 2853
  }
}

`GET /v1/events/:tx_id/proof` returns the Merkle proof that cryptographically demonstrates a specific event was included in the ledger exactly as submitted, without modification. This proof is self-contained and can be verified by any third party without trusting ImmutableLog.

The proof is cryptographically verifiable and does not depend on trusting the system operator. Ideal for external audits, contractual disputes, and regulatory compliance.

curl "https://api.immutablelog.com/v1/events/a1b2c3d4-e5f6-7890-abcd-ef1234567890/proof" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "tx_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tx_hash": "d20a624740ce1b7e2c74659bb291f665c021d202be02d13ce27feb067eeec837",
  "payload_hash": "75f3ae1057c197610e33633c630a4e0000dd997f095592bb90cf797202a92b07",
  "block_index": 48291,
  "block_hash": "9a59c5f8229aab55e9f855173ef94485aab8497eea0588f365c871d6d0561722",
  "prev_hash": "3da2892d37823d9298e1d5011d7dcfaaf2d9d9a6d465e99be33af5be1d87c12b",
  "merkle_root": "ca12ad3f60dde6fcadc46c58f7a877648c9119484bd2e3178a1b65da78111efa",
  "merkle_path": [
    { "sibling_hash": "a8c0cce8bb067e91cf2766c26be4e5d7cfba3d3323dc19d08a834391a1ce5acf", "position": "left" },
    { "sibling_hash": "7765907da7bb75aa6424ddc1d582fb15ee9a79abfb457e9f9cf2bdf1d24848d6", "position": "right" },
    { "sibling_hash": "773bc304a3b0a626a520a8d6eacc36809ac18c0b174f3ff3cdaf0a4e9c64433d", "position": "left" }
  ]
}

How to verify: How to verify: for each step of `merkle_path`, compute SHA-256 of the concatenation of the two hex strings (not of the decoded bytes): if `position` is `left`, use `sibling_hash + current`; if it is `right`, use `current + sibling_hash`. The initial value of `current` is the `tx_hash`. Repeat for every step, in order. If the final result matches the block's `merkle_root`, inclusion is proven. Do not normalize the values (no lowercasing, no stripping the `0x` prefix): use the strings exactly as the API returns them.

API Responses

The API follows standard REST conventions. All response bodies are JSON. Below are the main HTTP status codes you may encounter and what to do in each case.

{
  "ok": true,
  "tx_id": "3f227a2d-ae7b-4fde-95a5-313197cc6b3a",
  "payload_hash": "00cf048489f716479f124654cdb7c3551a05b46a1245eaaac34bd2fe933f2fd3",
  "status": "accepted",
  "duplicate": false,
  "request_id": "f7ba7cfe-bb18-454c-af2f-19404719b421"
}

{
  "ok": true,
  "tx_id": "3f227a2d-ae7b-4fde-95a5-313197cc6b3a",
  "payload_hash": "00cf048489f716479f124654cdb7c3551a05b46a1245eaaac34bd2fe933f2fd3",
  "status": "committed",
  "duplicate": true,
  "request_id": "f7ba7cfe-bb18-454c-af2f-19404719b421"
}

{
  "ok": false,
  "reason": "missing_idempotency_key"
}

{
  "ok": false,
  "reason": "unauthorized"
}

{
  "ok": false,
  "reason": "forbidden"
}

{
  "ok": false,
  "reason": "monthly_limit_exceeded: 50000/50000 events used this billing cycle"
}

{
  "ok": false,
  "reason": "payload_too_large"
}

{
  "ok": false,
  "reason": "mempool_full"
}