REST API Reference

Automatic Memory API

The Auto API stores user and workspace policy. The local ACP service owns event delivery and compilation; application integrations use explicit Session lifecycle endpoints for deliberate task records.

TokST exposes its authenticated REST API at https://api.tokst.com/v1 plus an unauthenticated health check. The production API uses the same per-user and workspace access rules as the dashboard and remote MCP server.

The machine-readable OpenAPI 3.1 document is available at https://api.tokst.com/openapi.json. It describes authentication, typed operations, request parameters, and response shapes for programmatic clients.

TokST Local is a private CLI and stdio MCP profile. Local memory stays in SQLite on the current device and does not expose a network REST listener. Use the cloud API for cloud workspaces and Atlases.

Send structured Markdown in a memory content field for decisions, architecture, meeting notes, and tasks. Short facts can remain plain text. Keep credentials, private keys, raw reasoning, and transient tool output outside memory records.

Agent Identity and Messages

Send X-TokST-Actor: agent with an API Key to use a trusted Agent identity. The server creates or resolves the API-Key-bound agt_... identity; client-provided Agent IDs are rejected. sourceName remains a source label.

Authentication

Send your TokST API key in the Authorization header:

curl https://api.tokst.com/v1/status \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxx"

Keep API keys in a secret manager or environment variable. URL query authentication exists only for legacy MCP session compatibility and should not be used for REST requests.

Referrals and Benefits

New account attribution is set only during registration through a referral link. A qualifying memory created through this API, the dashboard, CLI, or MCP activates a verified referral automatically.

OAuth for Remote MCP

Remote MCP clients use OAuth 2.1 authorization code flow with PKCE. Connect the client to https://api.tokst.com/mcp; it discovers /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, opens TokST for account and workspace approval, then stores refreshable bearer credentials. REST automations continue to use an API key.

Endpoint Inventory

Health and Account

Agents and Messages

The SSE stream requires Authorization: Bearer $TOKST_API_KEY and X-TokST-Actor: agent. It sends ready, message.created, heartbeat, and auth.revoked events. The CLI manages reconnects and unread-message recovery through tokst agent listen.

Memories

Atlases

Workspaces

Memory Requests

Create

curl -X POST https://api.tokst.com/v1/memories \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Production deploys require approval on Fridays.",
    "type": "decision",
    "title": "Release policy",
    "tags": ["deploy", "policy"],
    "atlasId": "00000000-0000-0000-0000-000000000000"
  }'

content is required. type defaults to note. Supported types are fact, decision, preference, task, architecture, and note. When workspaceId is supplied it must match the selected atlas.

List and Context

# type accepts one value or a comma-separated list; limit is 1-100
curl "https://api.tokst.com/v1/memories?atlas_id=$ATLAS_ID&type=decision,note&limit=20" \
  -H "Authorization: Bearer $TOKST_API_KEY"

curl "https://api.tokst.com/v1/memories/context?atlas_id=$ATLAS_ID&limit=10" \
  -H "Authorization: Bearer $TOKST_API_KEY"

Search

curl -X POST https://api.tokst.com/v1/memories/search \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"release approval rules","atlas_id":"'$ATLAS_ID'","mode":"auto","limit":10}'

mode accepts auto, keyword, semantic, or hybrid and defaults to auto. The response includes mode plus meta with the requested/resolved mode, cache level, strong-keyword decision, and stage timings.

• keyword returns ranked title/content keyword matches.
• semantic returns vector results only.
• hybrid always fuses both lists with RRF.
• keyword_fallback records a bounded embedding failure while preserving keyword results.

Update and Append

curl -X PATCH https://api.tokst.com/v1/memories/mem_xxx \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated policy","type":"decision","tags":[]}'

curl -X POST https://api.tokst.com/v1/memories/mem_xxx/append \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Approved by the release manager."}'

Sending an empty tags array clears existing tags. Content updates and appends regenerate the semantic embedding.

Verify and Supersede

curl -X POST https://api.tokst.com/v1/memories/mem_xxx/verify \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"evidence":"https://example.com/policy","confidence":0.95,"validUntil":"2027-01-01T00:00:00Z"}'

