API Reference - RouteMCP 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:

curl https://api.routemcp.io/api/v1/crm/contact?provider=hubspot \
  -H "Authorization: Bearer sk_live_your_api_key"

See the Authentication Guide 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`

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:

{
  "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

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

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.

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>.

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:

{
  "success": true,
  "statusCode": 200,
  "message": "Contacts retrieved",
  "data": { ... }
}

Error responses:

{
  "success": false,
  "statusCode": 404,
  "message": "Contact does not exist",
  "code": "CONTACT_NOT_FOUND"
}

Pagination

List endpoints use cursor-based pagination:

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:

{
  "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

​Base URL

​Authentication

​Endpoints

​CRM Resources

​Accounting Resources

​Field Mappings

​Connect

​MCP Workspaces

​GET /mcp/workspaces

​POST /mcp/workspaces

​PATCH /mcp/workspaces/{id}

​DELETE /mcp/workspaces/{id}

​HTTP Streaming Chat

​Managing session context

​Response Format

​Pagination

​API Key Types