API Overview

The Coherence API lets you read and write workspace data and delegate work to your Coherence agent (Nash). The machine-readable OpenAPI 3.1 spec is published at https://getcoherence.io/openapi.json.

Getting Started

Base URL

https://api.getcoherence.io/v1

Authentication

Every request requires a workspace API key sent as Authorization: Bearer sk_live_....

Learn about Authentication →

Quick Example

List contacts:

curl -X GET "https://api.getcoherence.io/v1/modules/contacts/records" \
  -H "Authorization: Bearer sk_live_..."

{
  "records": [
    {
      "recordId": "5f0c2f8a-9a1e-4a9b-8d8f-2f7f4f3f9d10",
      "displayName": "John Smith",
      "fields": { "email": "[email protected]", "company": "Acme Corp" }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

Endpoints

This is the complete public API surface. Richer operations — sending email, creating reminders, drafting and scheduling outreach, posting to social — run through the agent via POST /agents/messages, governed by your workspace's approval rules.

Core Concepts

Workspaces

Your workspace contains all your data. API keys are scoped to a single workspace.

Modules

Modules are your data types (Contacts, Deals, etc.). Records live under a module:

/modules/{moduleSlug}/records

Records

Records are individual entries in a module. Each has a UUID recordId, a displayName, and a fields object keyed by field slug.

Request & Response

Headers

Authorization: Bearer sk_live_...
Content-Type: application/json

List query parameters

Creating a record

curl -X POST "https://api.getcoherence.io/v1/modules/contacts/records" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Jane Doe",
    "fields": { "email": "[email protected]", "status": "active" }
  }'

displayName is required; fields and ownerUserId are optional.

Response envelopes

{ "modules": [ ... ] }
{ "fields": [ ... ] }
{ "records": [ ... ], "total": 100, "page": 1, "pageSize": 25 }
{ "record": { ... } }

Error envelope

{
  "error": {
    "code": "not_found",
    "message": "Record not found",
    "statusCode": 404
  }
}

Validation failures carry code: "validation_error" and an issues array describing the failed fields. See Errors for the full code catalog.

Talking to the agent

curl -X POST "https://api.getcoherence.io/v1/agents/messages" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "Draft a follow-up email to the leads I created this week." }'

{ "response": "...", "success": true, "durationMs": 8421, "toolCalls": 3 }

Pass an optional agentId to target a specific agent with its own system prompt.

MCP

For MCP-compatible clients (Claude Desktop, Cursor, Cline, Windsurf, VS Code, ChatGPT), install the official MCP server:

npx @coherenceos/mcp-server

It wraps this API plus the Nash agent. See MCP Server Overview.

TypeScript SDK

For TypeScript and JavaScript, use the official SDK instead of hand-rolling fetch calls:

npm install @coherenceos/sdk

It wraps this entire API — records, modules, search, activity, and agents (including SSE streaming) — with full types, zero runtime dependencies, and ESM + CommonJS builds.

import { CoherenceClient } from '@coherenceos/sdk';
 
const coherence = new CoherenceClient({ apiKey: process.env.COHERENCE_API_KEY! });
const { records } = await coherence.records.list('contacts', { pageSize: 50 });

TypeScript SDK reference →

Next: Learn about Authentication to create your API key.