curl -X POST https://api.tokst.com/v1/memories/mem_old/supersede \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replacementMemoryId":"mem_new"}'

Verification marks a record as reviewed and stores its supporting metadata. Superseding marks the earlier record as superseded and preserves a link to the replacement.

Atlas and Workspace Requests

curl -X POST https://api.tokst.com/v1/workspaces \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform Team"}'

curl -X POST https://api.tokst.com/v1/atlases \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","workspaceId":"'$WORKSPACE_ID'","keywords":["deploy","release"]}'

Atlas deletion is cascading and also removes attachment objects. Workspace deletion is intentionally non-cascading: delete its atlases first, then delete the empty workspace.

Team Membership

# Invite multiple people for seven days.
curl -X POST "https://api.tokst.com/v1/workspaces/$WORKSPACE_ID/invitations" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]"],"role":"member","expiresInDays":7}'

# The recipient accepts an invitation from their own inbox.
curl -X POST "https://api.tokst.com/v1/workspace-invitations/$INVITATION_ID/respond" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accept":true,"confirm":true}'

The database enforces workspace roles for every membership RPC. Owner manages all membership changes and ownership transfer. Admin manages ordinary members. Member can leave and can manage only their own memories.

File Workflow

File transfers use the unified Supabase Edge Function at /functions/v1/tokst. These routes accept the short-lived user JWT returned by POST /auth/exchange, while normal REST routes accept tk_live_... API keys.

The CLI, web dashboard, and MCP tools implement this workflow. See File Attachments for complete examples.

Response and Error Model

Successful responses return a typed JSON object documented in the OpenAPI 3.1 contract. Errors use one stable shape:

{
  "error": "quota_exceeded",
  "code": "quota_exceeded",
  "message": "The current monthly quota has been reached. Retry after the reported reset time or upgrade capacity."
}

error remains available for existing clients. code is the canonical machine-readable value. message provides recovery guidance and must not be parsed for program control.

Resource lookups are scoped to the authenticated owner and workspace memberships. A resource outside that scope resolves as unavailable.

Rate Limit Headers

Authenticated REST responses expose the monthly quota window using standard headers:

Clients should slow or pause work when RateLimit-Remaining approaches zero. After 429, wait for Retry-After before retrying. TokST currently exposes pull-based REST, MCP, and Session event interfaces; public outbound webhooks are not available.

Versioning and Deprecation

TokST keeps stable cloud REST routes under /v1. Additive fields, endpoints, and optional request parameters can ship within /v1. A change that removes a field, changes its meaning, or changes authorization behavior receives a new major API path.

TokST announces a planned endpoint or field retirement in this reference and the release history at least 90 days before removal. During the announced period, affected HTTP responses include Deprecation: true and a Sunset date where the route can provide those headers. Clients should treat unknown response fields as forward-compatible and use error codes rather than parsed error text for recovery logic.

MCP Endpoint

The same host serves the complete 46-tool MCP Streamable HTTP surface at https://api.tokst.com/mcp. See the MCP reference; deployments can set TOKST_MCP_TOOLSET=core for the focused 11-tool memory surface.

Session Memory API

Session Memory creates a durable record for an Agent task. Agent clients send X-TokST-Actor: agent; TokST injects the trusted agt_... identity.

curl -X POST https://api.tokst.com/v1/sessions \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "X-TokST-Actor: agent" \
  -H "Content-Type: application/json" \
  -d '{"atlasId":"<atlas-id>","task":"Implement the API"}'

Candidate writes accept sourceEventId. Automatic bridges use task units: an independent task creates one formal memory, and a follow-up updates the matching unit. The event adapter enum supports acp, workbuddy, opencode, pi, codex, and claude; Claude Desktop remains MCP-assisted. Repeating a session and event ID returns the existing candidate. Members manage their own sessions. Workspace Owners and Admins may request scope=managed and govern candidate promotion. Reverting a compiled candidate archives its linked formal memory.

The Session Memory guide covers lifecycle expectations, idempotency, Agent handoffs, review permissions, Local behavior, and dashboard governance.