> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routemcp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the RouteMCP unified API

The RouteMCP API provides a unified interface to read and write data across multiple CRM and Accounting providers. Authenticate with your API key and interact with CRM records (contacts, leads, deals, meetings, companies, notes, tasks, activities) and accounting records (invoices, bills, contacts, accounts, payments, journal entries, items, financial reports, and more) through a single, consistent API — regardless of which provider your users have connected.

## Base URL

```
https://api.routemcp.io/api/v1
```

## Authentication

All API requests require an API key passed in the `Authorization` header as a Bearer token:

```bash theme={null}
curl https://api.routemcp.io/api/v1/crm/contact?provider=hubspot \
  -H "Authorization: Bearer sk_live_your_api_key"
```

See the [Authentication Guide](/guides/authentication) for details on obtaining and managing API keys.

## Endpoints

The API exposes five groups of endpoints:

### CRM Resources

CRUD operations on CRM resources. The same endpoints work across all connected providers — Salesforce, HubSpot, Zoho CRM, Pipedrive, LeadConnector, Monday CRM, and more.

| Method   | Endpoint               | Description                           |
| -------- | ---------------------- | ------------------------------------- |
| `GET`    | `/crm/{resource}`      | List records (with cursor pagination) |
| `POST`   | `/crm/{resource}`      | Create a record                       |
| `GET`    | `/crm/{resource}/{id}` | Get a single record                   |
| `PUT`    | `/crm/{resource}/{id}` | Replace a record                      |
| `PATCH`  | `/crm/{resource}/{id}` | Update specific fields                |
| `DELETE` | `/crm/{resource}/{id}` | Delete a record                       |

**Writable resources:** `contact`, `lead`, `deal`, `meeting`, `company`, `note`, `task`, `activity`, `appointment`

**Read-only resources:** `owner`, `pipeline` — support `GET /{resource}` (list) and `GET /{resource}/{id}` (get) only. These are managed by the provider and cannot be created, updated, or deleted through this API.

### Accounting Resources

CRUD operations on accounting resources. The same endpoints work across all connected providers (currently QuickBooks Online).

| Method   | Endpoint                      | Description                                                                        |
| -------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| `GET`    | `/accounting/{resource}`      | List records (with cursor pagination + `created_after` / `created_before` filters) |
| `POST`   | `/accounting/{resource}`      | Create a record                                                                    |
| `GET`    | `/accounting/{resource}/{id}` | Get a single record                                                                |
| `PUT`    | `/accounting/{resource}/{id}` | Replace a record                                                                   |
| `PATCH`  | `/accounting/{resource}/{id}` | Update specific fields                                                             |
| `DELETE` | `/accounting/{resource}/{id}` | Delete a record                                                                    |

**Writable resources:** `invoice`, `contact`, `account`, `payment`, `tax_rate`, `journal_entry`, `expense`, `purchase_order`, `sales_order`, `credit_note`, `vendor_credit`, `item`, `tracking_category`, `accounting_period`, `payment_method`, `payment_term`, `employee`, `project`, `attachment`, `expense_report`, `item_fulfillment`

**Update-only:** `company_info` — singleton per realm; cannot be created or deleted.

**Read-only resources:** `address`, `phone_number`, `balance_sheet`, `income_statement`, `cash_flow_statement`, `general_ledger_transaction`, `transaction`, `bank_feed_account`, `bank_feed_transaction` — list and get only.

The `created_after` / `created_before` query params filter by record creation timestamp on regular resources. On the three financial reports (`balance_sheet`, `income_statement`, `cash_flow_statement`) they are reinterpreted as the report's period bounds — `created_before` on `balance_sheet` is the as-of snapshot date.

### Field Mappings

| Method | Endpoint          | Description                                                     |
| ------ | ----------------- | --------------------------------------------------------------- |
| `GET`  | `/field-mappings` | List field mappings for a provider (with org overrides applied) |

### Connect

| Method | Endpoint         | Description                                            |
| ------ | ---------------- | ------------------------------------------------------ |
| `POST` | `/connect/token` | Create a connect session token for the embedded widget |

### MCP Workspaces

Manage workspaces — router-mode MCP servers scoped to an optional set of integrations. These endpoints are authenticated with your **API key** (`Authorization: Bearer sk_live_*` / `sk_test_*`). The environment is derived from the key — `sk_test_*` keys operate on sandbox, `sk_live_*` on production — so it is never sent in the request.

Toolkit and database connectors (GitHub, Gmail, Notion, Jira, PostgreSQL) are not unified REST resources like `/crm` or `/accounting` — they are accessed through the MCP runtime (`/mcp/{workspaceId}`) and the HTTP chat endpoint (`/mcp/{workspaceId}/chat`), scoped by the workspace's integrations.

| Method   | Endpoint               | Description                                                                 |
| -------- | ---------------------- | --------------------------------------------------------------------------- |
| `GET`    | `/mcp/workspaces`      | List workspaces for the key's environment (offset pagination, newest first) |
| `POST`   | `/mcp/workspaces`      | Create a workspace                                                          |
| `PATCH`  | `/mcp/workspaces/{id}` | Update a workspace's name and/or integrations                               |
| `DELETE` | `/mcp/workspaces/{id}` | Archive a workspace                                                         |

#### `GET /mcp/workspaces`

Query parameters:

| Parameter | Type    | Default | Validation |
| --------- | ------- | ------- | ---------- |
| `page`    | integer | `1`     | Min `1`    |
| `limit`   | integer | `20`    | `1`–`100`  |

