Events API

Ingest and query structured audit log events. Events are immutable records that cannot be modified or deleted after ingestion.

Ingest Events#

POST/api/v1/events

Send a single event or a batch of up to 100 events in a single request.

Auth: Project key or Master key

Request body

Name	Type	Required	Description
action	string	Required	Dot-namespaced action name (e.g. user.created). Must match ^[a-z][a-z0-9_](\.[a-z][a-z0-9_])+$
category	string	Required	One of: auth, access, mutation, admin, security, system
actor	object	Required	{ id (required), type (required: user \| api_key \| service \| system), name (optional), email (optional) }
tenant_id	string	Required	Your customer's unique identifier
target	object	Optional	The resource acted upon. { id (required), type (required), name (optional) }
context	object	Optional	Request context. { ip_address, user_agent, location, session_id } (all optional)
metadata	object	Optional	Arbitrary key-value pairs attached to the event
changes	array	Optional	Array of field changes. Each item: { field, before, after }
idempotency_key	string	Optional	Unique key for deduplication. Auto-generated by the SDK.
occurred_at	string	Optional	ISO 8601 timestamp. Defaults to server receive time if omitted.

Single event

curl -X POST https://logstitch.io/api/v1/events \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.invited",
    "category": "mutation",
    "actor": { "id": "user_123", "type": "user", "name": "Alice" },
    "tenant_id": "acme_corp",
    "target": { "id": "user_456", "type": "user", "name": "Bob" },
    "metadata": { "role": "editor" }
  }'

Batch request (array)

curl -X POST https://logstitch.io/api/v1/events \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '[
    {
      "action": "user.invited",
      "category": "mutation",
      "actor": { "id": "user_123", "type": "user", "name": "Alice" },
      "tenant_id": "acme_corp",
      "target": { "id": "user_456", "type": "user", "name": "Bob" }
    },
    {
      "action": "document.created",
      "category": "mutation",
      "actor": { "id": "user_123", "type": "user", "name": "Alice" },
      "tenant_id": "acme_corp",
      "target": { "id": "doc_789", "type": "document", "name": "Q1 Report" }
    }
  ]'

201Success

Response

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

Batch ingestion

Send up to 100 events in a single request by passing an array instead of an object. Each event in the batch is validated independently.

Query Events#

GET/api/v1/events

Retrieve events with filtering and cursor-based pagination. Results are returned in reverse chronological order.

Auth: Project key, Master key, or Viewer token

Query parameters

Name	Type	Required	Description
tenant_id	string	Optional	Filter by tenant. Required for viewer tokens (auto-applied).
actor_id	string	Optional	Filter by actor ID
actor_type	string	Optional	Filter by actor type (user, api_key, service, system)
action	string	Optional	Filter by action. Supports wildcard suffix: user.* matches user.created, user.deleted, etc.
category	string	Optional	Filter by category (auth, access, mutation, admin, security, system)
target_id	string	Optional	Filter by target ID
target_type	string	Optional	Filter by target type
start_date	string	Optional	ISO 8601 datetime -- only events on or after this time
end_date	string	Optional	ISO 8601 datetime -- only events on or before this time
search	string	Optional	Full-text search across action, actor name, and target name
cursor	string	Optional	Pagination cursor from a previous response
limit	number	Optional	Number of events per page (1-200, default 50)

Query with filters

curl "https://logstitch.io/api/v1/events?tenant_id=acme_corp&category=mutation&limit=25" \
  -H "Authorization: Bearer pk_..."

200Success

Response

{
  "events": [
    {
      "id": "evt_01HX...",
      "action": "user.created",
      "category": "mutation",
      "actor": { "id": "user_123", "type": "user", "name": "Alice" },
      "tenant_id": "acme_corp",
      "target": { "id": "user_456", "type": "user", "name": "Bob" },
      "content_hash": "sha256:abc...",
      "redacted": false,
      "occurred_at": "2026-01-15T09:30:00.000Z",
      "received_at": "2026-01-15T09:30:01.234Z"
    }
  ],
  "cursor": "eyJv...",
  "has_more": true,
  "request_id": "req_abc123"
}

Viewer token behavior

Viewer tokens automatically filter by their embedded tenant_id. They can only be used to read events and cannot ingest events or perform administrative operations.