API Overview

The Coherence API allows you to build custom integrations, automate workflows, and extend the platform's capabilities.

Getting Started

Base URL

All API requests use the following base URL:

https://api.getcoherence.io/v1

Authentication

Every request requires authentication via API key or OAuth token.

Learn about Authentication →

Quick Example

Fetch all contacts:

curl -X GET "https://api.getcoherence.io/v1/modules/contacts/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "rec_abc123",
      "name": "John Smith",
      "email": "[email protected]",
      "company": "Acme Corp",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25
  }
}

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.). Each module has its own endpoint:

/v1/modules/{module_slug}/records

Records

Records are individual entries in a module. Each record has a unique ID.

Fields

Fields define the data stored on records. Field types include text, number, date, reference, and more.

API Resources

Records

Method	Endpoint	Description
GET	`/modules/{module}/records`	List records
GET	`/modules/{module}/records/{id}`	Get a record
POST	`/modules/{module}/records`	Create a record
PATCH	`/modules/{module}/records/{id}`	Update a record
DELETE	`/modules/{module}/records/{id}`	Delete a record

Modules

Method	Endpoint	Description
GET	`/modules`	List all modules
GET	`/modules/{module}`	Get module schema
GET	`/modules/{module}/fields`	List module fields

Users

Method	Endpoint	Description
GET	`/users`	List workspace users
GET	`/users/me`	Get current user

Search

Method	Endpoint	Description
POST	`/search`	Search across modules

Request Format

Headers

Required headers for all requests:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

POST and PATCH requests use JSON:

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "status": "active"
}

Query Parameters

Common query parameters:

Parameter	Description	Example
`page`	Page number	`?page=2`
`per_page`	Results per page (max 100)	`?per_page=50`
`sort`	Sort field and direction	`?sort=-created_at`
`fields`	Fields to include	`?fields=name,email`
`filter`	Filter conditions	`?filter[status]=active`

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 25
  }
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "The email field is required",
    "details": {
      "field": "email"
    }
  }
}

Rate Limiting

Limits

Standard: 1000 requests per minute
Enterprise: 5000 requests per minute

Headers

Rate limit info is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Handling Limits

When rate limited, you'll receive:

HTTP 429 Too Many Requests

Wait for the reset time before retrying.

Use bulk endpoints when creating or updating multiple records to reduce API calls.

Webhooks

Event Types

Subscribe to events:

record.created
record.updated
record.deleted
email.received
email.sent

Webhook Payload

{
  "event": "record.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "module": "contacts",
    "record_id": "rec_abc123",
    "record": { ... }
  }
}

SDKs and Libraries

Official SDKs

JavaScript/Node.js - npm install @coherence/sdk
Python - pip install coherence-sdk

Community SDKs

Check our GitHub for community-maintained libraries.

Testing

Sandbox Environment

Use our sandbox for testing:

https://sandbox.api.getcoherence.io/v1

Sandbox data is reset weekly.

Test API Key

Generate test keys in Settings > API > Test Keys.

Next: Learn about Authentication to get your API key.