Documentation

Diameter is an AI-native workspace. Bring your own agent — connect any AI to your workspace via our APIs. We provide the context, you provide the intelligence.

• REST API — read and write tasks, artifacts, threads, and more
• Real-Time Subscribe — WebSocket connection for live workspace events
• CLI (di) — manage your workspace from the terminal
• MCP Server (diameter-mcp) — give AI agents like Claude full access to your workspace context

Quick Start

Get up and running with Diameter in five minutes.

1. Create your account

Sign up at diameter.app/signup with your invite code. You'll need to verify your email before continuing.

2. Generate an API token

In the web app, go to your personal space (the ~ space) and open Settings. Under API Tokens, create a new token. Copy it — you'll need it for the CLI and MCP server.

3. Install the CLI

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install.sh | sh

Or install via npm: npm install -g @diameter/cli

4. Connect Claude to your workspace

For Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

For Claude Code, add to your .claude/settings.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

5. Try it out

Ask Claude to interact with your workspace:

• "List my spaces"
• "Create a new document in my personal space about project ideas"
• "What's the context of my workspace?"
• "Create a task to review the Q1 report"

Troubleshooting

Getting Started

Install the CLI

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install.sh | sh

Or install via npm:

npm install -g @diameter/cli

Log in

Authenticate by opening a browser-based login flow:

di login --url https://diameter.app

Verify

Confirm your session is active:

di whoami

Configure Claude Desktop for MCP

Add the Diameter MCP server to your claude_desktop_config.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

Configure Claude Code for MCP

Add the Diameter MCP server to your .claude/settings.json or use claude mcp add:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

Generate an API token in the Diameter web app under Settings.

REST API

All endpoints require a Bearer token with appropriate scopes. Base URL: https://api.diameter.app

curl https://api.diameter.app/v1/tasks \
  -H "Authorization: Bearer slp_your_token_here"

Endpoints

Creating Documents

Create a document artifact with content populated — the document is immediately editable in the workspace with full collaborative editing support.

curl -X POST https://api.diameter.app/v1/artifacts \
  -H "Authorization: Bearer slp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "spc_xxx",
    "type": "document",
    "title": "Meeting Notes",
    "content": "# Summary\n\nKey decisions from today..."
  }'

The content field accepts plain text or markdown. The server generates the collaborative editing state automatically — no WebSocket connection required.

Context Endpoints

Structured summaries designed for AI consumption — everything an agent needs in one call.

Authentication

Generate an API token in the web app under Settings. Tokens use the slp_ prefix and support scoped access.

Available scopes: spaces:read spaces:write tasks:read tasks:write artifacts:read artifacts:write threads:read threads:write events:read links:read links:write memories:read memories:write

Real-Time Subscribe

Connect via WebSocket to receive workspace events in real-time. Your agent maintains one persistent connection and sends context updates over the wire.

Connect

ws://api.diameter.app/v1/subscribe?token=slp_your_token_here

Token must have the events:read scope.

Server Messages

On connect, you receive your accessible spaces:

{
  "type": "connected",
  "userId": "usr_xxx",
  "spaces": [
    { "id": "spc_xxx", "name": "My Project", "slug": "my-project", "role": "owner" }
  ]
}

When something changes, you receive an event:

{
  "type": "event",
  "event": {
    "id": "evt_xxx",
    "spaceId": "spc_xxx",
    "spaceName": "My Project",
    "type": "created",
    "entityType": "task",
    "entityId": "tsk_xxx",
    "agentName": "Dan",
    "data": { "title": "New task" },
    "createdAt": "2026-02-20T13:55:29.376Z"
  }
}

Client Messages

Tell the server what you're focused on to filter events:

// Focus on a space (only receive events from this space)
{ "type": "focus", "spaceId": "spc_xxx" }

// Focus on a specific entity
{ "type": "focus", "spaceId": "spc_xxx", "entityType": "task", "entityId": "tsk_xxx" }

// Remove focus (receive all events)
{ "type": "unfocus" }

// Keep connection alive (5 min idle timeout)
{ "type": "ping" }

Event Types

Example

const ws = new WebSocket(
  "ws://api.diameter.app/v1/subscribe?token=slp_xxx"
);

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);

  if (msg.type === "connected") {
    // Focus on a specific space
    ws.send(JSON.stringify({
      type: "focus",
      spaceId: msg.spaces[0].id
    }));
  }

  if (msg.type === "event") {
    // React to workspace changes
    console.log(msg.event.agentName, msg.event.type, msg.event.entityType);
  }
};

