{ "openapi": "3.1.0", "info": { "title": "Coherence API", "version": "1.1.0", "summary": "Public, agent-facing REST API for the Coherence workspace.", "description": "Public REST API for the Coherence platform (a unified CRM, email, calendar, and custom-module workspace operated by Brightyard, Inc.). Authenticate every request with a workspace API key created at Settings → API Keys, sent as `Authorization: Bearer sk_live_...`. This document is the canonical spec, served live at https://api.getcoherence.io/v1/openapi.json. Human reference: https://getcoherence.io/docs/api · MCP server: https://getcoherence.io/docs/mcp/overview", "termsOfService": "https://getcoherence.io/terms", "contact": { "name": "Coherence API Support", "email": "support@getcoherence.io", "url": "https://getcoherence.io/docs/api" }, "x-generated": "GENERATED FILE — do not edit by hand. Regenerate with: pnpm --filter @brightyard/module-config-service exec tsx scripts/generate-openapi-artifacts.ts", "x-generated-from": "services/module-config/src/routes/public-api-openapi.ts" }, "externalDocs": { "description": "Coherence API documentation", "url": "https://getcoherence.io/docs/api/overview" }, "servers": [ { "url": "https://api.getcoherence.io/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Meta", "description": "API metadata (this document)" }, { "name": "Identity", "description": "Confirm the workspace/user a key resolves to" }, { "name": "Modules", "description": "Module metadata and fields" }, { "name": "Records", "description": "CRUD over records in any module" }, { "name": "References", "description": "Relationship (reference) reads" }, { "name": "Search", "description": "Cross-module search" }, { "name": "Activity", "description": "Record / module / workspace activity feeds" }, { "name": "Agents", "description": "Chat with a Coherence agent (Nash)" } ], "paths": { "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "tags": ["Meta"], "summary": "Get this OpenAPI document", "description": "Returns the canonical OpenAPI 3.1 document describing this API. Unauthenticated — no API key required.", "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/me": { "get": { "operationId": "getIdentity", "tags": ["Identity"], "summary": "Identity check", "description": "Returns the user, account, and scopes the current key resolves to. Useful to confirm a key is valid and discover which workspace it operates against. Requires the `workspace:read` scope.", "responses": { "200": { "description": "Identity payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules": { "get": { "operationId": "listModules", "tags": ["Modules"], "summary": "List modules", "description": "Returns the active CRM modules (data types) in the workspace. Requires the `workspace:read` scope.", "responses": { "200": { "description": "Modules in the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "$ref": "#/components/schemas/Module" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/fields": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "listModuleFields", "tags": ["Modules"], "summary": "List fields defined on a module", "description": "Requires the `workspace:read` scope.", "responses": { "200": { "description": "Fields defined on the module", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "getModuleSchema", "tags": ["Modules"], "summary": "Get a module's full schema", "description": "Returns the module plus its fields, views, and references. Account-scoped. Requires the `workspace:read` scope.", "responses": { "200": { "description": "Module schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "module": { "type": "object", "additionalProperties": true }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "views": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "references": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/modules/{moduleSlug}/views": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "listModuleViews", "tags": ["Modules"], "summary": "List a module's views", "description": "Requires the `workspace:read` scope.", "responses": { "200": { "description": "Views defined on the module", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/modules/{moduleSlug}/records": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "listRecords", "tags": ["Records"], "summary": "List records in a module", "description": "Returns a paginated list of records. Requires the `records:read` scope.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Results per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "search", "in": "query", "description": "Free-text query within the module", "schema": { "type": "string" } }, { "name": "sortField", "in": "query", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "description": "Simple field filters, e.g. filter[status]=active,pending (comma = OR).", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "name": "advancedFilter", "in": "query", "description": "JSON-encoded advanced filter (operators + AND/OR grouping).", "schema": { "type": "string" } }, { "name": "labelIds", "in": "query", "description": "Comma-separated label IDs", "schema": { "type": "string" } }, { "name": "typeIds", "in": "query", "description": "Comma-separated type IDs", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated field slugs to include in each record's fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated record list", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createRecord", "tags": ["Records"], "summary": "Create a record", "description": "Requires the `records:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCreate" } } } }, "responses": { "201": { "description": "Created record", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/Record" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/records/{recordId}": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "getRecord", "tags": ["Records"], "summary": "Get a record by ID", "description": "Requires the `records:read` scope.", "responses": { "200": { "description": "Record payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/Record" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateRecord", "tags": ["Records"], "summary": "Update a record", "description": "Requires the `records:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordUpdate" } } } }, "responses": { "200": { "description": "Updated record", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/Record" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteRecord", "tags": ["Records"], "summary": "Delete a record (soft-delete)", "description": "Requires the `records:write` scope.", "responses": { "204": { "description": "Record deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/modules/{moduleSlug}/records/bulk": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "post": { "operationId": "bulkUpdateRecords", "tags": ["Records"], "summary": "Bulk add/remove labels and types", "description": "Add or remove labels and types across up to 100 records in one call. Requires the `records:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["recordIds"], "properties": { "recordIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "addLabelIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "removeLabelIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "addTypeIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "removeTypeIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Updated records", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/records/bulk-delete": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "post": { "operationId": "bulkDeleteRecords", "tags": ["Records"], "summary": "Bulk soft-delete records", "description": "Soft-delete up to 100 records in one call. Requires the `records:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["recordIds"], "properties": { "recordIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } } } } } }, "responses": { "200": { "description": "Count deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/references": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "listModuleReferences", "tags": ["References"], "summary": "List a module's reference fields", "description": "Requires the `records:read` scope.", "responses": { "200": { "description": "Reference fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "references": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/references/{referenceSlug}/records/{recordId}": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" }, { "name": "referenceSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "getLinkedRecordIds", "tags": ["References"], "summary": "Get linked record IDs for a reference", "description": "Requires the `records:read` scope.", "responses": { "200": { "description": "Linked record IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetRecordIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/modules/{moduleSlug}/references/{referenceSlug}/picker": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" }, { "name": "referenceSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getReferencePicker", "tags": ["References"], "summary": "Search records to link via a reference", "description": "Requires the `records:read` scope.", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Picker options", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/search": { "post": { "operationId": "search", "tags": ["Search"], "summary": "Cross-module search", "description": "Semantic + keyword search across indexed workspace content. Results are filtered to modules the key's role can view. Degrades to { results: [], total: 0, fallback: true } if the index is unavailable. Requires the `records:read` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "types": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 20, "description": "Restrict to source types, e.g. module_record, collab_doc" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "minSimilarity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "score": { "type": "number" }, "link": { "type": "string" } } } }, "total": { "type": "integer" }, "fallback": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/activity": { "get": { "operationId": "listWorkspaceActivity", "tags": ["Activity"], "summary": "Workspace-wide activity feed", "description": "Requires the `workspace:read` scope.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "activityTypes", "in": "query", "description": "Comma-separated activity types", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/activity": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" } ], "get": { "operationId": "listModuleActivity", "tags": ["Activity"], "summary": "Activity feed for a module", "description": "Requires the `workspace:read` scope.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "activityTypes", "in": "query", "description": "Comma-separated activity types", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/modules/{moduleSlug}/records/{recordId}/activity": { "parameters": [ { "$ref": "#/components/parameters/ModuleSlug" }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "listRecordActivity", "tags": ["Activity"], "summary": "Grouped activity feed for a record", "description": "Requires the `workspace:read` scope.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "groupWithinMinutes", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } ], "responses": { "200": { "description": "Grouped activity feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agents/messages": { "post": { "operationId": "chatWithAgent", "tags": ["Agents"], "summary": "Chat with a Coherence agent", "description": "Send a message to a Coherence agent (Nash by default). The agent runs its multi-step tool loop (email, reminders, outreach, records, social, landing pages) and returns its final natural-language response. Tools the agent invokes still flow through the workspace's approval system, so this cannot bypass approval gates. Requires the `agents:write` scope.\n\n**Response modes.** By default the endpoint returns a single JSON object once the run completes. To receive incremental progress, request a stream by sending `Accept: text/event-stream` (or adding `?stream=true`); the response is then a Server-Sent Events stream. Named events: `open` (`{ agentId }`), `token` (`{ text }` — a chunk of the final answer; concatenate across events), `tool_call` (`{ tool, label }`), `done` (the same object as the synchronous JSON body), and `error` (`{ message }`). Lines beginning with `:` are keepalives. Raw model reasoning and raw tool output are never streamed. Disconnecting the client aborts the run.", "parameters": [ { "name": "stream", "in": "query", "required": false, "description": "Set to `true` to receive a Server-Sent Events stream instead of a single JSON response (equivalent to sending `Accept: text/event-stream`).", "schema": { "type": "string", "enum": ["true"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 10000 }, "agentId": { "type": "string", "format": "uuid", "description": "Optional. Targets a specific agent (with its custom system prompt). Omit to use the default Nash agent." } } } } } }, "responses": { "200": { "description": "Agent response. `application/json` for the default synchronous mode; `text/event-stream` when a stream is requested via `Accept: text/event-stream` or `?stream=true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events. Each event is `event: ` + `data: `. Event names: `open`, `token`, `tool_call`, `done` (data matches AgentResponse), `error`. `:`-prefixed lines are keepalive comments." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Agent not found (when agentId is provided)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_…", "description": "Workspace API key created at Settings → API Keys. Send as `Authorization: Bearer sk_live_...`. Keys may be scoped (workspace:read, records:read, records:write, agents:write); a key with no scopes inherits the creating user's role permissions. App traffic may alternatively present a session JWT." } }, "parameters": { "ModuleSlug": { "name": "moduleSlug", "in": "path", "required": true, "description": "Module slug, e.g. contacts, companies, deals", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "RecordId": { "name": "recordId", "in": "path", "required": true, "description": "Record UUID", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "Unauthorized": { "description": "Authentication failed or missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid API key", "statusCode": 401 } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Record not found", "statusCode": 404 } } } } }, "ValidationError": { "description": "The request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "statusCode": 400, "issues": [] } } } } } }, "schemas": { "Identity": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "roleSlugs": { "type": "array", "items": { "type": "string" } }, "authMethod": { "type": "string", "enum": ["api_key", "jwt"] }, "apiKeyId": { "type": ["string", "null"] }, "scopes": { "type": ["array", "null"], "items": { "type": "string" } } } }, "Module": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Contacts" }, "slug": { "type": "string", "example": "contacts" } } }, "Field": { "type": "object", "properties": { "key": { "type": "string", "example": "email" }, "label": { "type": "string", "example": "Email" }, "type": { "type": "string", "example": "email" }, "required": { "type": "boolean" } }, "additionalProperties": true }, "Record": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "moduleId": { "type": "string", "format": "uuid" }, "moduleSlug": { "type": "string", "example": "contacts" }, "displayName": { "type": "string" }, "fields": { "type": "object", "additionalProperties": true }, "createdDateTime": { "type": "string", "format": "date-time" }, "updatedDateTime": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "RecordCreate": { "type": "object", "required": ["displayName"], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 500 }, "fields": { "type": "object", "additionalProperties": true, "description": "Field values keyed by field key." }, "ownerUserId": { "type": "string", "format": "uuid" } }, "example": { "displayName": "Jane Doe", "fields": { "email": "jane@example.com", "status": "active" } } }, "RecordUpdate": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 500 }, "fields": { "type": "object", "additionalProperties": true } } }, "AgentResponse": { "type": "object", "properties": { "response": { "type": "string", "description": "The agent's final natural-language reply" }, "success": { "type": "boolean" }, "durationMs": { "type": "integer" }, "toolCalls": { "type": "integer" }, "error": { "type": "string" } } }, "Error": { "type": "object", "description": "Standard error envelope. `code` is a machine-readable, additive-only error code: an explicit per-error override when set, otherwise derived from the HTTP status — bad_request, unauthorized, forbidden, not_found, conflict, unprocessable_entity, rate_limit_exceeded, internal_error, bad_gateway, service_unavailable, gateway_timeout. Zod validation failures use `validation_error` and include an `issues` array. `data` carries additional error context when present.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code, e.g. unauthorized, not_found, validation_error." }, "message": { "type": "string" }, "statusCode": { "type": "integer" }, "data": { "type": "object", "additionalProperties": true }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["code", "message", "statusCode"] } } } } } }