{
  "openapi": "3.1.0",
  "info": {
    "title": "Coherence API",
    "version": "1.0.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 mirrors the canonical spec served 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"
    }
  },
  "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": "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": {
    "/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" },
                    "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" },
                    "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", "maxLength": 1000 },
                  "types": {
                    "type": "array",
                    "items": { "type": "string" },
                    "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.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["message"],
                "properties": {
                  "message": { "type": "string", "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",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } }
            }
          },
          "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", "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": { "message": "Missing or invalid API key", "statusCode": 401 } }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": { "message": "Record not found", "statusCode": 404 } }
          }
        }
      },
      "ValidationError": {
        "description": "The request body failed validation.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "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": {
          "id": { "type": "string", "format": "uuid", "example": "rec_abc123" },
          "displayName": { "type": "string" },
          "fields": { "type": "object", "additionalProperties": true },
          "ownerUserId": { "type": ["string", "null"], "format": "uuid" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "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. `data` carries Boom error context; `issues` is present on Zod validation failures.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "statusCode": { "type": "integer" },
              "data": { "type": "object", "additionalProperties": true },
              "issues": {
                "type": "array",
                "items": { "type": "object", "additionalProperties": true }
              }
            },
            "required": ["message", "statusCode"]
          }
        }
      }
    }
  }
}