API Documentation

Integrate your Spokest brain with external tools, automations, and workflows. Available on the Mastermind plan.

Quickstart

Send your first message in under 30 seconds. Replace YOUR_API_KEY with a key from Settings > Developer (Mastermind tier required).

curl -X POST https://brain-api.spokest.com/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, brain"}'

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created from Settings > Developer (Mastermind tier required). Keys use the format sk_live_....

Authorization: Bearer sk_live_YOUR_KEY

Keys have full access to your brain. Keep them secret. If a key is compromised, revoke it immediately from Settings > Developer.

Base URL

https://brain-api.spokest.com

All endpoints are relative to this base URL. HTTPS is required for all requests.

Endpoints

Chat

POST /v1/chat

Send a message and receive a response with memory context.

Request body

{
  "message": "What did I decide about the pricing model?",
  "session_id": "optional-session-id"
}

Response

{
  "response": "Based on your notes from March 19...",
  "session_id": "abc123"
}

Memory

POST /v1/memory/store

Store a memory in your brain. The text field contains the memory content.

{
  "text": "Meeting with investor: agreed on $500K seed round at $5M valuation",
  "metadata": {
    "source": "api",
    "topics": ["fundraising", "meetings"]
  }
}

POST /v1/memory/recall

Search your memories by natural language query.

{
  "query": "What happened at the investor meeting?",
  "limit": 10
}

POST /v1/memory/connect

Create a relationship between two memories.

{
  "fromId": "mem_abc123",
  "toId": "mem_def456",
  "relation": "led_to"
}

POST /v1/memory/story

Reconstruct a narrative from related memories.

{
  "query": "How did the fundraising process unfold?",
  "maxResults": 20
}

GET /v1/memories

List memories with pagination.

GET /v1/memories?limit=20&offset=0

Brain (Advanced)

POST /v1/brain/panel Mastermind

Get multiple perspectives on a topic from different thinking modes.

{
  "topic": "Should we pivot to B2B?",
  "perspectives": ["strategist", "devil_advocate", "researcher"]
}

POST /v1/brain/search-with-citations Mastermind

Search with verified sources and citations.

{
  "query": "Latest trends in AI memory systems"
}

API Key Management

POST /v1/api-keys Mastermind

Create a new API key.

{
  "name": "My Integration"
}

Response

{
  "id": "key_abc123",
  "name": "My Integration",
  "key": "sk_live_...",
  "created_at": "2026-04-01T12:00:00Z"
}

The full key is only returned once at creation. Store it securely.

GET /v1/api-keys Mastermind

List all API keys for your account. Keys are returned with a masked prefix only.

DELETE /v1/api-keys/:id Mastermind

Revoke an API key. This action is immediate and irreversible.

Webhooks

POST /v1/webhooks Mastermind

Create a webhook subscription to receive events from your brain.

{
  "url": "https://your-app.com/webhook",
  "events": ["memory.stored", "chat.completed"]
}

GET /v1/webhooks Mastermind

List all webhook subscriptions.

GET /v1/webhooks/:id Mastermind

Get details of a specific webhook subscription.

PATCH /v1/webhooks/:id Mastermind

Update a webhook subscription (URL, events, or enabled status).

{
  "url": "https://your-app.com/new-webhook",
  "events": ["memory.stored"],
  "enabled": true
}

DELETE /v1/webhooks/:id Mastermind

Delete a webhook subscription.

GET /v1/webhooks/:id/deliveries Mastermind

View the delivery log for a webhook. Shows recent delivery attempts, status codes, and timestamps.

POST /v1/webhooks/:id/test Mastermind

Send a test ping event to verify your webhook endpoint is reachable.

Error Handling

Errors return a flat JSON object with an error field and an appropriate HTTP status code.

{
  "error": "Invalid API key"
}

Status	Meaning
`400`	Bad request. Check your request body.
`401`	Unauthorized. Invalid or missing API key.
`403`	Forbidden. Your plan does not include this feature.
`429`	Rate limited. Wait and retry.
`500`	Server error. Contact support if persistent.

Rate Limits

API requests are rate limited per key. Current limits for Mastermind:

Endpoint	Limit
`/v1/chat`	30 requests per minute
`/v1/memory/store`	60 requests per minute
`/v1/memory/recall, connect, graph, story`	120 requests per minute
`/v1/memory/import`	10 requests per minute
All other endpoints	20 requests per minute (default)

When rate limited, the API returns a 429 status. Wait before retrying.

MCP Server

Connect your Spokest brain directly to Claude Code or Cursor using the Model Context Protocol (MCP). This lets AI assistants access your memories and brain capabilities as tools.

An API key is required. Create one from Settings > Developer (Mastermind tier required).

Setup for Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "spokest": {
      "command": "node",
      "args": ["/path/to/mcp-server/bin/spokest-mcp.mjs"],
      "env": {
        "SPOKEST_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Setup for Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "spokest": {
      "command": "node",
      "args": ["/path/to/mcp-server/bin/spokest-mcp.mjs"],
      "env": {
        "SPOKEST_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Replace /path/to/mcp-server/ with the actual install location of the Spokest MCP server. Once connected, your AI assistant can recall memories, store new ones, and use your brain's panel and search capabilities as tools.