REST API

Base URL

http(s)://your-cosmictron-host:3000

All endpoints require a Authorization: Bearer <token> header unless noted as public.

Authentication

POST /v1/auth/sign-up

Create a new identity with email/password.

curl -X POST /v1/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

Response:

{ "token": "eyJ...", "identity": "abc123", "expires_at": 1735689600 }

POST /v1/auth/sign-in

Authenticate with email/password.

POST /v1/auth/magic-link/request

Send a magic link to an email address.

POST /v1/auth/magic-link/verify

Verify a magic link token and return a session token.

---

Modules

POST /v1/modules

Upload and deploy a module.

curl -X POST /v1/modules \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=my-agent" \
  -F "module=@my_agent.wasm"

Response:

{
  "name": "my-agent",
  "version": "sha256:a3f2...",
  "status": "active",
  "reducers": ["record_agent_message", "record_tool_call", "complete_tool_call"]
}

GET /v1/modules

List deployed modules.

GET /v1/modules/:name

Get module details.

DELETE /v1/modules/:name

Undeploy a module.

---

Reducers

POST /v1/reducers/:name

Invoke a reducer by name.

curl -X POST /v1/reducers/record_agent_message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "abc", "role": "user", "content": "Hello"}'

Response:

{ "tx_id": 12345, "status": "committed", "duration_ms": 2 }

Tip

For high-throughput workloads, prefer the WebSocket interface for reducer calls — it batches multiple calls into a single connection and avoids per-request TCP overhead.

---

SQL Queries

POST /v1/sql

Execute a read-only SQL query.

curl -X POST /v1/sql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM agent_state WHERE session_id = $1", "params": ["session-abc"]}'

Response:

{
  "columns": ["id", "session_id", "role", "content", "created_at"],
  "rows": [
    [1, "session-abc", "user", "Hello", 1735689600000000]
  ]
}

Time-travel queries

{
  "query": "SELECT * FROM agent_state AS OF TX 1234567"
}

---

Health

GET /v1/health

Liveness probe. Returns 200 OK if the process is running.

GET /v1/health/ready

Readiness probe. Returns 200 OK when WAL and storage are ready.

GET /v1/health/detailed

Full diagnostic JSON. See Monitoring.

---

SDK Macros (Rust)

#[table]

#[table(name = "users", public)]
#[rls(read = "owner_id = $identity")]
pub struct User {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub username: String,
}

Table attributes: name (required), public, event (append-only).

Field attributes: #[primary_key], #[auto_inc], #[index], #[unique], #[fk(table.column)], #[pii].

#[reducer]

#[reducer]
pub fn create_user(ctx: &ReducerContext, username: String) { ... }

Lifecycle variants: #[reducer(init)], #[reducer(client_connected)], #[reducer(client_disconnected)].

#[rls]

#[rls(read = "author_id = $identity OR is_public = true")]
#[rls(write = "author_id = $identity")]

Variables: $identity (current caller’s identity).

#[view]

#[view]
pub fn active_sessions() -> impl Iterator<Item = AgentSession> {
    AgentSession::filter(|s| s.status == "active")
}

---

TypeScript Client

Installation

bun add @cosmictron/client

CosmictronClient

import { CosmictronClient } from '@cosmictron/client';

const client = new CosmictronClient('wss://your-host:3000');

// Auth
await client.signIn({ email: 'user@example.com', password: 'secret' });

// Call a reducer
await client.callReducer('create_user', { username: 'alice' });

// Subscribe to a query
const sub = await client.subscribe('SELECT * FROM users');
sub.on('update', ({ inserts, deletes }) => { ... });
sub.unsubscribe();

// Direct SQL query (read-only)
const rows = await client.query('SELECT * FROM users WHERE id = $1', [1]);

React hooks

import { useQuery, useReducer, useIdentity } from '@cosmictron/react';

function UserList() {
  const users = useQuery('SELECT * FROM users');
  const createUser = useReducer('create_user');

  return (
    <ul>
      {users.rows.map(u => <li key={u.id}>{u.username}</li>)}
    </ul>
  );
}