API Reference

Complete REST API documentation for SealTrail.

Base URL

All API requests are made to:

https://api.sealtrail.dev

All endpoints require authentication via API key. See Authentication for details.

Response format

All successful responses follow a consistent envelope:

success-response.json

// Single resource
{ "data": { "id": "evt_...", "actor": "user_123", ... } }

// Collection (paginated)
{ "data": [{ ... }, { ... }], "nextCursor": "eyJjcmVhdGVk..." }

Error responses use a separate structure:

error-response.json

{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": { ... } } }

Cursor pagination

List endpoints use cursor-based pagination. The cursor is a Base64-encoded, opaque string — do not parse or construct it yourself.

nextCursor is only present when more results exist.
Pass it as ?cursor=... to fetch the next page.
Combine with ?limit=N to control page size (default: 50, max: 200).

Events

POST /v1/events #

Log a new audit event. The event is appended to a hash chain, ensuring cryptographic integrity. Returns the created event with its computed hash and chain position.

Request body

Name	Type	Required	Description
`actor`	string	Required	Who performed the action (user ID, email, service name)
`action`	string	Required	What happened (e.g. invoice.approved, user.deleted)
`resource`	string	Optional	What was acted upon (e.g. inv_456, user_789)
`context`	object	Optional	Additional metadata as key-value pairs
`chain`	string	Optional	Chain name for partitioning (default: "default")

Response

Name	Type	Required	Description
`id`	string	Required	Event ID (evt_ prefix)
`actor`	string	Required	Actor from the request
`action`	string	Required	Action from the request
`resource`	string \| null	Required	Resource from the request
`context`	object \| null	Required	Context metadata
`chain`	object	Required	Chain info: { id, name, position }
`hash`	string	Required	SHA-256 hash of this event
`previousHash`	string	Required	Hash of the previous event in the chain
`timestamp`	string	Required	ISO 8601 timestamp
`createdAt`	string	Required	Server-side insertion time (ISO 8601, used for cursor pagination)

Example

terminal

curl -X POST https://api.sealtrail.dev/v1/events \
  -H "Authorization: Bearer stl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "user_123",
    "action": "invoice.approved",
    "resource": "inv_456",
    "context": { "ip": "192.168.1.1", "amount": 1500 }
  }'

GET /v1/events #

Query your audit events with optional filters. Supports cursor-based pagination for efficient iteration over large datasets.

Query parameters

Name	Type	Required	Description
`actor`	string	Optional	Filter by actor
`action`	string	Optional	Filter by action
`resource`	string	Optional	Filter by resource
`chain_id`	string	Optional	Filter by chain ID (use GET /v1/chains to find IDs by name)
`after`	string	Optional	Events after this ISO 8601 datetime
`before`	string	Optional	Events before this ISO 8601 datetime
`limit`	number	Optional	Page size (default: 50, max: 200)
`cursor`	string	Optional	Cursor for next page (from previous response)

Example

terminal

curl "https://api.sealtrail.dev/v1/events?actor=user_123&limit=10" \
  -H "Authorization: Bearer stl_live_..."

GET /v1/events/:id #

Retrieve a single event by its ID. Returns the full event data including hash chain information.

Example

terminal

curl "https://api.sealtrail.dev/v1/events/evt_abc123" \
  -H "Authorization: Bearer stl_live_..."

Verification

GET /v1/events/:id/verify #

Verify a single event's hash integrity. Re-computes the expected hash from the event payload and previous hash, then compares it with the stored hash. Detects any tampering.

Response

Name	Type	Required	Description
`valid`	boolean	Required	Whether the event hash is valid
`errors`	string[]	Required	List of integrity errors (empty if valid)
`eventHash`	string	Required	The stored hash
`computedHash`	string	Required	The re-computed hash
`chainIntact`	boolean	Required	Whether the chain link is valid
`verifiedAt`	string	Required	ISO 8601 timestamp of verification

Example

terminal

curl "https://api.sealtrail.dev/v1/events/evt_abc123/verify" \
  -H "Authorization: Bearer stl_live_..."

Chains

GET /v1/chains #

List all hash chains for your account. Each chain is an independent, ordered sequence of events. Chains are created automatically when you log an event with a new chain name.

Response

Name	Type	Required	Description
`id`	string	Required	Chain ID
`name`	string	Required	Chain name
`lastHash`	string	Required	Hash of the latest event
`lastPosition`	number	Required	Position of the latest event
`eventCount`	number	Required	Total events in this chain
`createdAt`	string	Required	ISO 8601 creation date

Example

terminal

curl "https://api.sealtrail.dev/v1/chains" \
  -H "Authorization: Bearer stl_live_..."

GET /v1/chain/:chainId/status #

Get the current status of a specific hash chain, including its latest hash, position, and total event count.

Response

Name	Type	Required	Description
`id`	string	Required	Chain ID
`name`	string	Required	Chain name
`lastHash`	string	Required	Hash of the latest event
`lastPosition`	number	Required	Position of the latest event
`eventCount`	number	Required	Total events in this chain
`createdAt`	string	Required	ISO 8601 creation date

Example

terminal

curl "https://api.sealtrail.dev/v1/chain/chn_abc123/status" \
  -H "Authorization: Bearer stl_live_..."

← Authentication Error Handling →