{ "openapi": "3.0.0", "info": { "description": "REST API for accessing and managing your Nex data. Generate API keys from the Nex web UI and use them to authenticate requests.", "title": "Nex Developer API", "contact": {}, "version": "1.0" }, "paths": { "/v1/lists/{id}": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Add record to a list or update its list-specific attributes if it already exists", "tags": [ "Lists" ], "summary": "Upsert a list member", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateListMemberRequest" } } }, "description": "List member upsert request", "required": true }, "responses": { "200": { "description": "Created or updated list member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateListMemberResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "upsertListMember" }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Add record to a list", "tags": [ "Lists" ], "summary": "Add a list member", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateListMemberRequest" } } }, "description": "List member creation request", "required": true }, "responses": { "200": { "description": "Created list member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateListMemberResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "addListMember" }, "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list definition by its ID", "tags": [ "Lists" ], "summary": "Get a list by ID", "operationId": "getList", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ObjectResponse" } } } }, "400": { "description": "Bad request - Invalid list ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes a list definition", "tags": [ "Lists" ], "summary": "Delete a list", "operationId": "deleteList", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List deleted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/lists/{id}/records": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves all records that belong to a specific list with pagination", "tags": [ "Lists" ], "summary": "Get records from a specific list", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListRecordsRequest" } } }, "description": "List records request with pagination options", "required": true }, "responses": { "200": { "description": "List of records with pagination info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListRecordsResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "getListRecords" } }, "/v1/lists/{id}/records/{record_id}": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates list-specific attributes for a record that belongs to a list", "tags": [ "Lists" ], "summary": "Update a record within a list", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateListRecordRequest" } } }, "description": "List record update request", "required": true }, "responses": { "200": { "description": "Updated list record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateListRecordResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List or record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "updateListRecord" }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Removes a record from a list without deleting the record itself", "tags": [ "Lists" ], "summary": "Remove a record from a list", "operationId": "removeRecordFromList", "parameters": [ { "description": "List ID", "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Record removed from list" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "List or record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/objects": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves all entity definitions (objects) available in the workspace", "tags": [ "Objects" ], "summary": "List all objects in the workspace", "parameters": [ { "description": "Include attribute definitions for each object", "name": "include_attributes", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListObjectsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "listObjects" }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new object definition (entity type) in the workspace", "tags": [ "Schema" ], "summary": "Create an object definition", "operationId": "createObjectDefinition", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateObjectRequest" } } }, "description": "Object definition to create", "required": true }, "responses": { "200": { "description": "Created object definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ObjectResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/objects/{slug}": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new record or updates an existing one based on a matching attribute", "tags": [ "Records" ], "summary": "Create or update a record", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpsertRecordRequest" } } }, "description": "Upsert record request with matching attribute and data", "required": true }, "responses": { "200": { "description": "Created or updated record with all attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpsertRecordResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object type not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "upsertRecord" }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new record for a specific object type with the provided attributes", "tags": [ "Records" ], "summary": "Create a new record", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateRecordRequest" } } }, "description": "Record attributes", "required": true }, "responses": { "200": { "description": "Created record with all attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateRecordResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object type not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "createRecord" }, "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a single object definition with all its attribute definitions", "tags": [ "Schema" ], "summary": "Get an object definition", "operationId": "getObjectDefinition", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Object definition with attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ObjectResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates properties of an existing object definition", "tags": [ "Schema" ], "summary": "Update an object definition", "operationId": "updateObjectDefinition", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateObjectRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "Updated object definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ObjectResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes an object definition and all associated data", "tags": [ "Schema" ], "summary": "Delete an object definition", "operationId": "deleteObjectDefinition", "parameters": [ { "description": "Object slug", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Object definition deleted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/objects/{slug}/lists": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves all lists associated with a specific object type", "tags": [ "Lists" ], "summary": "List all lists for a specific object", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Include attribute definitions for each list", "name": "include_attributes", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of lists for the object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListObjectsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "listObjectLists" }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new list associated with a specific object type", "tags": [ "Lists" ], "summary": "Create a list", "operationId": "createList", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateListRequest" } } }, "description": "List to create", "required": true }, "responses": { "200": { "description": "Created list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ObjectResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/objects/{slug}/records": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves records (entities) for a specific object type with pagination and optional filtering", "tags": [ "Records" ], "summary": "List records for a specific object type", "parameters": [ { "description": "Object slug (e.g., 'person', 'company')", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListRecordsRequest" } } }, "description": "List records request with pagination and filtering options", "required": true }, "responses": { "200": { "description": "List of records with pagination info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListRecordsResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "listRecords" } }, "/v1/records/{record_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a single record with all its attributes", "tags": [ "Records" ], "summary": "Get a specific record by ID", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Record details with attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.RecordResponse" } } } }, "400": { "description": "Bad request - Invalid record ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "getRecord" }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates specific attributes of an existing record", "tags": [ "Records" ], "summary": "Update an existing record", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateRecordRequest" } } }, "description": "Attributes to update", "required": true }, "responses": { "200": { "description": "Updated record with all attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateRecordResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "updateRecord" }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes a record and all its associated data", "tags": [ "Records" ], "summary": "Delete a record", "operationId": "deleteRecord", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Record deleted" }, "400": { "description": "Bad request - Invalid record ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/context/text": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Add arbitrary context through unstructured text. This endpoint allows you to provide contextual information about (new or existing) people or companies. Returns an artifact_id that can be used to retrieve the processing results via GET /v1/context/artifacts/{artifact_id}.", "tags": [ "Context" ], "summary": "Add context to workspace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.AddContextTextRequest" } } }, "description": "Context text to add", "required": true }, "responses": { "200": { "description": "Context processing initiated, returns artifact_id for retrieving results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.AddContextTextResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "addContext" } }, "/v1/context/ask": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Query information using natural language. This enhanced endpoint supports three types of queries: (1) questions about specific entities (people, companies), (2) questions about multiple entities at once, and (3) generic workspace-level questions that don't reference specific entities. The AI will analyze your workspace context to provide relevant answers.", "tags": [ "Context" ], "summary": "Ask AI a question", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.QueryContextRequest" } } }, "description": "Natural language query - can be about specific entities, multiple entities, or general workspace questions", "required": true }, "responses": { "200": { "description": "Query response with relevant information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.QueryContextResponse" } } } }, "400": { "description": "Bad request - Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "queryContext" } }, "/v1/context/artifacts/{artifact_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve the results of a previously submitted ProcessText request using the artifact ID returned from the POST /v1/context/text endpoint.", "tags": [ "Context" ], "summary": "Retrieve context artifact status", "parameters": [ { "description": "Artifact ID returned from ProcessText", "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact details with processing results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.GetArtifactResponse" } } } }, "400": { "description": "Bad request - Invalid artifact ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Artifact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "getArtifact" } }, "/v1/context/list/jobs": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create an AI-powered list generation job. The AI will search your workspace and generate a list of records matching your natural language query. Use the returned job_id to poll for results.", "tags": [ "AI Lists" ], "summary": "Create an AI List", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateAIListJobRequest" } } }, "description": "AI list generation parameters", "required": true }, "responses": { "200": { "description": "Job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateAIListJobResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "createAIListJob" } }, "/v1/context/list/jobs/{job_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get the status and results of an AI list generation job. Poll this endpoint until the job status is 'completed' or 'failed'.", "tags": [ "AI Lists" ], "summary": "Get AI list job status and results", "parameters": [ { "description": "Job ID returned from create job endpoint", "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Include full attributes for each record in the results", "name": "include_attributes", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Job status and results (if completed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.GetAIListJobResponse" } } } }, "400": { "description": "Bad request - Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } }, "operationId": "getAIListJob" } }, "/v1/objects/{slug}/attributes": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new attribute definition on an object type", "tags": [ "Schema" ], "summary": "Create an attribute definition", "operationId": "createAttributeDefinition", "parameters": [ { "description": "Object slug", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateAttributeDefinitionRequest" } } }, "description": "Attribute definition to create", "required": true }, "responses": { "200": { "description": "Created attribute definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.AttributeDefinitionResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/objects/{slug}/attributes/{attr_id}": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates properties of an existing attribute definition", "tags": [ "Schema" ], "summary": "Update an attribute definition", "operationId": "updateAttributeDefinition", "parameters": [ { "description": "Object slug", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Attribute definition ID", "name": "attr_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateAttributeDefinitionRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "Updated attribute definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.AttributeDefinitionResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object or attribute not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes an attribute definition from an object type", "tags": [ "Schema" ], "summary": "Delete an attribute definition", "operationId": "deleteAttributeDefinition", "parameters": [ { "description": "Object slug", "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Attribute definition ID", "name": "attr_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attribute definition deleted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Object or attribute not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/relationships": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new relationship definition between two object types", "tags": [ "Relationships" ], "summary": "Create a relationship definition", "operationId": "createRelationshipDefinition", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateRelationshipDefinitionRequest" } } }, "description": "Relationship definition to create", "required": true }, "responses": { "200": { "description": "Created relationship definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.RelationshipDefinitionResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves all relationship definitions in the workspace", "tags": [ "Relationships" ], "summary": "List relationship definitions", "operationId": "listRelationshipDefinitions", "responses": { "200": { "description": "List of relationship definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListRelationshipDefinitionsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/relationships/{id}": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes a relationship definition", "tags": [ "Relationships" ], "summary": "Delete a relationship definition", "operationId": "deleteRelationshipDefinition", "parameters": [ { "description": "Relationship definition ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Relationship definition deleted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Relationship definition not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/records/{record_id}/relationships": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a relationship instance between two records", "tags": [ "Relationships" ], "summary": "Create a relationship instance", "operationId": "createRelationshipInstance", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateRelationshipRequest" } } }, "description": "Relationship instance to create", "required": true }, "responses": { "200": { "description": "Created relationship instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.RelationshipInstanceResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/records/{record_id}/relationships/{rel_id}": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Deletes a relationship instance between two records", "tags": [ "Relationships" ], "summary": "Delete a relationship instance", "operationId": "deleteRelationshipInstance", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "description": "Relationship instance ID", "name": "rel_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Relationship instance deleted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Relationship instance not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/records/{record_id}/timeline": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves the activity timeline for a specific record, including tasks, notes, attribute changes, and relationship events. Supports cursor-based pagination.", "tags": [ "Timeline" ], "summary": "Get record timeline", "operationId": "getRecordTimeline", "parameters": [ { "description": "Record ID", "name": "record_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "description": "Max events to return (1-100, default: 50)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timeline events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.TimelineResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/tasks": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new task, optionally associated with records and assignees", "tags": [ "Tasks" ], "summary": "Create a task", "operationId": "createTask", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateTaskRequest" } } }, "description": "Task to create", "required": true }, "responses": { "200": { "description": "Created task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.TaskResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves tasks with optional filtering by entity, assignee, completion status, and search query. Supports offset-based pagination.", "tags": [ "Tasks" ], "summary": "List tasks", "operationId": "listTasks", "parameters": [ { "description": "Filter by associated record ID", "name": "entity_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by assignee user ID", "name": "assignee_id", "in": "query", "schema": { "type": "string" } }, { "description": "Search task titles", "name": "search", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by completion status (true/false)", "name": "is_completed", "in": "query", "schema": { "type": "boolean" } }, { "description": "Max results (1-500, default: 100)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination offset (default: 0)", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListTasksResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a single task by ID", "tags": [ "Tasks" ], "summary": "Get a task", "operationId": "getTask", "parameters": [ { "description": "Task ID", "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.TaskResponse" } } } }, "400": { "description": "Bad request - Invalid task ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates properties of an existing task. All fields are optional \u2014 only provided fields are updated.", "tags": [ "Tasks" ], "summary": "Update a task", "operationId": "updateTask", "parameters": [ { "description": "Task ID", "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateTaskRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "Updated task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.TaskResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Archives (soft-deletes) a task. The task will have an archived_at timestamp set.", "tags": [ "Tasks" ], "summary": "Delete a task", "operationId": "deleteTask", "parameters": [ { "description": "Task ID", "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task archived" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notes": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new note, optionally associated with a record", "tags": [ "Notes" ], "summary": "Create a note", "operationId": "createNote", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateNoteRequest" } } }, "description": "Note to create", "required": true }, "responses": { "200": { "description": "Created note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NoteResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves notes with optional filtering by associated record. Response capped at 200 notes.", "tags": [ "Notes" ], "summary": "List notes", "operationId": "listNotes", "parameters": [ { "description": "Filter by associated record ID", "name": "entity_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of notes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListNotesResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notes/{note_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a single note by ID", "tags": [ "Notes" ], "summary": "Get a note", "operationId": "getNote", "parameters": [ { "description": "Note ID", "name": "note_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Note details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NoteResponse" } } } }, "400": { "description": "Bad request - Invalid note ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates properties of an existing note. All fields are optional.", "tags": [ "Notes" ], "summary": "Update a note", "operationId": "updateNote", "parameters": [ { "description": "Note ID", "name": "note_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateNoteRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "Updated note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NoteResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Archives (soft-deletes) a note. The note will have an archived_at timestamp set.", "tags": [ "Notes" ], "summary": "Delete a note", "operationId": "deleteNote", "parameters": [ { "description": "Note ID", "name": "note_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Note archived" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/insights": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve insights for the workspace. Supports three query modes: 'last' for a rolling time window (e.g., '30m', '2h'), 'from'/'to' for a date range (RFC3339), or no time params for most recent insights.", "tags": [ "Insights" ], "summary": "Get insights", "operationId": "getInsights", "parameters": [ { "description": "Rolling time window (e.g., '30m', '2h', '1d')", "name": "last", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Start of date range (RFC3339 UTC timestamp)", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "description": "End of date range (RFC3339 UTC timestamp)", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "description": "Maximum number of insights to return", "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of insights", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.InsightsResponse" } } } }, "400": { "description": "Bad request - Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/insights/stream": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stream real-time insights via Server-Sent Events (SSE). On connect, recent insights are replayed as 'insight.replay' events (up to 20). New insights arrive as 'insight.batch.created' events. Keepalive comments are sent every 30 seconds.", "tags": [ "Insights" ], "summary": "Stream insights (SSE)", "operationId": "streamInsights", "responses": { "200": { "description": "SSE event stream of insights", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Events: 'insight.batch.created' (real-time new insights), 'insight.replay' (historical replay on connect). Each event's data field contains a JSON object with workspace, insights array, insight_count, and emitted_at." } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/search": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Search across all records in the workspace. Results are grouped by object type (e.g., person, company). Partial results are returned if some search types fail.", "tags": [ "Search" ], "summary": "Search records", "operationId": "searchRecords", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.SearchRequest" } } }, "description": "Search query", "required": true }, "responses": { "200": { "description": "Search results grouped by type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.SearchResponse" } } } }, "400": { "description": "Bad request - Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/graph": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the full knowledge graph for the workspace, including CRM entity nodes, relationship edges, context edges (from ingested text), insight triplet edges (AI-extracted subject-predicate-object relationships), insight nodes, and insight link edges (semantic relationships between insights). Supports an optional `limit` query parameter to control the maximum number of entity nodes returned (default 1000, max 5000). Set `Accept: text/html` or `?format=html` to receive an interactive visualization.", "tags": [ "Graph" ], "summary": "Get knowledge graph", "operationId": "getGraph", "parameters": [ { "description": "Maximum number of entity nodes to return", "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 5000, "minimum": 1 } }, { "description": "Response format. Use `html` to receive an interactive graph visualization instead of JSON.", "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "html"] } } ], "responses": { "200": { "description": "Knowledge graph data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/graph.GraphResponse" } }, "text/html": { "schema": { "type": "string", "description": "Interactive HTML visualization of the knowledge graph" } } } }, "400": { "description": "Bad request - Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/integrations": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Lists all available integrations and their current connection status for the authenticated workspace. Returns each integration type/provider combination with any active connections.", "tags": [ "Integrations" ], "summary": "List integrations", "operationId": "listIntegrations", "responses": { "200": { "description": "List of integrations with connection status", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/developer.IntegrationResponse" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/integrations/{type}/{provider}/connect": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Initiates an OAuth flow to connect a third-party integration. Returns an authorization URL that the user must visit to grant access, and a connect_id used to poll for completion status.", "tags": [ "Integrations" ], "summary": "Start OAuth connection", "operationId": "startIntegrationConnect", "parameters": [ { "description": "Integration type", "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "email", "calendar", "messaging", "crm" ] } }, { "description": "Integration provider", "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "microsoft", "slack", "attio", "hubspot", "salesforce" ] } } ], "responses": { "200": { "description": "OAuth authorization URL and connect ID for polling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ConnectResponse" } } } }, "400": { "description": "Invalid integration type/provider combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "429": { "description": "Rate limit exceeded (10 requests/minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/integrations/connect/{connect_id}/status": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Polls the status of an in-progress OAuth connection. The connect_id is returned by the Start OAuth Connection endpoint. Poll this endpoint until the status changes from \"pending\" to \"connected\". The connect_id expires after 10 minutes.", "tags": [ "Integrations" ], "summary": "Get connection status", "operationId": "getConnectStatus", "parameters": [ { "description": "Connect ID returned by the start connect endpoint", "name": "connect_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current connection status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ConnectStatusResponse" } } } }, "400": { "description": "Invalid connect_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "410": { "description": "Connect ID has expired (10 minute TTL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/integrations/connections/{connection_id}": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Disconnects an active integration connection. The connection ID can be found in the list integrations response.", "tags": [ "Integrations" ], "summary": "Disconnect integration", "operationId": "disconnectIntegration", "parameters": [ { "description": "Connection ID to disconnect", "name": "connection_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully disconnected" }, "400": { "description": "Invalid connection_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/compounding/trigger": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Triggers an on-demand compounding intelligence job for the workspace. Use after onboarding, file scanning, or bulk context ingestion to run intelligence pipelines immediately instead of waiting for the next scheduled cron cycle. Supported job types: consolidation (merge near-duplicate insights), pattern_detection (discover recurring patterns), playbook_synthesis (generate playbook rules from patterns), decay_sweep (reduce confidence on stale insights), and metrics (snapshot pipeline metrics). This endpoint is asynchronous and returns a job_run_id you can poll for status.", "tags": [ "Compounding" ], "summary": "Trigger compounding job", "operationId": "triggerCompoundingJob", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/compounding.TriggerJobRequest" } } }, "description": "Job trigger request", "required": true }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/compounding.TriggerJobResponse" } } } }, "400": { "description": "Bad request - Invalid job type or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/compounding/jobs/{job_run_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the current state of a compounding job triggered through the developer API. Poll this endpoint with the job_run_id returned by the trigger endpoint until the status changes from accepted or running to completed or failed.", "tags": [ "Compounding" ], "summary": "Get compounding job status", "operationId": "getCompoundingJobStatus", "parameters": [ { "name": "job_run_id", "in": "path", "required": true, "description": "The compounding job run identifier returned by the trigger endpoint", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/compounding.JobStatusResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notifications/feed": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns recent context alerts generated by the server-side notification system. Use the `since` parameter for incremental polling.", "tags": [ "Notifications" ], "summary": "Get Notification Feed", "operationId": "getNotificationFeed", "parameters": [ { "description": "Maximum number of notifications to return (default: 20, max: 50)", "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "description": "Only return notifications after this ISO 8601 timestamp (for incremental polling)", "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "List of notification feed items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NotificationFeedResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notifications/preferences": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the current notification preferences including polling frequency, enabled notification types, and digest settings.", "tags": [ "Notifications" ], "summary": "Get Notification Preferences", "operationId": "getNotificationPreferences", "responses": { "200": { "description": "Current notification preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NotificationPreferencesResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update notification polling frequency, enabled types, or digest settings. All fields are optional.", "tags": [ "Notifications" ], "summary": "Update Notification Preferences", "operationId": "updateNotificationPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.UpdateNotificationPreferencesRequest" } } }, "description": "Notification preferences to update", "required": true }, "responses": { "200": { "description": "Updated notification preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.NotificationPreferencesResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notifications/custom": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "List all custom AI notification rules configured for the authenticated user.", "tags": [ "Notifications" ], "summary": "List Custom Notification Rules", "operationId": "listCustomNotificationRules", "responses": { "200": { "description": "List of custom notification rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.ListCustomNotificationRulesResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create a new AI-powered notification rule. Describe what you want to be notified about in natural language.", "tags": [ "Notifications" ], "summary": "Create Custom Notification Rule", "operationId": "createCustomNotificationRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CreateCustomNotificationRuleRequest" } } }, "description": "Custom notification rule to create", "required": true }, "responses": { "200": { "description": "Created custom notification rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CustomNotificationRuleResponse" } } } }, "400": { "description": "Bad request - Invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } }, "/v1/notifications/custom/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get a specific custom notification rule by ID.", "tags": [ "Notifications" ], "summary": "Get Custom Notification Rule", "operationId": "getCustomNotificationRule", "parameters": [ { "description": "Custom notification rule ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Custom notification rule details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/developer.CustomNotificationRuleResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Custom notification rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Delete a custom notification rule. This action cannot be undone.", "tags": [ "Notifications" ], "summary": "Delete Custom Notification Rule", "operationId": "deleteCustomNotificationRule", "parameters": [ { "description": "Custom notification rule ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "404": { "description": "Custom notification rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/httpx.APIError" } } } } } } } }, "servers": [ { "url": "https://app.nex.ai/api/developers" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "description": "API key for authentication (format: \"Bearer YOUR_API_KEY\")", "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "developer.AttributeDefinitionResponse": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "options": { "$ref": "#/components/schemas/developer.AttributeOptionsResponse" }, "slug": { "type": "string" }, "type": { "type": "string" } } }, "developer.AttributeOptionsResponse": { "type": "object", "properties": { "is_multi_value": { "type": "boolean" }, "is_required": { "type": "boolean" }, "is_unique": { "type": "boolean" }, "is_whole_number": { "type": "boolean" }, "select_options": { "type": "array", "items": { "$ref": "#/components/schemas/developer.SelectOptionResponse" } }, "use_raw_format": { "type": "boolean" } } }, "developer.AttributesParam": { "oneOf": [ { "type": "string", "enum": [ "all", "primary", "none" ], "description": "Simple string values for common attribute sets" }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "custom" ], "description": "Must be 'custom' when using object format" }, "slugs": { "type": "array", "items": { "type": "string" }, "description": "Array of attribute slugs to include", "minItems": 1 } }, "required": [ "mode", "slugs" ], "description": "Object format for custom attribute selection" } ], "description": "Attributes parameter supports both string values ('all', 'primary', 'none') and object format for custom selection" }, "developer.CreateListMemberRequest": { "type": "object", "properties": { "attributes": { "description": "Optional list-specific attributes", "type": "object", "additionalProperties": {} }, "parent_id": { "description": "ID of the existing record to add to the list", "type": "string" } }, "example": { "parent_id": "32417546405832961", "attributes": { "source": "website", "status": "new", "score": 85, "notes": "Qualified lead from demo request" } } }, "developer.CreateListMemberResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32417546405832962", "object_id": "32417546405832950", "type": "person", "workspace_id": "32417546405832945", "created_at": "2024-01-20T16:45:00Z", "updated_at": "2024-01-20T16:45:00Z", "attributes": { "name": { "first_name": "Sarah", "last_name": "Chen" }, "email_addresses": [ "sarah@newstartup.com" ], "job_title": "VP Engineering", "source": "website", "status": "new", "score": 85, "notes": "Qualified lead from demo request" } } }, "developer.CreateRecordRequest": { "type": "object", "required": [ "attributes" ], "properties": { "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "Can be a string (e.g., 'John Doe') or an object (e.g., {'first_name': 'John', 'last_name': 'Doe'} for Person objects).", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "additionalProperties": {} } }, "example": { "attributes": { "name": { "first_name": "John", "last_name": "Doe" }, "name (alternative)": "John Doe", "email_addresses": [ "john@example.com" ], "phone_number": { "country_code": 1, "number": "5551234567" }, "job_title": "Software Engineer", "location": { "street": "123 Main St", "city": "Boston", "region": "MA", "postal_code": "02134", "country": "US" } } } }, "developer.CreateRecordResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32710180831586561", "object_id": "32710180831586560", "type": "person", "workspace_id": "32710180831586559", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "attributes": { "name": { "first_name": "John", "last_name": "Doe" }, "email_addresses": [ "john@example.com" ], "phone_number": { "country_code": 1, "number": "5551234567" }, "job_title": "Software Engineer", "location": { "street": "123 Main St", "city": "Boston", "region": "MA", "postal_code": "02134", "country": "US" } } } }, "developer.ListObjectsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.ObjectResponse" } } }, "example": { "data": [ { "id": "123", "slug": "person", "name": "Person", "name_plural": "People", "type": "person", "description": "", "created_at": "2024-01-01T00:00:00Z", "attributes": [ { "id": "456", "slug": "name", "type": "full_name", "name": "Name", "description": "", "options": { "is_multi_value": false, "is_required": true, "is_unique": false } }, { "id": "789", "slug": "email_addresses", "type": "email", "name": "Email Addresses", "description": "", "options": { "is_multi_value": true, "is_required": false, "is_unique": true } } ] }, { "id": "456", "slug": "company", "name": "Company", "name_plural": "Companies", "type": "company", "description": "", "created_at": "2024-01-01T00:00:00Z", "attributes": [ { "id": "987", "slug": "name", "type": "text", "name": "Name", "description": "", "options": { "is_multi_value": false, "is_required": true, "is_unique": false } }, { "id": "654", "slug": "domains", "type": "domain", "name": "Domains", "description": "", "options": { "is_multi_value": true, "is_required": false, "is_unique": true } }, { "id": "321", "slug": "industries", "type": "select", "name": "Industries", "description": "", "options": { "is_multi_value": true, "is_required": false, "is_unique": false, "select_options": [ { "id": "tech", "name": "Technology" }, { "id": "finance", "name": "Financial Services" }, { "id": "healthcare", "name": "Healthcare" }, { "id": "retail", "name": "Retail" } ] } } ] } ] } }, "developer.ListRecordsRequest": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/developer.AttributesParam" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "$ref": "#/components/schemas/developer.SortParam" } }, "example": { "attributes": "all", "limit": 50, "offset": 0, "sort": { "attribute": "name", "direction": "asc" } } }, "developer.ListRecordsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.RecordResponse" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "example": { "data": [ { "id": "32414268188027655", "object_id": "32414268188027650", "type": "person", "workspace_id": "32414268188027645", "created_at": "2024-01-15T14:20:00Z", "updated_at": "2024-01-20T09:15:00Z", "attributes": { "name": { "first_name": "Alice", "last_name": "Johnson" }, "email_addresses": [ "alice@techcorp.com" ], "job_title": "Product Manager", "phone_number": { "country_code": 1, "number": "5551112222" } } }, { "id": "32414268188027656", "object_id": "32414268188027650", "type": "person", "workspace_id": "32414268188027645", "created_at": "2024-01-16T08:30:00Z", "updated_at": "2024-01-16T08:30:00Z", "attributes": { "name": { "first_name": "Bob", "last_name": "Wilson" }, "email_addresses": [ "bob@startup.io" ], "job_title": "Founder", "location": { "city": "San Francisco", "region": "CA", "country": "US" } } } ], "limit": 50, "offset": 0, "total": 247 } }, "developer.ObjectResponse": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/developer.AttributeDefinitionResponse" } }, "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "name_plural": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" } } }, "developer.RecordResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32414268188027655", "object_id": "32414268188027650", "type": "person", "workspace_id": "32414268188027645", "created_at": "2024-01-15T14:20:00Z", "updated_at": "2024-01-20T09:15:00Z", "attributes": { "name": { "first_name": "Alice", "last_name": "Johnson" }, "email_addresses": [ "alice@techcorp.com" ], "job_title": "Product Manager", "phone_number": { "country_code": 1, "number": "5551112222" }, "location": { "street": "456 Innovation Dr", "city": "Austin", "region": "TX", "postal_code": "73301", "country": "US" }, "linkedin": { "username": "alicejohnson", "url": "https://linkedin.com/in/alicejohnson" } } } }, "developer.SelectOptionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "developer.SortParam": { "type": "object", "properties": { "attribute": { "description": "attribute slug or ID", "type": "string" }, "direction": { "description": "\"asc\" or \"desc\"", "type": "string" } } }, "developer.UpdateListRecordRequest": { "type": "object", "properties": { "attributes": { "description": "Attributes to update", "type": "object", "additionalProperties": {} } }, "example": { "attributes": { "status": "qualified", "score": 92, "notes": "Had a great demo call, ready to move forward", "source": "referral" } } }, "developer.UpdateListRecordResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32417546405832962", "object_id": "32417546405832950", "type": "person", "workspace_id": "32417546405832945", "created_at": "2024-01-20T16:45:00Z", "updated_at": "2024-01-21T10:30:00Z", "attributes": { "name": { "first_name": "Sarah", "last_name": "Chen" }, "email_addresses": [ "sarah@newstartup.com" ], "job_title": "VP Engineering", "status": "qualified", "score": 92, "notes": "Had a great demo call, ready to move forward", "source": "referral" } } }, "developer.UpdateRecordRequest": { "type": "object", "properties": { "attributes": { "description": "Attributes to update", "type": "object", "additionalProperties": {} } }, "example": { "attributes": { "job_title": "Senior Engineer", "location": { "city": "Boston", "region": "MA", "country": "US" }, "phone_number": { "country_code": 1, "number": "5551234567" } } } }, "developer.UpdateRecordResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32414268188027655", "object_id": "32414268188027650", "type": "person", "workspace_id": "32414268188027645", "created_at": "2024-01-15T14:20:00Z", "updated_at": "2024-01-21T11:45:00Z", "attributes": { "name": { "first_name": "John", "last_name": "Doe" }, "email_addresses": [ "john@example.com" ], "job_title": "Senior Engineer", "phone_number": { "country_code": 1, "number": "5551234567" }, "location": { "city": "Boston", "region": "MA", "country": "US" } } } }, "developer.UpsertRecordRequest": { "type": "object", "required": [ "attributes", "matching_attribute" ], "properties": { "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "Required when creating a new record, but optional when updating an existing record that already has a name. Can be a string (e.g., 'John Doe') or an object (e.g., {'first_name': 'John', 'last_name': 'Doe'} for Person objects).", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "additionalProperties": {} }, "matching_attribute": { "description": "ID or slug of the attribute to match on", "type": "string" } }, "example": { "matching_attribute": "email_addresses", "attributes": { "name": { "first_name": "Jane", "last_name": "Smith" }, "email_addresses": [ "jane@example.com" ], "job_title": "CTO", "phone_number": { "country_code": 1, "number": "5559876543" } } } }, "developer.UpsertRecordResponse": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "string" } }, "example": { "id": "32414268188027657", "object_id": "32414268188027650", "type": "person", "workspace_id": "32414268188027645", "created_at": "2024-01-21T12:00:00Z", "updated_at": "2024-01-21T12:00:00Z", "attributes": { "name": { "first_name": "Jane", "last_name": "Smith" }, "email_addresses": [ "jane@example.com" ], "job_title": "CTO", "phone_number": { "country_code": 1, "number": "5559876543" }, "location": { "city": "San Francisco", "region": "CA", "country": "US" } } } }, "httpx.APIError": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "developer.AddContextTextRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The unstructured text containing context information about people, companies, or other entities" }, "context": { "type": "string", "description": "Optional additional context about the content (e.g., source, type of activity)" } }, "example": { "content": "Marcus Rodriguez commented: \"Would love to book a demo\"", "context": "New LinkedIn activity" } }, "developer.QueryContextRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language query - supports single entity questions (e.g., 'What's the status with techflow.io?'), multi-entity questions (e.g., 'Compare engagement levels of Acme Corp and TechFlow'), or general workspace questions (e.g., 'Which deals are most likely to close this quarter?')" } }, "example": { "query": "What's the status with techflow.io?" } }, "developer.QueryContextResponse": { "type": "object", "properties": { "answer": { "type": "string", "description": "AI-generated response to the query based on available workspace context" }, "entities_considered": { "type": "array", "description": "Entities that were analyzed to generate the answer", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Entity ID" }, "name": { "type": "string", "description": "Entity name" }, "type": { "type": "string", "description": "Entity type (PERSON, COMPANY)" }, "reason": { "type": "string", "description": "Why this entity was considered relevant" }, "insights_matched": { "type": "integer", "description": "Number of insights matched for this entity" }, "score": { "type": "number", "description": "Relevance score" } } } }, "signals_used": { "type": "array", "description": "Specific signals/insights used to generate the answer", "items": { "type": "object", "properties": { "insight_id": { "type": "integer", "description": "Insight ID" }, "entity_id": { "type": "integer", "description": "Entity ID this signal belongs to" }, "content": { "type": "string", "description": "Signal content excerpt" }, "score": { "type": "number", "description": "Relevance score" }, "type": { "type": "string", "description": "Signal type" } } } }, "metadata": { "type": "object", "description": "Query processing metadata", "properties": { "query_type": { "type": "string", "enum": [ "workspace_wide", "entity_specific" ], "description": "Whether the query was about specific entities or workspace-wide" }, "total_entities_searched": { "type": "integer", "description": "Total number of entities searched" }, "confidence": { "type": "number", "description": "Confidence score of the answer" } } } }, "example": { "answer": "Based on the available context, techflow.io appears to be a technology company. Marcus Rodriguez from techflow.io expressed interest in booking a demo on LinkedIn.", "entities_considered": [ { "id": 25339323448557880, "name": "TechFlow", "type": "COMPANY", "reason": "Direct match for techflow.io domain", "insights_matched": 3, "score": 0.95 }, { "id": 25339323448557884, "name": "Marcus Rodriguez", "type": "PERSON", "reason": "Associated with TechFlow, recent LinkedIn activity", "insights_matched": 2, "score": 0.87 } ], "signals_used": [ { "insight_id": 38485049540083710, "entity_id": 25339323448557884, "content": "Marcus Rodriguez commented on LinkedIn: Would love to book a demo", "score": 0.92, "type": "social_activity" }, { "insight_id": 38485049540083710, "entity_id": 25339323448557880, "content": "TechFlow is a SaaS platform for workflow automation", "score": 0.88, "type": "company_info" } ], "metadata": { "query_type": "entity_specific", "total_entities_searched": 156, "confidence": 0.89 } } }, "developer.AddContextTextResponse": { "type": "object", "properties": { "artifact_id": { "type": "integer", "description": "Unique identifier for the processing artifact. Use this ID to retrieve results via GET /v1/context/artifacts/{artifact_id}" } }, "example": { "artifact_id": 32710180831586560 } }, "developer.GetArtifactResponse": { "type": "object", "properties": { "operation_id": { "type": "integer", "description": "Unique identifier for the processing operation" }, "status": { "type": "string", "enum": [ "unknown", "pending", "processing", "completed", "failed" ], "description": "Current operation status" }, "result": { "type": "object", "description": "Processing results (when status is 'completed')", "properties": { "entities_extracted": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Entity type (PERSON, COMPANY, ENGAGEMENT)" }, "context_id": { "type": "integer", "description": "Internal context ID" }, "canonical_entity_id": { "type": "integer", "description": "Entity ID (if linked)" }, "properties": { "type": "object", "description": "Entity properties (name, email, job_title, domain, etc.)" }, "previous_properties": { "type": "object", "description": "Properties before this operation (for updates)" }, "is_new": { "type": "boolean", "description": "Whether entity was created in this operation" } } }, "description": "Array of extracted entities with details" }, "entities_created": { "type": "integer", "description": "Number of new entities created" }, "entities_updated": { "type": "integer", "description": "Number of existing entities updated" }, "relationships_created": { "type": "integer", "description": "Number of relationships established" }, "insights_created": { "type": "integer", "description": "Number of insights generated" }, "tasks_suggested": { "type": "integer", "description": "Number of tasks suggested" } } }, "error": { "type": "string", "description": "Error message if status is 'failed'" }, "created_at": { "type": "string", "description": "Operation creation timestamp" }, "completed_at": { "type": "string", "description": "Operation completion timestamp" } }, "example": { "operation_id": 48066188026052610, "status": "completed", "created_at": "2025-11-28T14:14:40Z", "completed_at": "2025-11-28T14:14:41Z", "result": { "entities_extracted": [ { "type": "COMPANY", "context_id": 38485049540083710, "canonical_entity_id": 25339323448557880, "properties": { "name": "Adobe", "domain": "adobe.com" }, "previous_properties": { "name": "Adobe", "domain": null }, "is_new": false }, { "type": "PERSON", "context_id": 38485049540083710, "canonical_entity_id": 25339323448557884, "properties": { "name": "John Smith", "email": "john.smith@adobe.com", "job_title": "Product Manager" }, "is_new": true } ], "entities_created": 1, "entities_updated": 1, "relationships_created": 1, "insights_created": 3, "tasks_suggested": 0 } } }, "developer.CreateAIListJobRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language query to search items (e.g., 'all companies', 'high priority contacts')" }, "object_type": { "type": "string", "description": "Type of object to search - 'contact' or 'company' (default: 'contact')" }, "limit": { "type": "integer", "description": "Number of results (default: 50, max: 100)", "default": 50 }, "include_attributes": { "type": "boolean", "description": "If true, includes all entity attribute values in response (default: false)", "default": false } }, "example": { "query": "all companies who have asked for a contract", "object_type": "company", "limit": 20, "include_attributes": true } }, "developer.CreateAIListJobResponse": { "type": "object", "properties": { "message": { "type": "object", "description": "Response wrapper", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the list generation job" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Initial job status (always 'pending')" } } } }, "example": { "message": { "job_id": "12345678901234567", "status": "pending" } } }, "developer.GetAIListJobResponse": { "type": "object", "properties": { "message": { "type": "object", "description": "Response wrapper", "properties": { "job_id": { "type": "string", "description": "The job identifier" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Current job status" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when job was created" }, "entities": { "type": "array", "description": "Array of matched entities (only when status is 'completed')", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Entity identifier" }, "name": { "type": "string", "description": "Entity primary attribute (contact name or company name)" }, "type": { "type": "string", "description": "Entity type ('contact' or 'company')" }, "reason": { "type": "string", "description": "LLM-generated explanation of why this entity matched" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Array of relevant insight snippets (up to 3)" }, "attributes": { "type": "object", "description": "Object with all attribute values (if include_attributes was true)" } } } }, "count": { "type": "integer", "description": "Number of entities returned (only when status is 'completed')" }, "query_interpretation": { "type": "string", "description": "AI-generated explanation of how the query was interpreted" }, "error": { "type": "string", "description": "Error message (only when status is 'failed')" } } } }, "example": { "message": { "job_id": "12345678901234567", "status": "completed", "created_at": "2024-01-15T10:30:00Z", "count": 2, "query_interpretation": "Finding all venture capital firms in the workspace", "entities": [ { "id": "32710180831586564", "name": "Sequoia Capital", "type": "company", "reason": "Sequoia Capital is a well-known venture capital firm", "highlights": [ "Invested in multiple portfolio companies", "Active in Series A and B funding rounds" ], "attributes": { "domains": [ "sequoiacap.com" ], "industries": [ "Venture Capital" ] } }, { "id": "32710180831586565", "name": "Andreessen Horowitz", "type": "company", "reason": "a16z is a prominent venture capital firm", "highlights": [ "Focus on technology investments" ] } ] } } }, "developer.CreateObjectRequest": { "type": "object", "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "description": "Display name for the object" }, "name_plural": { "type": "string", "description": "Plural display name" }, "slug": { "type": "string", "description": "URL-safe identifier" }, "description": { "type": "string", "description": "Description of the object type" }, "type": { "type": "string", "description": "Object type", "enum": [ "person", "company", "custom", "deal" ] } }, "example": { "name": "Project", "name_plural": "Projects", "slug": "project", "description": "Project tracker", "type": "custom" } }, "developer.UpdateObjectRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New display name" }, "name_plural": { "type": "string", "description": "New plural name" }, "description": { "type": "string", "description": "New description" } }, "example": { "name": "Updated Project", "description": "Updated description" } }, "developer.CreateAttributeDefinitionRequest": { "type": "object", "required": [ "name", "slug", "type" ], "properties": { "name": { "type": "string", "description": "Display name" }, "slug": { "type": "string", "description": "URL-safe identifier" }, "type": { "type": "string", "description": "Attribute value type", "enum": [ "text", "number", "email", "phone", "url", "date", "boolean", "currency", "location", "select", "social_profile", "domain", "full_name" ] }, "description": { "type": "string", "description": "Description" }, "options": { "$ref": "#/components/schemas/developer.CreateAttributeOptionsRequest" } }, "example": { "name": "Status", "slug": "status", "type": "select", "description": "Current status", "options": { "is_required": true, "select_options": [ { "name": "Open" }, { "name": "In Progress" }, { "name": "Done" } ] } } }, "developer.CreateAttributeOptionsRequest": { "type": "object", "properties": { "is_required": { "type": "boolean", "description": "Field is required" }, "is_unique": { "type": "boolean", "description": "Value must be unique" }, "is_multi_value": { "type": "boolean", "description": "Allow multiple values" }, "use_raw_format": { "type": "boolean", "description": "Store raw format (numbers)" }, "is_whole_number": { "type": "boolean", "description": "Number must be integer" }, "select_options": { "type": "array", "items": { "$ref": "#/components/schemas/developer.CreateSelectOptionRequest" }, "description": "Predefined choices for select fields" } } }, "developer.CreateSelectOptionRequest": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "description": "Option ID (optional on create, auto-generated if omitted)" }, "name": { "type": "string", "description": "Option display label" } } }, "developer.UpdateAttributeDefinitionRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New display name" }, "description": { "type": "string", "description": "New description" }, "options": { "$ref": "#/components/schemas/developer.UpdateAttributeOptionsRequest" } }, "example": { "name": "Updated Status", "options": { "is_required": false, "select_options": [ { "id": "existing-id", "name": "Renamed" }, { "name": "New Option" } ] } } }, "developer.UpdateAttributeOptionsRequest": { "type": "object", "properties": { "is_required": { "type": "boolean" }, "use_raw_format": { "type": "boolean" }, "is_whole_number": { "type": "boolean" }, "select_options": { "type": "array", "items": { "$ref": "#/components/schemas/developer.CreateSelectOptionRequest" }, "description": "Updated select options. Include id to update existing, omit id to create new." } } }, "developer.CreateRelationshipDefinitionRequest": { "type": "object", "required": [ "type", "entity_definition_1_id", "entity_definition_2_id" ], "properties": { "type": { "type": "string", "description": "Relationship cardinality", "enum": [ "one_to_one", "one_to_many", "many_to_many" ] }, "entity_definition_1_id": { "type": "string", "description": "First object definition ID" }, "entity_definition_2_id": { "type": "string", "description": "Second object definition ID" }, "entity_1_to_2_predicate": { "type": "string", "description": "Label for 1\u21922 direction (e.g., 'has')" }, "entity_2_to_1_predicate": { "type": "string", "description": "Label for 2\u21921 direction (e.g., 'belongs to')" } }, "example": { "type": "one_to_many", "entity_definition_1_id": "123", "entity_definition_2_id": "456", "entity_1_to_2_predicate": "has", "entity_2_to_1_predicate": "belongs to" } }, "developer.RelationshipDefinitionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "one_to_one", "one_to_many", "many_to_many" ] }, "entity_definition_1_id": { "type": "string" }, "entity_definition_2_id": { "type": "string" }, "entity_1_to_2_predicate": { "type": "string" }, "entity_2_to_1_predicate": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "id": "789", "type": "one_to_many", "entity_definition_1_id": "123", "entity_definition_2_id": "456", "entity_1_to_2_predicate": "has", "entity_2_to_1_predicate": "belongs to", "created_at": "2024-01-15T10:00:00Z" } }, "developer.ListRelationshipDefinitionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.RelationshipDefinitionResponse" } } } }, "developer.CreateRelationshipRequest": { "type": "object", "required": [ "definition_id", "entity_1_id", "entity_2_id" ], "properties": { "definition_id": { "type": "string", "description": "Relationship definition ID" }, "entity_1_id": { "type": "string", "description": "First record ID" }, "entity_2_id": { "type": "string", "description": "Second record ID" } }, "example": { "definition_id": "789", "entity_1_id": "1001", "entity_2_id": "2002" } }, "developer.RelationshipInstanceResponse": { "type": "object", "properties": { "id": { "type": "string" }, "definition_id": { "type": "string" }, "entity_1_id": { "type": "string" }, "entity_2_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "id": "5001", "definition_id": "789", "entity_1_id": "1001", "entity_2_id": "2002", "created_at": "2024-01-15T10:00:00Z" } }, "developer.CreateListRequest": { "type": "object", "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "description": "List display name" }, "name_plural": { "type": "string", "description": "Plural name" }, "slug": { "type": "string", "description": "URL-safe identifier" }, "description": { "type": "string", "description": "List description" } }, "example": { "name": "VIP Contacts", "slug": "vip-contacts", "description": "High-value contacts" } }, "developer.CreateTaskRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Task title (non-empty)" }, "description": { "type": "string", "description": "Task description" }, "priority": { "type": "string", "description": "Task priority", "enum": [ "unspecified", "low", "medium", "high", "urgent" ] }, "due_date": { "type": "string", "format": "date-time", "description": "Due date (RFC3339)" }, "entity_ids": { "type": "array", "items": { "type": "string" }, "description": "Associated record IDs" }, "assignee_ids": { "type": "array", "items": { "type": "string" }, "description": "Assigned user IDs" } }, "example": { "title": "Follow up with client", "description": "Discuss contract renewal", "priority": "high", "due_date": "2026-03-01T09:00:00Z", "entity_ids": [ "1001", "1002" ], "assignee_ids": [ "50" ] } }, "developer.UpdateTaskRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "New title (cannot be empty)" }, "description": { "type": "string", "description": "New description (empty string clears it)" }, "priority": { "type": "string", "description": "New priority (empty string clears it)", "enum": [ "unspecified", "low", "medium", "high", "urgent", "" ] }, "due_date": { "type": "string", "format": "date-time", "description": "New due date" }, "is_completed": { "type": "boolean", "description": "Mark complete/incomplete" }, "entity_ids": { "type": "array", "items": { "type": "string" }, "description": "Replace associated records" }, "assignee_ids": { "type": "array", "items": { "type": "string" }, "description": "Replace assignees" } }, "example": { "title": "Updated title", "priority": "urgent", "is_completed": true, "entity_ids": [ "1001" ], "assignee_ids": [ "50", "51" ] } }, "developer.TaskResponse": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string" }, "due_date": { "type": "string", "format": "date-time" }, "is_completed": { "type": "boolean" }, "completed_at": { "type": "string", "format": "date-time" }, "assignee_ids": { "type": "array", "items": { "type": "string" } }, "entity_ids": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "created_by_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time" } }, "example": { "id": "800", "title": "Follow up with client", "description": "Discuss contract renewal", "priority": "high", "due_date": "2026-03-01T09:00:00Z", "is_completed": false, "assignee_ids": [ "50" ], "entity_ids": [ "1001", "1002" ], "created_by": "developer_api", "created_by_id": "42", "created_at": "2024-01-15T10:00:00Z" } }, "developer.ListTasksResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.TaskResponse" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer" }, "next_offset": { "type": "integer" } }, "example": { "data": [ { "id": "800", "title": "Follow up with client", "priority": "high", "is_completed": false, "created_by": "developer_api", "created_at": "2024-01-15T10:00:00Z" } ], "has_more": true, "total": 47, "next_offset": 20 } }, "developer.CreateNoteRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Note title (non-empty)" }, "content": { "type": "string", "description": "Note body text" }, "entity_id": { "type": "string", "description": "Associated record ID" } }, "example": { "title": "Meeting notes", "content": "Discussed Q3 roadmap...", "entity_id": "1001" } }, "developer.UpdateNoteRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "New title" }, "content": { "type": "string", "description": "New content" }, "entity_id": { "type": "string", "description": "Change associated record" } }, "example": { "title": "Updated meeting notes", "content": "Added action items..." } }, "developer.NoteResponse": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "entity_id": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time" } }, "example": { "id": "900", "title": "Meeting notes", "content": "Discussed Q3 roadmap...", "entity_id": "1001", "created_by": "developer_api", "created_at": "2024-01-15T10:00:00Z" } }, "developer.ListNotesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.NoteResponse" } } } }, "developer.TimelineResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.TimelineEventResponse" } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "developer.TimelineEventResponse": { "type": "object", "properties": { "id": { "type": "string" }, "resource_type": { "type": "string", "description": "Type of resource", "enum": [ "entity", "task", "note", "list_item", "attribute" ] }, "resource_id": { "type": "string" }, "event_type": { "type": "string", "description": "Type of event", "enum": [ "created", "updated", "deleted", "archived" ] }, "event_payload": { "$ref": "#/components/schemas/developer.TimelineEventPayloadResponse" }, "event_timestamp": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "created_by_id": { "type": "string" }, "is_aggregated": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/developer.TimelineEventResponse" } } }, "example": { "id": "5000", "resource_type": "task", "resource_id": "800", "event_type": "created", "event_payload": { "task": { "id": "800", "title": "Follow up", "priority": "high" } }, "event_timestamp": "2024-01-15T10:00:00Z", "created_by": "developer_api", "created_by_id": "42", "is_aggregated": false, "children": [] } }, "developer.TimelineEventPayloadResponse": { "type": "object", "description": "Only the relevant field is populated based on resource_type", "properties": { "task": { "$ref": "#/components/schemas/developer.TimelineTaskPayload" }, "note": { "$ref": "#/components/schemas/developer.TimelineNotePayload" }, "entity": { "$ref": "#/components/schemas/developer.TimelineEntityPayload" }, "list_item": { "$ref": "#/components/schemas/developer.TimelineListItemPayload" }, "attribute": { "$ref": "#/components/schemas/developer.TimelineAttributePayload" }, "field_changes": { "type": "array", "items": { "$ref": "#/components/schemas/developer.FieldChangeResponse" } } } }, "developer.TimelineTaskPayload": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "due_date": { "type": "string", "format": "date-time" }, "priority": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" } } }, "developer.TimelineNotePayload": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" } } }, "developer.TimelineEntityPayload": { "type": "object", "properties": { "id": { "type": "string" }, "definition_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": {} } } }, "developer.TimelineListItemPayload": { "type": "object", "properties": { "id": { "type": "string" }, "definition_id": { "type": "string" }, "list_name": { "type": "string" }, "parent_id": { "type": "string" } } }, "developer.TimelineAttributePayload": { "type": "object", "properties": { "id": { "type": "string" }, "definition_id": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "value": {}, "plain_text": { "type": "string" } } }, "developer.FieldChangeResponse": { "type": "object", "properties": { "field_name": { "type": "string" }, "old_value": {}, "new_value": {} } }, "developer.InsightsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developer.InsightResponse" }, "description": "Array of insight objects" } } }, "developer.InsightResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique insight identifier" }, "workspace_id": { "type": "string", "description": "Workspace the insight belongs to" }, "content": { "type": "string", "description": "Human-readable insight text" }, "type": { "type": "string", "description": "Insight category or type" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "description": "Entities referenced in this insight" }, "created_at": { "type": "string", "format": "date-time", "description": "When the insight was generated" } } }, "developer.SearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query (1-500 characters)" } }, "example": { "query": "john doe" } }, "developer.SearchResponse": { "type": "object", "properties": { "results": { "type": "object", "description": "Results grouped by object type (e.g., 'person', 'company')", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/developer.SearchResultResponse" } } }, "errored_search_types": { "type": "array", "items": { "type": "string" }, "description": "Search types that encountered errors (partial results returned)" } }, "example": { "results": { "person": [ { "id": "1001", "primary_value": "John Doe", "matched_value": "John Doe", "score": 0.95, "entity_definition_id": "10" } ], "company": [ { "id": "2001", "primary_value": "Doe Industries", "matched_value": "Doe Industries", "score": 0.72, "entity_definition_id": "11" } ] }, "errored_search_types": [] } }, "developer.SearchResultResponse": { "type": "object", "properties": { "id": { "type": "string" }, "primary_value": { "type": "string", "description": "Primary display value of the record" }, "matched_value": { "type": "string", "description": "Value that matched the search query" }, "score": { "type": "number", "description": "Relevance score" }, "entity_definition_id": { "type": "string", "description": "Object definition ID" } } }, "developer.IntegrationResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "Integration type", "enum": [ "email", "calendar", "messaging", "crm" ], "example": "email" }, "provider": { "type": "string", "description": "Integration provider", "enum": [ "google", "microsoft", "slack", "attio", "hubspot", "salesforce" ], "example": "google" }, "display_name": { "type": "string", "description": "Human-readable name of the integration", "example": "Gmail" }, "description": { "type": "string", "description": "Description of the integration", "example": "Connect to your Gmail account to automatically sync emails, create contacts, and update context." }, "connections": { "type": "array", "description": "Active connections for this integration", "items": { "$ref": "#/components/schemas/developer.ConnectionResponse" } } } }, "developer.ConnectionResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Connection ID", "example": 12345 }, "status": { "type": "string", "description": "Connection status", "example": "active" }, "identifier": { "type": "string", "description": "Account identifier (email address, username, etc.)", "example": "user@example.com" } } }, "developer.ConnectResponse": { "type": "object", "properties": { "auth_url": { "type": "string", "description": "OAuth authorization URL. Open this in a browser for the user to grant access.", "example": "https://accounts.google.com/o/oauth2/v2/auth?..." }, "connect_id": { "type": "string", "description": "Encrypted token to poll for connection status. Expires after 10 minutes.", "example": "eyJ3Ijo..." } } }, "developer.ConnectStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Connection status: \"pending\" while waiting, \"connected\" when complete", "enum": [ "pending", "connected" ], "example": "connected" }, "connection_id": { "type": "integer", "description": "ID of the newly created connection (only present when status is \"connected\")", "example": 12345 } } }, "graph.GraphResponse": { "type": "object", "description": "Complete knowledge graph for the workspace", "properties": { "nodes": { "type": "array", "description": "CRM entity nodes (people, companies, custom objects) and ghost nodes (entities mentioned in context but not yet resolved to a CRM record)", "items": { "$ref": "#/components/schemas/graph.GraphNode" } }, "edges": { "type": "array", "description": "CRM relationship edges between entity nodes (e.g., person works_at company)", "items": { "$ref": "#/components/schemas/graph.GraphEdge" } }, "relationship_definitions": { "type": "array", "description": "Definitions of relationship types in the workspace", "items": { "$ref": "#/components/schemas/graph.GraphRelationshipDefinition" } }, "context_edges": { "type": "array", "description": "Edges derived from ingested context, AI-extracted triplets, insight-entity links, and insight-to-insight semantic relationships. Each edge has an `edge_type` indicating its source.", "items": { "$ref": "#/components/schemas/graph.ContextEdge" } }, "insight_nodes": { "type": "array", "description": "Insight nodes representing AI-extracted knowledge (entity insights and workspace-level knowledge insights)", "items": { "$ref": "#/components/schemas/graph.InsightNode" } }, "insights": { "type": "object", "description": "Per-entity insight summaries, keyed by entity ID", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/graph.EntityInsightSummary" } } }, "total_nodes": { "type": "integer", "description": "Total number of entity nodes in the workspace (may exceed the returned count due to the limit parameter)" }, "total_edges": { "type": "integer", "description": "Total number of CRM relationship edges in the workspace" }, "total_context_edges": { "type": "integer", "description": "Total number of context edges returned (includes all edge types)" } } }, "graph.GraphNode": { "type": "object", "description": "A node in the knowledge graph representing a CRM entity or a ghost (unresolved) entity", "properties": { "id": { "type": "string", "description": "Node ID. CRM entities use numeric IDs (e.g., \"12345\"). Ghost nodes use the format \"ghost:\".", "example": "12345" }, "name": { "type": "string", "description": "Display name (primary attribute value, or a generated name for unnamed entities)", "example": "John Smith" }, "type": { "type": "string", "description": "Entity type name (e.g., \"person\", \"company\", \"ghost\")", "example": "person" }, "definition_slug": { "type": "string", "description": "Slug of the entity definition", "example": "person" }, "primary_attribute": { "type": "string", "description": "Value of the entity's primary attribute" }, "created_at": { "type": "string", "format": "date-time", "description": "When the entity was created" } } }, "graph.GraphEdge": { "type": "object", "description": "A CRM relationship edge between two entity nodes", "properties": { "id": { "type": "string", "description": "Edge ID" }, "source": { "type": "string", "description": "Source node ID" }, "target": { "type": "string", "description": "Target node ID" }, "label": { "type": "string", "description": "Relationship label (e.g., \"works_at\", \"reports_to\")", "example": "works_at" }, "definition_id": { "type": "string", "description": "ID of the relationship definition" } } }, "graph.GraphRelationshipDefinition": { "type": "object", "description": "Definition of a relationship type", "properties": { "id": { "type": "string", "description": "Definition ID" }, "name": { "type": "string", "description": "Display name" }, "entity_1_to_2": { "type": "string", "description": "Label from entity 1 to entity 2 (e.g., \"works_at\")" }, "entity_2_to_1": { "type": "string", "description": "Inverse label from entity 2 to entity 1 (e.g., \"employs\")" } } }, "graph.ContextEdge": { "type": "object", "description": "An edge in the context/knowledge layer of the graph. The `edge_type` field indicates the source: \"context\" (from ingested text), \"triplet\" (AI-extracted subject-predicate-object), \"insight\" (linking an insight node to an entity), or \"insight_link\" (semantic relationship between two insight nodes).", "properties": { "id": { "type": "string", "description": "Edge ID. Prefixed by type: \"ctx_\" for context, \"tri_\" for triplet, \"ei_edge_\" for entity insight edges, and \"il_\" for insight_link edges.", "example": "tri_42" }, "source": { "type": "string", "description": "Source node ID. Can be an entity ID, ghost ID (\"ghost:123\"), or insight node ID (\"ei:123\" or \"ki:123\").", "example": "12345" }, "target": { "type": "string", "description": "Target node ID", "example": "67890" }, "label": { "type": "string", "description": "Edge label. For context edges: the relationship type. For triplets: the predicate (e.g., \"works_with\"). For insight edges: the insight type. For insight_link edges: \"related_to\" or \"contradicts\".", "example": "works_with" }, "edge_type": { "type": "string", "description": "Source type of the edge", "enum": ["context", "triplet", "insight", "insight_link"] }, "confidence": { "type": "number", "format": "double", "description": "Confidence score (0-1). Present on triplet edges (extraction confidence) and insight_link edges (similarity score). Null/absent for context and insight edges.", "nullable": true, "minimum": 0, "maximum": 1 } } }, "graph.InsightNode": { "type": "object", "description": "An insight node representing AI-extracted knowledge", "properties": { "id": { "type": "string", "description": "Insight node ID. Entity insights use \"ei:\", knowledge insights use \"ki:\".", "example": "ei:42" }, "content": { "type": "string", "description": "The insight text content", "example": "John prefers email communication over phone calls" }, "type": { "type": "string", "description": "Insight type (e.g., \"preference\", \"behavior\", \"fact\")", "example": "preference" }, "confidence": { "type": "number", "format": "double", "description": "Confidence score (0-1)", "minimum": 0, "maximum": 1 }, "source": { "type": "string", "description": "Source type: \"entity_insight\" (scoped to an entity) or \"knowledge_insight\" (workspace-level)", "enum": ["entity_insight", "knowledge_insight"] } } }, "graph.EntityInsightSummary": { "type": "object", "description": "Summary of an insight associated with a specific entity", "properties": { "content": { "type": "string", "description": "The insight text content" }, "confidence": { "type": "number", "format": "double", "description": "Confidence score (0-1)", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "description": "Insight type" } } }, "compounding.TriggerJobRequest": { "type": "object", "required": ["job_type"], "properties": { "job_type": { "type": "string", "description": "The type of compounding job to run", "enum": [ "consolidation", "pattern_detection", "playbook_synthesis", "decay_sweep", "metrics" ] }, "dry_run": { "type": "boolean", "description": "If true, preview impact without persisting changes", "default": false } } }, "compounding.TriggerJobResponse": { "type": "object", "properties": { "job_run_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this job execution" }, "job_type": { "type": "string", "description": "The type of job that was executed", "enum": [ "consolidation", "pattern_detection", "playbook_synthesis", "decay_sweep", "metrics" ] }, "workspace_id": { "type": "integer", "description": "Workspace ID the job ran against" }, "dry_run": { "type": "boolean", "description": "Whether the job ran in dry-run mode" }, "status": { "type": "string", "description": "Current job status", "enum": [ "accepted" ] }, "success": { "type": "boolean", "description": "Whether the job was accepted successfully" } } }, "compounding.JobStatusResponse": { "type": "object", "properties": { "job_run_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this compounding job" }, "job_type": { "type": "string", "description": "The compounding job type", "enum": [ "consolidation", "pattern_detection", "playbook_synthesis", "decay_sweep", "metrics" ] }, "workspace_id": { "type": "integer", "description": "Workspace ID the job belongs to" }, "status": { "type": "string", "description": "Current job status", "enum": [ "accepted", "running", "completed", "failed" ] }, "dry_run": { "type": "boolean", "description": "Whether the job is running in dry-run mode" }, "insights_scanned": { "type": "integer", "description": "Total number of insights evaluated during the job" }, "insights_affected": { "type": "integer", "description": "Number of insights modified by the job" }, "candidates_created": { "type": "integer", "description": "Number of candidates or rules created by the job" }, "errors": { "type": "integer", "description": "Number of errors recorded during the job" }, "started_at": { "type": "string", "format": "date-time", "description": "When the job entered the system" }, "completed_at": { "type": "string", "format": "date-time", "description": "When the job completed, if it has finished" }, "duration_ms": { "type": "integer", "description": "Total job duration in milliseconds after completion" }, "error_details": { "type": "object", "description": "Structured error payload for failed jobs", "additionalProperties": true } } }, "developer.NotificationFeedItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique notification ID" }, "type": { "type": "string", "description": "Notification type (e.g., 'context_alert', 'digest')" }, "status": { "type": "string", "description": "Notification status (e.g., 'unread', 'read')" }, "alert_time": { "type": "string", "format": "date-time", "description": "When the alert condition was detected" }, "sent_at": { "type": "string", "format": "date-time", "description": "When the notification was sent" }, "content": { "type": "object", "description": "Notification content payload", "properties": { "important_items": { "type": "array", "description": "List of important items flagged by the notification system", "items": { "type": "object" } }, "entity_changes": { "type": "array", "description": "List of entity changes that triggered the notification", "items": { "type": "object" } } } } } }, "developer.NotificationFeedResponse": { "type": "object", "properties": { "items": { "type": "array", "description": "List of notification feed items", "items": { "$ref": "#/components/schemas/developer.NotificationFeedItem" } } } }, "developer.NotificationPreferencesResponse": { "type": "object", "properties": { "frequency_minutes": { "type": "integer", "description": "How often the notification system polls for new alerts (in minutes)" }, "enabled_types": { "type": "array", "description": "List of enabled notification types", "items": { "type": "string" } }, "digest_enabled": { "type": "boolean", "description": "Whether digest notifications are enabled" } } }, "developer.UpdateNotificationPreferencesRequest": { "type": "object", "properties": { "frequency_minutes": { "type": "integer", "description": "How often the notification system polls for new alerts (in minutes)" }, "enabled_types": { "type": "array", "description": "List of notification types to enable", "items": { "type": "string" } }, "digest_enabled": { "type": "boolean", "description": "Whether to enable digest notifications" } } }, "developer.CustomNotificationRuleResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "name": { "type": "string", "description": "Human-readable rule name" }, "prompt": { "type": "string", "description": "The natural language prompt describing the notification condition" }, "is_enabled": { "type": "boolean", "description": "Whether the rule is currently active" }, "schedule": { "type": "string", "description": "Cron-style schedule for rule evaluation" }, "created_at": { "type": "string", "format": "date-time", "description": "When the rule was created" } } }, "developer.ListCustomNotificationRulesResponse": { "type": "object", "properties": { "rules": { "type": "array", "description": "List of custom notification rules", "items": { "$ref": "#/components/schemas/developer.CustomNotificationRuleResponse" } } } }, "developer.CreateCustomNotificationRuleRequest": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "description": "Natural language description of what you want to be notified about" } } } } } }