Minolith Platform API Documentation

Base URL: https://api.minolith.io

This document covers the shared foundations of every Minolith service — authentication, rate limiting, error handling, credits, and pagination. Read this first, then dive into the service-specific docs below.

Services

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer mlth_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed with mlth_ and scoped to a single project — you'll only ever see data belonging to that project.

Getting an API Key

1. Sign up at app.minolith.io/register (14-day free trial, no card required)
2. Create a project
3. Go to API Keys in the project sidebar and generate a key
4. Copy it immediately — it's only shown once

Agent Identity (Optional)

Set the X-Minolith-Agent header to identify which agent is making the request:

X-Minolith-Agent: riley

The system resolves the header against agent definitions in the project. If the agent exists, all operations (notes, status changes, context entries) are attributed to that agent. If the header is present but the agent name doesn't match a definition, a 422 error is returned.

This header is optional for all services except Tasks, where it's required for get_my_tasks and for proper assignment/attribution.

When configuring MCP:

claude mcp add --transport http minolith https://mcp.minolith.io \
  --header "Authorization: Bearer mlth_your_api_key" \
  --header "X-Minolith-Agent: riley"

Managing Keys

• Create as many keys as you need per project (e.g. production, staging, development)
• Revoke any key instantly — requests using that key will return 401 immediately
• The first 12 characters of each key are visible in the dashboard for identification

Authentication Errors

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required. Provide a valid API key via the Authorization header: Bearer mlth_xxx",
    "docs": "https://docs.minolith.io/api/platform#authentication"
  }
}

HTTP status: 401

Rate Limiting

Every API key is limited to 100 requests per minute. Every response includes headers so you can track your usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710500000

If You Hit the Limit

You'll receive a 429 response with a Retry-After header:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 100 requests per minute exceeded. Retry after 12 seconds.",
    "retry_after": 12,
    "docs": "https://docs.minolith.io/api/platform#rate-limiting"
  }
}

Wait for the number of seconds in retry_after, then try again.

Error Responses

Every error across every service uses the same structure:

{
  "error": {
    "code": "invalid_type",
    "message": "The type 'note' is not valid. Accepted values are: rule, pattern, snippet, decision, fact, warning, event.",
    "field": "type",
    "docs": "https://docs.minolith.io/api/context#entry-types",
    "suggestion": "Did you mean 'fact'?"
  }
}

Fields

HTTP Status Codes

Handling Errors

1. Check the HTTP status code for the category
2. Read error.code to identify the specific problem
3. Check error.field to see which input to fix (if present)
4. Check error.suggestion for a recommended correction (if present)
5. Follow error.docs for full details on the relevant feature

Credits and Pricing

Minolith uses a simple pay-as-you-go credit system. 1 credit = $0.01 USD.

What's free

• All reads — GET requests never cost anything
• Context — the entire Context service is free, no limits for subscribers
• Projects — create as many as you need at no extra cost
• Updates and deletes — modifying or removing data is always free

What costs credits

Base subscription

$5/month includes 500 credits. Any usage beyond that is billed as overage at $0.01/credit. Team plans are available at $15/month (1,500 credits) and $25/month (2,500 credits).

Spending Caps

Set a monthly cap in the dashboard (Usage page) to prevent unexpected charges. If a write would exceed your cap, you'll get a 402 response:

{
  "error": {
    "code": "spending_cap_exceeded",
    "message": "This action would exceed your monthly spending cap of 500 credits. Current usage: 498 credits. This action costs 1 credit. Increase your cap in the dashboard or wait for the next billing period.",
    "docs": "https://docs.minolith.io/api/platform#spending-caps",
    "current_usage": 498,
    "cap": 500,
    "action_cost": 1
  }
}

Pagination

All list endpoints use cursor-based pagination. Pass limit to control page size (default 20, max 100) and cursor to fetch the next page.

Response Format

{
  "data": [
    { "id": "ctx_abc123", "..." : "..." },
    { "id": "ctx_def456", "..." : "..." }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "ctx_def456",
    "limit": 20
  }
}

Paging Through Results

1. Make your first request: GET /v1/context/entries?limit=50
2. If has_more is true, pass next_cursor as the cursor parameter: GET /v1/context/entries?limit=50&cursor=ctx_def456
3. Repeat until has_more is false

