Realtime API

Subscribe to a Server-Sent Events (SSE) stream to receive project events in real time. This is the recommended alternative to polling for extraction results.

Event stream

Opens a persistent SSE connection that emits events for the authenticated project. Requires the standard authentication headers.

Headers

curl

curl -N "https://api.aidenid.com/v1/realtime/stream" \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Accept: text/event-stream"

Event types

Event format

Each SSE event contains four fields:

Raw SSE example

event: extraction.completed
id: evt_x1y2z3
retry: 3000
data: {"identity_id":"ident_a1b2c3d4e5","type":"otp","has_secret":true,"redacted_value":"***","confidence":0.99,"extracted_at":"2026-04-06T10:05:02Z"}

event: identity.expired
id: evt_a4b5c6
retry: 3000
data: {"identity_id":"ident_f6g7h8i9j0","expired_at":"2026-04-06T12:00:00Z"}

event: inbound.received
id: evt_d7e8f9
retry: 3000
data: {"identity_id":"ident_a1b2c3d4e5","from":"noreply@github.com","subject":"Your verification code","received_at":"2026-04-06T10:04:58Z"}

JavaScript (EventSource)

The browser-native EventSource API does not support custom headers. Use the eventsource npm package for Node.js or pass authentication via query parameters if your backend supports it.

TypeScript (Node.js)

import EventSource from "eventsource";

const es = new EventSource(
  "https://api.aidenid.com/v1/realtime/stream",
  {
    headers: {
      "Authorization": "Bearer aid_your_api_key",
      "X-Org-Id": "org_abc123",
      "X-Project-Id": "proj_def456",
    },
  }
);

es.addEventListener("extraction.completed", (event) => {
  const data = JSON.parse(event.data);
  console.log(`Extraction completed for ${data.identity_id}: ${data.type}`);
});

es.addEventListener("identity.created", (event) => {
  const data = JSON.parse(event.data);
  console.log(`New identity: ${data.identity_id}`);
});

es.addEventListener("inbound.received", (event) => {
  const data = JSON.parse(event.data);
  console.log(`Inbound event received for ${data.identity_id}`);
});

es.onerror = (err) => {
  console.error("SSE connection error:", err);
  // EventSource will auto-reconnect with Last-Event-ID
};

Python (sseclient)

import requests
import sseclient
import json

url = "https://api.aidenid.com/v1/realtime/stream"
headers = {
    "Authorization": "Bearer aid_your_api_key",
    "X-Org-Id": "org_abc123",
    "X-Project-Id": "proj_def456",
    "Accept": "text/event-stream",
}

response = requests.get(url, headers=headers, stream=True)
client = sseclient.SSEClient(response)

for event in client.events():
    data = json.loads(event.data)

    if event.event == "extraction.completed":
        print(f"Extraction completed for {data['identity_id']}: {data['type']}")
    elif event.event == "inbound.received":
        print(f"Inbound event received for {data['identity_id']}")
    elif event.event == "identity.expired":
        print(f"Identity expired: {data['identity_id']}")

Reconnection

If the SSE connection drops, reconnect and include the Last-Event-ID header set to the id of the last event you received. The server will replay any events that occurred while you were disconnected.

curl -N "https://api.aidenid.com/v1/realtime/stream" \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Last-Event-ID: evt_x1y2z3" \
  -H "Accept: text/event-stream"

Error codes

Related

• Webhooks API — push-based alternative to SSE streaming
• Identities API — poll for extractions if SSE is not available
• Consumer API — consumer-scoped SSE inbox stream