// Keep alive
setInterval(() => {
  ws.send(JSON.stringify({ type: "ping" }));
}, 120_000);

Memory

Give your agent persistent, semantic memory scoped to each workspace. Store facts, search by meaning, and extract knowledge from conversations — all through the API.

Memory is bring-your-own-key. Configure your preferred embedding provider per space — OpenAI, Voyage AI, Cohere, or Ollama (local).

Configure a Provider

Before using memory, set up an embedding provider for your space:

curl -X PUT https://api.diameter.app/v1/memories/config \
  -H "Authorization: Bearer slp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "spc_abc",
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "sk-your-openai-key",
    "dimensions": 1536
  }'

Available Providers

GET /v1/memories/providers

# Returns all supported providers and models:
# - OpenAI: text-embedding-3-small (1536d), text-embedding-3-large (3072d)
# - Voyage AI: voyage-3-lite (512d), voyage-3 (1024d)
# - Cohere: embed-english-v3.0 (1024d), embed-multilingual-v3.0 (1024d)
# - Ollama: nomic-embed-text (768d), mxbai-embed-large (1024d)

Store a Memory

curl -X POST https://api.diameter.app/v1/memories \
  -H "Authorization: Bearer slp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "spc_abc",
    "content": "User prefers dark mode and compact layouts",
    "category": "preference"
  }'

# Categories: preference, decision, context, instruction, fact

Search Memories

Semantic search — find memories by meaning, not just keywords:

curl "https://api.diameter.app/v1/memories/search?spaceId=spc_abc&q=what+theme+does+the+user+like" \
  -H "Authorization: Bearer slp_your_token"

# Returns memories ranked by semantic similarity, each with a score (0-1)

Ingest from Conversations

Feed raw text and let Diameter extract discrete facts automatically. Duplicate facts (> 92% similarity) are skipped:

curl -X POST https://api.diameter.app/v1/memories/ingest \
  -H "Authorization: Bearer slp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "spc_abc",
    "text": "The client wants the dashboard redesigned by March. They prefer minimal UI with lots of whitespace. Budget is $15k."
  }'

# Extracts and stores:
# - "Client wants dashboard redesigned by March" (context)
# - "Client prefers minimal UI with lots of whitespace" (preference)
# - "Project budget is $15k" (fact)

Memory Profile

Get an aggregated view of all memories for a space, grouped by category:

GET /v1/memories/profile?spaceId=spc_abc

# Returns: { facts: { preference: [...], decision: [...], context: [...] }, count: 42 }

All Endpoints

Scopes

Memory endpoints require memories:read and/or memories:write scopes on your API token. New tokens include these by default.

CLI Reference

The di CLI gives you full access to your Diameter workspace from the terminal. All commands support --help for detailed usage.

Auth

Spaces

Tasks

Artifacts

Threads

Context

Global flags: --json for raw output, --api-url and --token for overriding config.

MCP Server Setup

The Diameter MCP server gives Claude (or any MCP-compatible agent) direct access to your workspace. It uses stdio transport, the standard mechanism for local MCP servers.

The server requires two environment variables:

• DIAMETER_API_TOKEN — your personal API token
• DIAMETER_API_URL — URL of your Diameter instance
• DIAMETER_COLLAB_URL — WebSocket URL of the collaboration server (optional, enables real-time editing)

See Getting Started for full configuration instructions for Claude Desktop and Claude Code.

MCP Tools Reference

These tools are available to any MCP-connected agent. Each tool maps to a Diameter API operation.

Spaces

Tasks

Artifacts

Threads

Links

Context

Events

Agents

Assets

Themes

Real-Time Editing

Requires DIAMETER_COLLAB_URL. These tools connect via Y.js for live collaborative editing.

MCP Resources

MCP resources provide read-only context that agents can pull into their working memory. These URIs are available via the standard MCP resource protocol.

• diameter://spaces — List of workspaces
• diameter://whoami — Current identity
• diameter://context-guide — Guide for using context tools
• diameter://space/{id} — Specific space context
• diameter://task/{id} — Specific task context
• diameter://artifact/{id} — Specific artifact context