```bash theme={null}
curl "https://api.routemcp.io/api/v1/mcp/workspaces?page=1&limit=20" \
  -H "Authorization: Bearer sk_test_your_api_key"
```

Returns a paginated envelope:

```json theme={null}
{
  "data": [
    {
      "id": "0191e6a2-...",
      "name": "Support Bot",
      "mode": "router",
      "environment": "sandbox",
      "toolkitFilter": ["github", "gmail"],
      "status": "active",
      "createdAt": "2026-05-29T10:00:00.000Z",
      "updatedAt": "2026-05-29T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 }
}
```

#### `POST /mcp/workspaces`

Request body. The environment is taken from the API key, so it is not part of the body.

| Field          | Type      | Required | Validation                                                                               |
| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------- |
| `name`         | string    | yes      | Length `1`–`100`                                                                         |
| `integrations` | string\[] | no       | Toolkit slugs (e.g. `github`, `gmail`). Omit or pass `[]` to expose **all** integrations |

```bash theme={null}
curl -X POST https://api.routemcp.io/api/v1/mcp/workspaces \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support Bot", "integrations": ["github", "gmail"] }'
```

#### `PATCH /mcp/workspaces/{id}`

Partial update — send only the fields you want to change. The environment is key-derived and cannot be changed here.

| Field          | Type      | Required | Validation                                                                     |
| -------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `name`         | string    | no       | Length `1`–`100`                                                               |
| `integrations` | string\[] | no       | Toolkit slugs. Pass `[]` to reset the workspace to expose **all** integrations |

```bash theme={null}
curl -X PATCH https://api.routemcp.io/api/v1/mcp/workspaces/0191e6a2-... \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed Bot", "integrations": ["github"] }'
```

#### `DELETE /mcp/workspaces/{id}`

Archives the workspace (soft delete) and responds with `204 No Content`. The `{id}` path parameter must be a valid UUID.

```bash theme={null}
curl -X DELETE https://api.routemcp.io/api/v1/mcp/workspaces/0191e6a2-... \
  -H "Authorization: Bearer sk_test_your_api_key"
```

A request for a missing workspace, or for a server that is not a workspace (non-`router` mode), returns `404 Not Found`. Invalid request bodies return `422 Unprocessable Entity` with per-field validation messages.

### HTTP Streaming Chat

| Method | Endpoint                  | Description                                                          |
| ------ | ------------------------- | -------------------------------------------------------------------- |
| `POST` | `/mcp/{workspaceId}/chat` | Send a message and stream the agent's response as Server-Sent Events |

### Managing session context

Each chat session supports a **stored context** — a free-text string (up to 8 000 characters) that is encrypted at rest and automatically prepended to the agent's system prompt on every turn of the session. Use these endpoints to set, read, or remove that context out-of-band (e.g. from your backend before the user's first message).

| Method   | Endpoint                             | Description                                                |
| -------- | ------------------------------------ | ---------------------------------------------------------- |
| `PUT`    | `/chat-sessions/{sessionId}/context` | Upsert the stored context for a session                    |
| `GET`    | `/chat-sessions/{sessionId}/context` | Read the stored context (returns `null` fields if not set) |
| `DELETE` | `/chat-sessions/{sessionId}/context` | Delete the stored context (idempotent, responds `204`)     |

`sessionId` is the same UUID you pass as `x-session-id` on each chat call. All three endpoints authenticate with `Authorization: Bearer <API_KEY>`.

```bash theme={null}
SID=019e6dd6-aafd-7c16-bea4-5585ad3c85e9

# Set context before the first chat turn
curl -X PUT "https://api.routemcp.io/api/v1/chat-sessions/$SID/context" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"context":"My email signature is:\nJane Doe, Head of Support"}'

# Read the stored context
curl "https://api.routemcp.io/api/v1/chat-sessions/$SID/context" \
  -H "Authorization: Bearer <API_KEY>"

# Remove the stored context
curl -X DELETE "https://api.routemcp.io/api/v1/chat-sessions/$SID/context" \
  -H "Authorization: Bearer <API_KEY>"
```

The inline `context` field on `POST /mcp/{workspaceId}/chat` writes the same value — these CRUD endpoints let you manage it without sending a chat message.

## Response Format

All responses follow a consistent envelope:

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Contacts retrieved",
  "data": { ... }
}
```

Error responses:

```json theme={null}
{
  "success": false,
  "statusCode": 404,
  "message": "Contact does not exist",
  "code": "CONTACT_NOT_FOUND"
}
```

## Pagination

List endpoints use cursor-based pagination:

```bash theme={null}
GET /api/v1/crm/contact?provider=hubspot&limit=50
```

| Parameter  | Type    | Default | Description                                                                                |
| ---------- | ------- | ------- | ------------------------------------------------------------------------------------------ |
| `provider` | string  | -       | Provider slug (e.g. `hubspot`, `zoho-crm`). Omit to fan out across all connected providers |
| `cursor`   | string  | -       | Cursor from previous response's `pagination.cursor`                                        |
| `limit`    | integer | 25      | Items per page (max 100)                                                                   |

Response pagination metadata:

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "OK",
  "data": {
    "data": [...],
    "pagination": {
      "cursor": "eyJpZCI6...",
      "hasMore": true,
      "limit": 25
    }
  }
}
```

## API Key Types

| Prefix     | Environment | Description                        |
| ---------- | ----------- | ---------------------------------- |
| `sk_live_` | Production  | Real data from connected providers |
| `sk_test_` | Sandbox     | Test data, safe for development    |