ContoxContox|Documentation

Endpoint

GET /api/v2/brain

The brain endpoint assembles and returns your project's complete memory as a structured markdown document. This is the primary endpoint used by MCP servers and CLI tools to load project context at the start of a session.

Authentication

Supports Bearer token or session cookie authentication.

Query parameters

ParameterTypeDefaultDescription
projectIdstringRequiredThe project ID
tokenBudgetnumber6000Approximate token budget for the assembled document

Token budget

The tokenBudget parameter controls the maximum approximate size of the returned brain document. The assembler prioritizes higher-tier items and truncates lower-priority content to stay within budget:

bash
# Default budget (6000 tokens)
curl https://contox.dev/api/v2/brain?projectId=proj_abc123 \
  -H "Authorization: Bearer contox_sk_yourkey"

# Larger budget for detailed context
curl "https://contox.dev/api/v2/brain?projectId=proj_abc123&tokenBudget=12000" \
  -H "Authorization: Bearer contox_sk_yourkey"

Response

Headers

HeaderDescription
ETagCache identifier for the current brain state
Content-Typeapplication/json

Body

json
{
  "markdown": "# Project Memory\n\n## Architecture\n...",
  "metadata": {
    "itemCount": 42,
    "tokenEstimate": 5847,
    "assembledAt": "2025-01-20T14:00:00Z",
    "schemaKeys": ["root/architecture", "root/conventions", "root/implementation"]
  }
}
FieldTypeDescription
markdownstringThe assembled brain document in markdown format
metadata.itemCountnumberNumber of memory items included
metadata.tokenEstimatenumberEstimated token count of the document
metadata.assembledAtstringISO timestamp of assembly
metadata.schemaKeysarraySchema keys of included sections

ETag caching

The brain endpoint supports ETag-based caching to avoid unnecessary data transfer. Use the If-None-Match header with the ETag from a previous response:

bash
# First request
curl -i https://contox.dev/api/v2/brain?projectId=proj_abc123 \
  -H "Authorization: Bearer contox_sk_yourkey"

# Response includes ETag
# ETag: "brain-abc123-1705312200"

# Subsequent request with ETag
curl -i https://contox.dev/api/v2/brain?projectId=proj_abc123 \
  -H "Authorization: Bearer contox_sk_yourkey" \
  -H "If-None-Match: \"brain-abc123-1705312200\""

# Returns 304 Not Modified if brain hasn't changed

A 304 Not Modified response means the brain has not changed since the last request, and your cached version is still valid.

Brain assembly

The brain document is assembled from approved memory items organized by schema key. Items are grouped into sections and sorted by section order:

  1. Layer 0 -- Project metadata and configuration
  2. Layer 1 -- Architecture, conventions, and tech stack (Tier 1 items)
  3. Layer 2 -- Implementation journal, decisions, and bugs (Tier 2 items)
  4. Layer 3 -- Todos, session logs, and supplementary data (Tier 3 items)

Higher layers are included first. If the token budget is reached before all items are included, lower-priority items are truncated.

See Brain Assembly Guide for a detailed explanation of the assembly process.

Example usage in MCP server

javascript
async function loadBrain(projectId, apiKey) {
  const response = await fetch(
    `https://contox.dev/api/v2/brain?projectId=${projectId}&tokenBudget=8000`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'If-None-Match': cachedETag || '',
      },
    }
  );

  if (response.status === 304) {
    return cachedBrain; // Use cached version
  }

  cachedETag = response.headers.get('ETag');
  const data = await response.json();
  cachedBrain = data.markdown;

  return data.markdown;
}

Next steps

Previous
V2 Ingest
Next
V2 Sessions