API and MCP

Connect with an API key

Use an API key with Cursor, Claude Code, scripts and other tools that send a header.

Get a key

A workspace admin creates a key in the app: open API and MCP in the workspace and click Create key. The key starts with bl_ and is shown once. See API keys.

Send it as a bearer token: Authorization: Bearer bl_your_key.

Cursor

Add Botlum to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "botlum": {
      "url": "https://dash.botlum.com/mcp",
      "headers": {
        "Authorization": "Bearer bl_your_key"
      }
    }
  }
}

Claude Code

claude mcp add --transport http botlum https://dash.botlum.com/mcp --header "Authorization: Bearer bl_your_key"

Claude Code can also sign in without a key: see Connect an AI assistant.

Other MCP clients

Any client that speaks MCP over streamable HTTP and can send a header works: use the URL https://dash.botlum.com/mcp and the header above. A key reads the workspace it belongs to.

Scripts and reports

The same key reads the REST API. List your workspace and projects:

curl -H "Authorization: Bearer $BOTLUM_KEY" https://dash.botlum.com/api/v1/workspaces
curl -H "Authorization: Bearer $BOTLUM_KEY" https://dash.botlum.com/api/v1/workspaces/your-workspace/projects

Visibility for a period, and the daily CSV for a spreadsheet:

curl -H "Authorization: Bearer $BOTLUM_KEY" \
  "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/overview?from=2026-10-01&to=2026-10-21"

curl -H "Authorization: Bearer $BOTLUM_KEY" -o visibility.csv \
  "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/export/visibility.csv?from=2026-10-01&to=2026-10-21"

Every endpoint is in the REST API reference.

Errors