Health Check

GET /v1/health

Returns {"status": "ok"} if the platform is running. No authentication required.

MCP Server

Minolith provides an MCP (Model Context Protocol) server so AI coding tools can access all Minolith services as native tools. It works with Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, and any other MCP-compatible client.

The MCP server uses the same API key as the REST API. All data is scoped to the key's project.

Setup

Claude Code

claude mcp add --transport http minolith https://mcp.minolith.io \
  --header "Authorization: Bearer mlth_yourkey" \
  --header "X-Minolith-Agent: your-agent-name"

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "minolith": {
      "url": "https://mcp.minolith.io",
      "headers": {
        "Authorization": "Bearer mlth_yourkey",
        "X-Minolith-Agent": "your-agent-name"
      }
    }
  }
}

Restart Cursor after saving — MCP servers only load at startup.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "minolith": {
      "serverUrl": "https://mcp.minolith.io",
      "headers": {
        "Authorization": "Bearer mlth_yourkey",
        "X-Minolith-Agent": "your-agent-name"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/mcp.json (workspace) or use the command palette → MCP: Open User Configuration (global):

{
  "servers": {
    "minolith": {
      "type": "http",
      "url": "https://mcp.minolith.io",
      "headers": {
        "Authorization": "Bearer mlth_yourkey",
        "X-Minolith-Agent": "your-agent-name"
      }
    }
  }
}

Other Clients

Point any MCP client's HTTP transport at https://mcp.minolith.io with the Authorization: Bearer mlth_yourkey and X-Minolith-Agent: your-agent-name headers.

Protocol Details

The server implements JSON-RPC 2.0 over Streamable HTTP:

• Endpoint: POST https://mcp.minolith.io/
• Content-Type: application/json
• Auth: Authorization: Bearer mlth_yourkey

Supported methods:

Server Capabilities

The server returns these capabilities during initialize:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": { "listChanged": false }
  },
  "serverInfo": {
    "name": "minolith",
    "version": "1.4.0"
  }
}

Calling a Tool

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "store_context",
    "arguments": {
      "type": "rule",
      "title": "Example rule",
      "body": "Rule details..."
    }
  }
}

Error Handling

Tool errors come back as normal tool results with isError: true — the agent sees the error message and can react to it.

Protocol errors (bad JSON, unknown method) use standard JSON-RPC error codes:

Available Tools

Each service exposes its own set of tools. See the individual service docs for full schemas and examples.

ID Format

Every resource ID is a prefixed UUID — the prefix tells you what kind of resource it is at a glance. IDs are case-sensitive and globally unique.

MCP Token Footprint

The full Minolith MCP tool set loads at 12,307 tokens. This is the cost of registering all 61 tools in your agent's context window before any calls are made.

For context-constrained agents, this is roughly 1.2% of a 1M-token window or 6.2% of a 200K-token window. The token cost is fixed regardless of how many tools are actually used during a session — tools are registered once at connection time.

MCP Tool Selection

By default, all 61 tools are returned in tools/list when your agent connects. You can reduce the token footprint by configuring which tools load.

How it works

Tool selection is configured at two levels with the following priority:

1. Agent tools_allowed — if the agent definition has a non-empty tools_allowed array, only those tools (plus protected tools) are returned
2. API key mcp_tools — if the API key has a non-empty mcp_tools configuration, those tools (plus protected tools) are returned
3. Default — if neither is set, all 61 tools are returned

Agent-level configuration always overrides key-level configuration when both are set.

Protected tools

The following 12 tools are always included regardless of your selection. They cannot be deselected:

• bootstrap
• All Context service tools: store_context, get_context, update_context, delete_context, bulk_store_context, bulk_update_context, bulk_delete_context, log_event, get_recent_events, list_tags, list_scopes

tools/call is unaffected

Tool selection only controls what appears in tools/list. Any tool can still be called via tools/call regardless of the selection — this is purely a token optimisation, not a security boundary.

Configuration

Configure via the dashboard:

• API keys: Edit an API key from your project's API Keys page and use the tool picker
• Agents: Edit an agent definition and use the MCP Tools Allowed picker

Or via the API/MCP:

• Agent definitions: Set the tools_allowed field to a JSON array of tool names
• API keys: Set the mcp_tools field (database column, no REST endpoint yet)