REST API Reference

Stable compatibility surface. TokST maintains existing REST routes and contracts in V0.9.0. Cloud MCP is the public Agent interface for durable knowledge; this reference documents the compatible REST knowledge surface.

API scope

TokST publishes this REST API as a stable compatibility surface for durable knowledge. New integrations should use Cloud MCP for memory, context, knowledge bases, workspace governance, evidence files, and account status.

Connected Runtime APIs support the TokST CLI, device bridges, automatic sessions, Agent communication, and directed tasks. They remain private implementation interfaces and are not a public integration contract.

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. REST requests use the Authorization header.

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/mcp 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

Memories

Memory lifecycle

Memory changes are reversible through archive and restore. The public compatibility API does not expose permanent memory deletion. A user may permanently clear an archived memory only from the Dashboard archive view after manual confirmation.

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"]}'

Archive Atlases and Workspaces through their archive operations. The Dashboard archived views provide the user-confirmed permanent cleanup path.

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 and MCP 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 32-tool MCP Streamable HTTP surface at https://api.tokst.com/mcp. See the MCP reference.

Connected Runtime

Automatic sessions, Agent communication, task delivery, and task execution use the authenticated TokST Runtime after the CLI connects a device. These private Runtime APIs are maintained for the Dashboard and connected CLI; external integrations use Cloud MCP for durable knowledge.