Quick Start

This guide walks you through creating your first log, appending events, and querying a view.

Prerequisites

You’ll need:

A Primatomic account (register at primatomic.com/auth)
An API key or owner credentials
wkg for downloading WASM components (see registry configuration)
curl or an HTTP client of your choice

1. Authenticate

First, obtain a JWT token by exchanging your API key:

curl -X POST https://api.primatomic.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key_here"}'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Include this token in the Authorization header for all subsequent requests:

export TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Create a Log

Create an event log to store your events. Log names must be unique within your tenant:

curl -X POST https://api.primatomic.com/logs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-events"}'

Response:

{
  "success": true,
  "log_id": "550e8400-e29b-41d4-a716-446655440000"
}

Save the log_id — all endpoints use UUIDs:

export LOG_ID="550e8400-e29b-41d4-a716-446655440000"

3. Append Events

Append events to your log. The append endpoint uses the log UUID. Event payloads are sent as raw bytes — the format is defined by your view. The counter example expects JSON with inc or dec fields:

curl -X POST https://api.primatomic.com/logs/$LOG_ID/append \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -d '{"inc": 10}'

Response:

{
  "success": true,
  "sequence": 1
}

Append a few more events to see the counter in action:

curl -X POST https://api.primatomic.com/logs/$LOG_ID/append \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -d '{"inc": 20}'

curl -X POST https://api.primatomic.com/logs/$LOG_ID/append \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -d '{"dec": 5}'

Store the sequence number from the last response if you need read-after-write consistency.

4. Deploy a View

Views are WebAssembly components that process log events. The WASM binary must implement the primatomic:machine interface (see WASM Interface):

# Download the example counter WASM
curl -o counter.wasm https://primatomic.com/examples/counter.wasm

# Deploy it — create view uses the view name in the path
curl -X POST https://api.primatomic.com/logs/$LOG_ID/views/counter \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @counter.wasm

Response:

{
  "success": true,
  "view_id": "660e8400-e29b-41d4-a716-446655440001"
}

Save the view_id for querying:

export VIEW_ID="660e8400-e29b-41d4-a716-446655440001"

5. Check View Status

Before querying, verify the view has a leader and is processing events:

curl https://api.primatomic.com/logs/$LOG_ID/views/$VIEW_ID/stats \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "log_id": "550e8400-e29b-41d4-a716-446655440000",
  "log_name": "my-events",
  "view_id": "660e8400-e29b-41d4-a716-446655440001",
  "view_name": "counter",
  "leader_status": "ready",
  "leader_address": "10.0.0.5:3000",
  "processed_sequence": 3,
  "created_at": 1705680000
}

When leader_status is "ready", the view is available for queries. If leader_status is null, wait and retry.

6. Query the View

Query your view. You can specify a sequence number for read-after-write consistency:

# With read-after-write consistency (waits for sequence 3)
curl -X POST "https://api.primatomic.com/logs/$LOG_ID/views/$VIEW_ID/query?after=3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary ""

Request/Response Format:

Aspect	Specification
Request Content-Type	`application/octet-stream`
Request Body	Binary query input (format defined by view)
Response Content-Type	`application/octet-stream`
Response Body	Binary query output (format defined by view)

The response body format is defined by your view’s query function. The counter example returns JSON:

curl -s -X POST "https://api.primatomic.com/logs/$LOG_ID/views/$VIEW_ID/query?after=3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary ""
# Response: {"count":25}

The counter processed all three events: 10 + 20 - 5 = 25.

If you omit the after parameter, the service may return stale results.

Service Guarantees

Guarantee	Description
Durability	Events are not acknowledged until durably stored
Log Ordering	Sequence numbers are strictly monotonically increasing; each event stored exactly once
View Processing	Events processed in order; at-least-once (views must be deterministic)
Consistency	Queries with `after` parameter reflect all events up to that sequence
Isolation	Tenants cannot access other tenants’ resources

Next Steps

Authentication - API keys and token management
WASM Interface - Build your own views
Consistency Model - Read-after-write guarantees
Conventions - Terminology and service guarantees