Streams API

Anonymous event ingestion with deferred signup. Start sending events immediately — no account, API key, or dashboard required. Claim your stream later to bind it to a project.

How It Works#

Call LogStitch.stream() in the SDK — it generates a random claim token and starts sending events to an unauthenticated endpoint.
Events are stored in a temporary stream with a 7-day TTL, protected by built-in PII redaction.
When ready, sign up and claim the stream from the dashboard or API. All events are migrated into your project atomically.

Security

Stream events are stored separately from authenticated project events. No event data is readable through the stream endpoints — only metadata (count, status, expiry) is exposed. Events become queryable only after claiming.

Ingest Stream Events#

POST/api/v1/streams/:token/events

Send events to an anonymous stream. The stream is auto-created on the first request to a new token. No authentication required.

Auth: None

URL parameters

Name	Type	Required	Description
:token	string (UUIDv4)	Required	The claim token. Must be a valid UUIDv4 format.

Request body

Name	Type	Required	Description
action	string	Required	Dot-namespaced action name (e.g. user.created)
category	string	Required	One of: auth, access, mutation, admin, security, system
actor	object	Required	{ id (required), type (required), name (optional), email (optional) }
tenant_id	string	Required	Your customer's unique identifier
target	object	Optional	The resource acted upon. { id, type, name }
metadata	object	Optional	Arbitrary key-value data
idempotency_key	string	Optional	Unique key for deduplication

Send a stream event

curl -X POST https://logstitch.io/api/v1/streams/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/events \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.signed_up",
    "category": "auth",
    "actor": { "id": "user_123", "type": "user" },
    "tenant_id": "acme_corp"
  }'

201Success

Response

{
  "ids": ["evt_01HX..."],
  "redacted_count": 0,
  "request_id": "req_abc123"
}

PII Redaction

Stream events automatically have built-in PII redaction applied (credit card, SSN, email, phone, JWT, bearer token, AWS key). Custom redaction rules are not available until the stream is claimed.

Get Stream Info#

GET/api/v1/streams/:token/info

Get metadata about a stream. Returns event count, status, and expiry. No event data is exposed.

Auth: None

Check stream status

curl https://logstitch.io/api/v1/streams/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/info

200Success

Response

{
  "claim_token": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "event_count": 42,
  "status": "active",
  "created_at": "2026-02-20T10:00:00.000Z",
  "expires_at": "2026-02-27T10:00:00.000Z",
  "request_id": "req_abc123"
}

Claim Stream#

POST/api/v1/streams/claim

Bind an anonymous stream to a project. All stream events are atomically migrated into the project's event table. The stream is permanently locked after claiming.

Auth: Master key

Request body

Name	Type	Required	Description
claim_token	string (UUIDv4)	Required	The claim token for the stream to bind to this project.

Claim a stream

curl -X POST https://logstitch.io/api/v1/streams/claim \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{ "claim_token": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }'

200Success

Response

{
  "event_count": 42,
  "request_id": "req_abc123"
}

One-way operation

Claiming a stream is irreversible. Once claimed, the token is permanently locked and cannot be reused. Events are moved (not copied) into the target project.

Rate Limits#

Streams have tighter rate limits than authenticated endpoints to prevent abuse of the unauthenticated ingestion path.

Limit	Value	Scope
Requests per minute	30	Per IP address
Events per day	100	Per stream
Lifetime events	500	Per stream
New streams per day	10	Per IP address
Stream expiry	7 days	From creation