{ "openapi": "3.0.3", "info": { "title": "Heliyos API", "version": "1.0.0", "description": "The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`.", "contact": { "name": "Heliyos support", "email": "soham@heliyos.ai", "url": "https://www.heliyos.ai" } }, "servers": [ { "url": "https://api-prod.heliyos.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Workspace", "description": "The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace." }, { "name": "Schemas", "description": "Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold." }, { "name": "Records", "description": "Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records." }, { "name": "Timeline", "description": "The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions." }, { "name": "Activities", "description": "The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make." }, { "name": "Interactions", "description": "Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve." }, { "name": "Notes", "description": "Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory." }, { "name": "Tasks", "description": "Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly." }, { "name": "Workers and runs", "description": "Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on." }, { "name": "Reviews", "description": "Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it." }, { "name": "Scouts", "description": "Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies." }, { "name": "Signals", "description": "Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read." }, { "name": "Watchlist", "description": "The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it." }, { "name": "Knowledge base", "description": "What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`." }, { "name": "Files", "description": "Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file." }, { "name": "Labels", "description": "Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels." }, { "name": "Team", "description": "The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email." }, { "name": "Notification settings", "description": "Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it." } ], "paths": { "/v1/platform/organization": { "get": { "operationId": "getOrganization", "tags": [ "Workspace" ], "parameters": [], "responses": { "200": { "description": "The workspace summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Workspace" } } }, "example": { "meta": { "message": "Organization fetched." }, "data": { "id": "66a0f1e2d3c4b5a697887766", "name": "Northwind Traders", "billingStatus": "active", "plan": { "name": "Growth" }, "memberCount": 8, "recordCounts": { "companies": 1240, "people": 3815, "deals": 96 }, "watchersInUse": 42, "watchersLimit": 100 } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: the workspace no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get the workspace", "description": "Returns the workspace your API key belongs to: its id and name, billing status, active plan,\nmember count, how many companies, people and deals it holds, and how many companies are watched\nout of the plan's limit.\n\nCounts are computed on every call, so they are always current.", "x-mint": { "href": "/api-reference/workspace/get-the-workspace", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_organization_get`](/mcp/tools/workspace-objects-and-fields#heliyos-organization-get)." } } }, "/v1/platform/usage": { "get": { "operationId": "listUsage", "tags": [ "Workspace" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Entries per page, 1 to 100. Defaults to 20.", "example": 50 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "The page to return, starting at 1. Defaults to 1.", "example": 1 }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only entries recorded at or after this time, as an ISO 8601 date or date-time. A date alone means midnight UTC at the start of that day.", "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only entries recorded at or before this time, as an ISO 8601 date or date-time. A date alone means midnight UTC at the start of that day, so to include a whole day send the next day's midnight or `T23:59:59.999Z`.", "example": "2026-10-31T23:59:59.999Z" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only entries for this feature, exact match and case-sensitive, for example `worker_run` or `company_enrichment`. See `feature` on the entry for the values.", "example": "worker_run" }, { "name": "objectId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only entries charged on this object, exact match. For a worker run, pass the run id.", "example": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Case-insensitive text matched against `feature`, `objectId`, `objectType` and `description`. Up to 200 characters. An empty string is ignored.", "example": "enrichment" } ], "responses": { "200": { "description": "A page of usage entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEntry" } } } }, "example": { "meta": { "message": "Usage logs fetched successfully", "pagination": { "page": 1, "limit": 20, "offset": 0, "count": 2, "hasMore": false } }, "data": [ { "_id": "6721c0a4b5d6e7f8a9b0c1d2", "organizationId": "66a0f1e2d3c4b5a697887766", "feature": "worker_run", "creditsUtilized": 5, "objectId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e", "objectType": "orchestrator_run", "sourceService": "agent", "description": "worker account_researcher in run 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e", "metadata": { "workerId": "6720f3a1b2c3d4e5f6a7b8c9", "tool": "account_researcher" }, "meta": { "organizationId": "66a0f1e2d3c4b5a697887766", "feature": "worker_run", "sourceService": "agent" }, "createdAt": "2026-11-04T10:12:40.000Z" }, { "_id": "6721bf02a3b4c5d6e7f8a9b0", "organizationId": "66a0f1e2d3c4b5a697887766", "feature": "company_enrichment", "creditsUtilized": 2, "sourceService": "agent", "description": "Company enrichment", "metadata": {}, "meta": { "organizationId": "66a0f1e2d3c4b5a697887766", "feature": "company_enrichment", "sourceService": "agent" }, "createdAt": "2026-11-04T09:58:11.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List credit usage", "description": "Returns the workspace's credit charges, newest first. Each entry says when credits were spent,\nby which feature, how many, and on what. Use it to reconcile your balance or to see what a\nworker run cost.\n\nThis list pages by page number: send `page` and `limit`. `meta.pagination` carries `page`,\n`limit`, `offset` (rows skipped), `count` (all matching entries) and `hasMore`. There is no\ncursor. To total a period, page through every entry for it and add up `creditsUtilized`.\n\nFilters combine with AND. The API is read-only for usage: there is no way to add, change or\nrefund credits through it.", "x-mint": { "href": "/api-reference/workspace/list-credit-usage", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_usage_get`](/mcp/tools/usage#heliyos-usage-get)." } } }, "/v1/platform/base-schemas": { "get": { "operationId": "listBaseSchemas", "tags": [ "Schemas" ], "parameters": [ { "name": "isRecordCount", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "true adds `recordCount` (the number of records) to each object. Counting takes longer on large workspaces. Defaults to false.", "example": true } ], "responses": { "200": { "description": "All objects you may view.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaObject" } } } }, "example": { "meta": { "message": "Schemas retrieved successfully" }, "data": [ { "id": "66a0f1e2d3c4b5a697880001", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Company", "slug": "company", "description": "Master data for companies", "type": "base", "objectType": "company", "viewType": "table", "fields": [ { "id": "674af8e0017b924c5d1d69b2", "sequence": 1, "name": "company_name", "displayName": "Company", "type": { "type": "relationship", "enum": [ "relationship", "text" ] }, "required": true, "isAIEnabled": false, "isHiddenField": false, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "hasAccess": true } ], "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "recordCount": 412, "created": { "at": "2026-01-12T08:00:00.000Z", "by": "system" }, "updated": { "at": "2026-10-02T14:21:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } }, { "id": "6730b1c4d3e5f6a7b8c9d0e1", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Partners", "slug": "partners", "type": "custom", "objectType": "partners", "viewType": "table", "fields": [ { "id": "6730c2d5e4f6a7b8c9d0e1f2", "sequence": 4, "name": "partner_tier", "displayName": "Partner tier", "type": { "type": "select", "enum": [ "select" ] }, "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" } ] }, "required": false, "isAIEnabled": false, "isHiddenField": false, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "hasAccess": true } ], "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "recordCount": 18, "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List objects", "description": "Returns every object (base schema) in the workspace that you may view, with its fields, oldest\nfirst: companies, people, each deal pipeline and your custom objects. The list is not paginated;\na workspace has a handful of objects.\n\nUse it to find an object's `id` (records call it `schemaId`) and its field keys. Fields whose\npermissions hide them from you are left out of each object.", "x-mint": { "href": "/api-reference/schemas/list-objects", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_objects_list`](/mcp/tools/workspace-objects-and-fields#heliyos-objects-list)." } } }, "/v1/platform/base-schemas/{id}": { "get": { "operationId": "getBaseSchema", "tags": [ "Schemas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "6730b1c4d3e5f6a7b8c9d0e1" } ], "responses": { "200": { "description": "The object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/SchemaObject" } } }, "example": { "meta": { "message": "Base schema retrieved successfully" }, "data": { "_id": "6730b1c4d3e5f6a7b8c9d0e1", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Partners", "slug": "partners", "description": "Resellers and referral partners.", "type": "custom", "objectType": "partners", "icon": "PiHandshake", "viewType": "table", "kanbanConfig": { "_id": "6730b1c4d3e5f6a7b8c9d0e2", "lanes": [] }, "fields": [ { "id": "6730c2d5e4f6a7b8c9d0e1f2", "sequence": 4, "name": "partner_tier", "displayName": "Partner tier", "description": "Commercial tier agreed in the partner contract.", "icon": "PiMedal", "type": { "type": "select", "enum": [ "select" ], "relationshipConfig": [] }, "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" }, { "value": "Registered", "color": "blue" } ] }, "isAIEnabled": false, "isHiddenField": false, "isReadOnly": false, "isVisibleOnlyInPage": false, "required": false, "unique": false, "validation": { "rules": [] }, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ], "agents": [], "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:31:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: the object is private and you are not on its view list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get an object", "description": "Returns one object (base schema) with its fields. Fields whose permissions hide them from you\nare left out.\n\nThis response names the object's id `_id`, where list, create and update name it `id`.", "x-mint": { "href": "/api-reference/schemas/get-an-object", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_fields_create`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-create), [`heliyos_fields_delete`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-delete), [`heliyos_fields_update`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-update), [`heliyos_objects_get`](/mcp/tools/workspace-objects-and-fields#heliyos-objects-get)." } } }, "/v1/platform/base-schemas/{id}/fields": { "post": { "operationId": "createBaseSchemaField", "tags": [ "Schemas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "6730b1c4d3e5f6a7b8c9d0e1" } ], "responses": { "201": { "description": "The new field.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/SchemaField" } } }, "example": { "meta": { "message": "Schema attribute added successfully" }, "data": { "id": "6730c2d5e4f6a7b8c9d0e1f2", "sequence": 4, "name": "partner_tier", "displayName": "Partner tier", "description": "Commercial tier agreed in the partner contract.", "icon": "PiMedal", "type": { "type": "select", "enum": [ "select" ], "relationshipConfig": [] }, "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" }, { "value": "Registered", "color": "blue" } ] }, "isAIEnabled": false, "isHiddenField": false, "isReadOnly": false, "isVisibleOnlyInPage": false, "required": false, "unique": false, "validation": { "rules": [] }, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a required property is missing, `type.type` is not a supported type, `default.value` does not fit the type, `permissions` is incomplete, a `pattern` rule is unsafe, or the field could not be added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The field's key: what records use in `data` and filters name. 1 to 100 characters. Use lowercase letters, digits and underscores, starting with a letter, for example `partner_tier`. The API does not check the format yet, but keys with dots or `$` do not work in filters and updates, so avoid them. Must be new on the object (see the warning).", "example": "partner_tier" }, "type": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "richText", "number", "currency", "rating", "checkbox", "date", "timestamp", "select", "multiSelect", "url", "email", "phone", "user", "image", "relationship" ], "description": "The field type. Any other value is refused with 400." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Related kinds for the web app's editors, for example `[\"text\", \"richText\"]` for `text`. Send the value in the field types table." }, "relationshipSchemaId": { "type": "string", "description": "`relationship` only: id of the object to link to." }, "relationshipConfig": { "type": "array", "description": "`relationship` only: how the link maps onto the other object. Stored on this object only; the matching field on the other object is not created or changed.", "items": { "type": "object", "required": [ "targetSchema", "associatedField", "inverseName" ], "additionalProperties": false, "properties": { "targetSchema": { "type": "string", "description": "Id of the linked object." }, "associatedField": { "type": "string", "description": "Key of the matching field on the linked object." }, "inverseName": { "type": "string", "description": "Key of this side of the link." }, "onDelete": { "type": "string", "enum": [ "cascade", "setNull", "restrict" ], "description": "What the link should do when the linked record is deleted. Defaults to `setNull`." } } } } }, "required": [ "type" ], "additionalProperties": false, "description": "The field's type. `type.type` is required; send the rest as the web app does (see the field types table)." }, "displayName": { "type": "string", "description": "The label shown in the web app, for example `Contract value`. May be empty." }, "sequence": { "type": "number", "format": "float", "description": "The field's position, starting at 1. To append, send the highest `sequence` on the object plus 1, as the web app does. Stored as sent.", "example": 4 }, "icon": { "type": "string", "description": "An icon name from the web app's icon set." }, "description": { "type": "string", "description": "What the field holds. Shown in the web app and read by workers." }, "isAIEnabled": { "type": "boolean", "description": "true makes the field an AI column that workers fill from `aiPrompt`. The web app offers it for `text`, `richText`, `number`, `date`, `select`, `multiSelect` and `checkbox`. Turning it on or off resets each record's AI status for the field; stored values are kept." }, "isHiddenField": { "type": "boolean", "description": "true hides the field from table views by default. Default false." }, "required": { "type": "boolean", "description": "true makes creating a record without this key fail with 400. An empty string or null still counts as a value, and record updates are not checked. Default false." }, "unique": { "type": "boolean", "description": "Shown in the web app. The API does not enforce uniqueness on record writes. Default false." }, "aiPrompt": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The instructions workers follow to fill the field." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Names of the fields the prompt mentions. Send `[]` when it mentions none." } }, "additionalProperties": false, "description": "The AI column's prompt." }, "validation": { "type": "object", "properties": { "rules": { "type": "array", "maxItems": 20, "description": "Up to 20 rules, each `{ \"type\", \"value\", \"message\" }`. Rule types:\n- `minLength`, `maxLength`: string length, `value` a number.\n- `pattern`: a regular expression the value must match, `value` a string of at most 200\n characters. A pattern that is invalid or could take exponential time (nested repetition\n such as `(a+)+`) is refused with 400.\n- `email`: the value must be an email address (`value` is ignored).\n- `min`, `max`: number bounds, `value` a number.\n\nOther rule types are stored but not checked. Use string rules on text-like types and `min`\nand `max` on number types.\n", "items": { "type": "object", "required": [ "type", "value", "message" ], "additionalProperties": false, "properties": { "type": { "type": "string", "description": "`minLength`, `maxLength`, `pattern`, `email`, `min` or `max`." }, "value": { "description": "The rule's argument." }, "message": { "type": "string", "description": "A message for people editing the record." } } } } }, "additionalProperties": false, "description": "Rules checked whenever a record writes this field. Values already stored are not re-checked." }, "default": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "`static` or `dynamic`." }, "value": { "description": "The default value." } }, "required": [ "type", "value" ], "additionalProperties": false, "description": "A default stored with the field. `value` must fit the field's type, or the request fails with 400. Records are not filled from it; use `settings.defaultValue` for that." }, "settings": { "type": "object", "properties": { "selectOptions": { "type": "array", "description": "`select` and `multiSelect`: the choices, in order. Each is `{ \"value\", \"color\" }` or a bare string. Colours are label families: `red`, `orange`, `amber`, `olive`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Values are stored as sent; keep them unique.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "value", "color" ], "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The option's text, which is what records store." }, "color": { "type": "string", "description": "A label colour family." } } } ] } }, "currencyOptions": { "type": "object", "additionalProperties": false, "description": "`currency`: how the web app formats amounts.", "properties": { "currency": { "type": "string", "description": "A two-letter country code whose currency is used, for example `US` for US dollars." }, "display": { "type": "string", "description": "`symbol`, `code` or `name`." } } }, "defaultValue": { "description": "The value a new record gets when it is created without one (missing, null or an empty string). Must fit the field's type, or record creation fails." }, "aiRunStatus": { "type": "string", "enum": [ "RUNNING", "PENDING", "FINISHED", "ERROR", "" ], "description": "A display status for an AI column. The web app sends `PENDING` when it saves an AI column without running it." }, "abbreviateNumber": { "type": "boolean", "description": "`number` and `currency`: show large values as 1.2k, 3.4M and so on." } }, "additionalProperties": false, "description": "Type-specific configuration. See the field types table for which keys apply." }, "permissions": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "organization" ], "description": "`organization` or `private`." }, "editableBy": { "type": "object", "additionalProperties": false, "description": "Who may edit the field when it is private.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names: `OWNER`, `ADMIN`, `MEMBER`, `STAFF`, `SUPPORT`, `SUPER_ADMIN`, `AGENCY`." }, "users": { "type": "array", "items": { "type": "string" }, "description": "User ids." } } }, "viewableBy": { "type": "object", "additionalProperties": false, "description": "Who may view the field when it is private.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names, as in `editableBy`." }, "users": { "type": "array", "items": { "type": "string" }, "description": "User ids." } } } }, "required": [ "visibility", "editableBy", "viewableBy" ], "additionalProperties": false, "description": "Required. Who may view and edit the field. With `organization`, every member who can see the object may. With `private`, only the listed roles and users. Send both `roles` and `users` in each list. The web app's default lists every role." }, "runImmediately": { "type": "boolean", "description": "With `isAIEnabled: true`, starts a worker run now that fills this field on every record of the object. It uses credits for each record processed. Default false." } }, "required": [ "name", "type", "permissions" ], "additionalProperties": false }, "examples": { "select": { "summary": "A select field", "value": { "name": "partner_tier", "displayName": "Partner tier", "description": "Commercial tier agreed in the partner contract.", "sequence": 4, "type": { "type": "select", "enum": [ "select" ] }, "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" }, { "value": "Registered", "color": "blue" } ] }, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } } } }, "currency": { "summary": "A currency field", "value": { "name": "contract_value", "displayName": "Contract value", "sequence": 5, "type": { "type": "currency", "enum": [ "number" ] }, "settings": { "currencyOptions": { "currency": "US", "display": "symbol" }, "abbreviateNumber": true }, "validation": { "rules": [ { "type": "min", "value": 0, "message": "Contract value cannot be negative." } ] }, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } } } }, "aiColumn": { "summary": "An AI column", "value": { "name": "partner_fit", "displayName": "Partner fit", "sequence": 6, "type": { "type": "richText", "enum": [ "richText", "text" ] }, "isAIEnabled": true, "aiPrompt": { "prompt": "Summarise how well this partner's customer base matches our ideal customer profile.", "variables": [] }, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "runImmediately": false } } } } } }, "summary": "Create a field", "description": "Adds a field to an object (base schema). Every existing record gets an empty value for the new\nfield. The response is the new field, not the whole object.\n\n\n`type.type` decides what records can store. Send the `type` object shown, as the web app does.\nEvery type also accepts `\"\"` or `null` as no value.\n\n| `type.type` | Records store | Send as `type` | Extra configuration |\n|---|---|---|---|\n| `text` | A string, trimmed. | `{\"type\":\"text\",\"enum\":[\"text\",\"richText\"]}` | None |\n| `richText` | A string of formatted text. | `{\"type\":\"richText\",\"enum\":[\"richText\",\"text\"]}` | None |\n| `number` | A number. | `{\"type\":\"number\",\"enum\":[\"number\"]}` | `settings.abbreviateNumber` |\n| `currency` | A number, the amount. | `{\"type\":\"currency\",\"enum\":[\"number\"]}` | `settings.currencyOptions`, `settings.abbreviateNumber` |\n| `rating` | A number. The web app shows 1 to 5 stars; the API does not limit it. | `{\"type\":\"rating\",\"enum\":[\"number\"]}` | None |\n| `checkbox` | `true` or `false`. | `{\"type\":\"checkbox\",\"enum\":[\"boolean\"]}` | None |\n| `date` | A date, sent as an ISO 8601 string. | `{\"type\":\"date\",\"enum\":[\"date\",\"timestamp\"]}` | None |\n| `timestamp` | A date and time, sent as an ISO 8601 string. | `{\"type\":\"timestamp\",\"enum\":[\"timestamp\",\"date\"]}` | None |\n| `select` | One string. | `{\"type\":\"select\",\"enum\":[\"select\"]}` | `settings.selectOptions` |\n| `multiSelect` | An array of strings. | `{\"type\":\"multiSelect\",\"enum\":[\"multiSelect\"]}` | `settings.selectOptions` |\n| `url` | A URL. Must parse as a URI. | `{\"type\":\"url\",\"enum\":[\"text\"]}` | None |\n| `email` | An email address. Must be valid. | `{\"type\":\"email\",\"enum\":[\"text\"]}` | None |\n| `phone` | A string. The format is not checked. | `{\"type\":\"phone\",\"enum\":[\"text\"]}` | None |\n| `user` | An array of workspace members. The web app stores `{ \"id\", \"name\", \"email\" }` per member, `id` being the user id. | `{\"type\":\"user\",\"enum\":[\"user\"]}` | None |\n| `image` | An object. | `{\"type\":\"image\",\"enum\":[\"text\"]}` | None |\n| `relationship` | Links to records of another object. | `{\"type\":\"relationship\",\"enum\":[\"relationship\"], ...}` | `type.relationshipSchemaId`, `type.relationshipConfig` |\n\nRecord writes check a `select` value is a string and a `multiSelect` value is an array; they do\nnot check them against `settings.selectOptions`. Relationship fields are best created in the web\napp, which sets up both sides of the link; this endpoint stores the configuration on this object\nonly. `file` fields cannot be created through the API.\n\n\nWith `isAIEnabled: true` and an `aiPrompt`, workers fill the field. Send `runImmediately: true`\nto start filling every record of the object straight away. That run uses credits for each\nrecord it processes.\n\n\nSee Update a field for what can change after creation\nand what each change does to stored values.", "x-mint": { "href": "/api-reference/schemas/create-a-field", "metadata": {}, "content": "\nPick a key (`name`) the object does not already use. The API does not refuse a duplicate key:\nthe request succeeds without adding a field, and the existing field's value is cleared to an\nempty string on every record. Read the object's fields first.\n\n\nIn the Heliyos MCP server: [`heliyos_fields_create`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-create)." } } }, "/v1/platform/base-schemas/{id}/fields/{fieldId}": { "patch": { "operationId": "updateBaseSchemaField", "tags": [ "Schemas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "6730b1c4d3e5f6a7b8c9d0e1" }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The field's `id`, from Get an object.", "example": "6730c2d5e4f6a7b8c9d0e1f2" } ], "responses": { "200": { "description": "The whole object, with the updated field.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/SchemaObject" } } }, "example": { "meta": { "message": "Schema attribute updated successfully" }, "data": { "id": "6730b1c4d3e5f6a7b8c9d0e1", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Partners", "slug": "partners", "description": "Resellers and referral partners.", "type": "custom", "objectType": "partners", "icon": "PiHandshake", "viewType": "table", "kanbanConfig": { "_id": "6730b1c4d3e5f6a7b8c9d0e2", "lanes": [] }, "fields": [ { "id": "6730b1c4d3e5f6a7b8c9d0e3", "sequence": 1, "name": "partners", "displayName": "Partners", "type": { "type": "text", "enum": [ "text", "longText", "richText" ], "relationshipConfig": [] }, "isAIEnabled": false, "isHiddenField": false, "required": false, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } } }, { "id": "6730c2d5e4f6a7b8c9d0e1f2", "sequence": 4, "name": "partner_tier", "displayName": "Partner level", "type": { "type": "select", "enum": [ "select" ], "relationshipConfig": [] }, "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" }, { "value": "Registered", "color": "blue" } ] }, "isAIEnabled": false, "isHiddenField": false, "required": false, "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T10:12:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ], "agents": [], "permissions": { "visibility": "organization", "editableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] }, "viewableBy": { "roles": [ "OWNER", "ADMIN", "MEMBER", "STAFF", "SUPPORT", "SUPER_ADMIN" ], "users": [] } }, "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } }, "400": { "description": "VALIDATION_FAILED: the body is empty or invalid, `sequence` is less than 1, the new type is unknown, records hold values for the field during a type change (\"Cannot change field type\"), or the field could not be updated. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace, or no field with this id on it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A new key, 1 to 100 characters. Stored values are not moved (see the warning)." }, "type": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "richText", "number", "currency", "rating", "checkbox", "date", "timestamp", "select", "multiSelect", "url", "email", "phone", "user", "image", "relationship" ], "description": "The field type. Any other value is refused with 400." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Related kinds for the web app's editors, for example `[\"text\", \"richText\"]` for `text`. Send the value in the field types table." }, "relationshipSchemaId": { "type": "string", "description": "`relationship` only: id of the object to link to." }, "relationshipConfig": { "type": "array", "description": "`relationship` only: how the link maps onto the other object. Stored on this object only; the matching field on the other object is not created or changed.", "items": { "type": "object", "required": [ "targetSchema", "associatedField", "inverseName" ], "additionalProperties": false, "properties": { "targetSchema": { "type": "string", "description": "Id of the linked object." }, "associatedField": { "type": "string", "description": "Key of the matching field on the linked object." }, "inverseName": { "type": "string", "description": "Key of this side of the link." }, "onDelete": { "type": "string", "enum": [ "cascade", "setNull", "restrict" ], "description": "What the link should do when the linked record is deleted. Defaults to `setNull`." } } } } }, "required": [ "type" ], "additionalProperties": false, "description": "A new type, replacing the current `type` object. Refused while records hold values for the field (see the table). Must be a type Heliyos knows, or the request fails with 400." }, "displayName": { "type": "string", "description": "The label shown in the web app, for example `Contract value`. May be empty." }, "sequence": { "type": "number", "format": "float", "description": "A new position, 1 or more. The field moves there and the fields in between shift by one. Less than 1 is refused with 400." }, "icon": { "type": "string", "description": "An icon name from the web app's icon set." }, "description": { "type": "string", "description": "What the field holds. Shown in the web app and read by workers." }, "isAIEnabled": { "type": "boolean", "description": "true makes the field an AI column that workers fill from `aiPrompt`. The web app offers it for `text`, `richText`, `number`, `date`, `select`, `multiSelect` and `checkbox`. Turning it on or off resets each record's AI status for the field; stored values are kept." }, "isHiddenField": { "type": "boolean", "description": "true hides the field from table views by default. Default false." }, "required": { "type": "boolean", "description": "true makes creating a record without this key fail with 400. An empty string or null still counts as a value, and record updates are not checked. Default false." }, "unique": { "type": "boolean", "description": "Shown in the web app. The API does not enforce uniqueness on record writes. Default false." }, "aiPrompt": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The instructions workers follow to fill the field." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Names of the fields the prompt mentions. Send `[]` when it mentions none." } }, "additionalProperties": false, "description": "The AI column's prompt." }, "validation": { "type": "object", "properties": { "rules": { "type": "array", "maxItems": 20, "description": "Up to 20 rules, each `{ \"type\", \"value\", \"message\" }`. Rule types:\n- `minLength`, `maxLength`: string length, `value` a number.\n- `pattern`: a regular expression the value must match, `value` a string of at most 200\n characters. A pattern that is invalid or could take exponential time (nested repetition\n such as `(a+)+`) is refused with 400.\n- `email`: the value must be an email address (`value` is ignored).\n- `min`, `max`: number bounds, `value` a number.\n\nOther rule types are stored but not checked. Use string rules on text-like types and `min`\nand `max` on number types.\n", "items": { "type": "object", "required": [ "type", "value", "message" ], "additionalProperties": false, "properties": { "type": { "type": "string", "description": "`minLength`, `maxLength`, `pattern`, `email`, `min` or `max`." }, "value": { "description": "The rule's argument." }, "message": { "type": "string", "description": "A message for people editing the record." } } } } }, "additionalProperties": false, "description": "Rules checked whenever a record writes this field. Values already stored are not re-checked." }, "default": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "`static` or `dynamic`." }, "value": { "description": "The default value." } }, "required": [ "type", "value" ], "additionalProperties": false, "description": "A default stored with the field. Records are not filled from it; use `settings.defaultValue` for that." }, "settings": { "type": "object", "properties": { "selectOptions": { "type": "array", "description": "`select` and `multiSelect`: the choices, in order. Each is `{ \"value\", \"color\" }` or a bare string. Colours are label families: `red`, `orange`, `amber`, `olive`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Values are stored as sent; keep them unique.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "value", "color" ], "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The option's text, which is what records store." }, "color": { "type": "string", "description": "A label colour family." } } } ] } }, "currencyOptions": { "type": "object", "additionalProperties": false, "description": "`currency`: how the web app formats amounts.", "properties": { "currency": { "type": "string", "description": "A two-letter country code whose currency is used, for example `US` for US dollars." }, "display": { "type": "string", "description": "`symbol`, `code` or `name`." } } }, "defaultValue": { "description": "The value a new record gets when it is created without one (missing, null or an empty string). Must fit the field's type, or record creation fails." }, "aiRunStatus": { "type": "string", "enum": [ "RUNNING", "PENDING", "FINISHED", "ERROR", "" ], "description": "A display status for an AI column. The web app sends `PENDING` when it saves an AI column without running it." }, "abbreviateNumber": { "type": "boolean", "description": "`number` and `currency`: show large values as 1.2k, 3.4M and so on." } }, "additionalProperties": false, "description": "Replaces all of the field's settings. Include every key you want to keep, for example the current `currencyOptions` when you change `abbreviateNumber`." }, "permissions": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "organization" ], "description": "`organization` or `private`." }, "editableBy": { "type": "object", "additionalProperties": false, "description": "Who may edit the field when it is private.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names: `OWNER`, `ADMIN`, `MEMBER`, `STAFF`, `SUPPORT`, `SUPER_ADMIN`, `AGENCY`." }, "users": { "type": "array", "items": { "type": "string" }, "description": "User ids." } } }, "viewableBy": { "type": "object", "additionalProperties": false, "description": "Who may view the field when it is private.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names, as in `editableBy`." }, "users": { "type": "array", "items": { "type": "string" }, "description": "User ids." } } } }, "required": [ "visibility", "editableBy", "viewableBy" ], "additionalProperties": false, "description": "Who may view and edit the field. With `organization`, every member who can see the object may. With `private`, only the listed roles and users. Send both `roles` and `users` in each list." }, "runImmediately": { "type": "boolean", "description": "true starts a worker run now that fills this field on every record of the object, using credits for each record. It only runs when the field was already an AI column before this request; to turn on AI and run, send two requests. Default false." } }, "additionalProperties": false, "minProperties": 1 }, "examples": { "relabel": { "summary": "Rename the label", "value": { "displayName": "Partner level" } }, "options": { "summary": "Replace the options", "value": { "settings": { "selectOptions": [ { "value": "Gold", "color": "amber" }, { "value": "Silver", "color": "gray" }, { "value": "Bronze", "color": "orange" }, { "value": "Registered", "color": "blue" } ] } } }, "move": { "summary": "Move the field to position 2", "value": { "sequence": 2 } } } } } }, "summary": "Update a field", "description": "Changes one field of an object (base schema). Send at least one property; properties you leave\nout are kept. Each property you send replaces the stored one completely: `settings`, `type`,\n`permissions`, `validation`, `aiPrompt` and `default` are not merged, so send the whole object.\nThe response is the whole object with all of its fields.\n\n\n| Change | Effect on records |\n|---|---|\n| `displayName`, `description`, `icon`, `isHiddenField`, `unique` | Display only. |\n| `required`, `validation` | Apply to later record writes. Stored values are not re-checked. |\n| `settings.selectOptions` | Replaces the options. Records holding a removed option keep it. On a board's lane field, lanes are added and removed to match. |\n| `settings` (any key) | Replaces all settings: include the keys you want to keep. |\n| `sequence` | Moves the field to that position (starting at 1); the fields in between shift by one. |\n| `isAIEnabled` | Turns the AI column on or off and resets each record's AI status. Stored values are kept. |\n| `type` | Refused with 400 while any record of the object holds a value for the field, including the empty value every record gets when a field is added. When accepted, stored values are not converted. |\n| `name` (the key) | Values are not moved. See the warning. |\n| `permissions` | Replaces who may view and edit the field. |", "x-mint": { "href": "/api-reference/schemas/update-a-field", "metadata": {}, "content": "\nChanging `name` changes the field's key but leaves every record's value under the old key,\nwhere no field reads it, so the values stop showing. The API does not check that the new key is\nfree either. Treat the key as fixed and change `displayName` instead.\n\n\nIn the Heliyos MCP server: [`heliyos_fields_update`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-update)." } }, "delete": { "operationId": "deleteBaseSchemaField", "tags": [ "Schemas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "6730b1c4d3e5f6a7b8c9d0e1" }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The field's `id`, from Get an object.", "example": "6730c2d5e4f6a7b8c9d0e1f2" } ], "responses": { "200": { "description": "The field and its values were deleted. `data` is an empty object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Schema attribute deleted successfully" }, "data": {} } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace, or no field with this id on it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a field", "description": "Deletes one field of an object (base schema) and removes its value from every record,\npermanently.\n\nThe API does not protect any field: built-in fields such as a company's `company_name`, the\nfield a board's lanes come from, and relationship fields are deleted like any other. Deleting a\nrelationship field leaves the matching field on the other object unchanged.", "x-mint": { "href": "/api-reference/schemas/delete-a-field", "metadata": {}, "content": "\nThis removes the field and its value on every record of the object. It cannot be undone.\n\n\nIn the Heliyos MCP server: [`heliyos_fields_delete`](/mcp/tools/workspace-objects-and-fields#heliyos-fields-delete)." } } }, "/v1/platform/base-schemas/{id}/records": { "get": { "operationId": "listRecords", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "66a0f1e2d3c4b5a697880003" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Records per page, 1 to 100. Defaults to 20. In page-number mode it is the page size when `filters.pageSize` is not sent.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid in cursor mode: no sort and no board in `filters`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1. Switches to page-number paging. `filters.page` takes precedence when both are sent.", "example": 1 }, { "name": "filters", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20000, "description": "JSON-encoded filter object (search, filters, sort, page, pageSize, bypassPageSizeCap). Optional. pageSize above its bound is clamped: 200, or 5000 with bypassPageSizeCap: true." }, "description": "A JSON object, URL-encoded, at most 20,000 characters. No key may start with `$` or contain a dot.\nKeys:\n- `search` (string): matches records where any field value contains the text, ignoring case.\n Text, numbers and booleans are searched; lists, objects and values longer than 100 characters\n are not. Results are not ranked by relevance; they keep the mode's order or your `sort`.\n- `filters` (array, at most 500): conditions `{ \"field\", \"operator\", \"value\", \"conjunction\" }`.\n - `field`: a field key, or `createdAt`, `updatedAt` or `isAgentAssigned` (watched). Anything from\n the first `-` on is ignored. `.` (for example `company.company_name`)\n compares values stored on the record's links, not the linked record itself.\n - `operator`: `equals`, `notEquals` (exact match; text ignores case); `contains`, `notContains`,\n `startsWith`, `endsWith` (text, ignoring case; `value` must be a string, and a comma in a\n `contains` or `notContains` value means any or none of the parts); `empty`, `notEmpty`\n (missing, null or `\"\"`; no value); `greaterThan`, `greaterThanOrEqual`, `lessThan`,\n `lessThanOrEqual` (numbers); `after`, `before` (dates, the same as `greaterThan` and\n `lessThan`). Any other operator is treated as an exact match on the raw value.\n - `value`: a string, number or boolean. A string that looks like a number is compared as a number.\n Date fields are stored as text, so send ISO 8601 dates (`2026-12-31`). For `createdAt` and\n `updatedAt` the value is read as a date, and `equals` matches the whole day.\n - `conjunction`: `and` (default) or `or`. The first condition's is ignored; every other condition\n must use the same one. Mixing `and` and `or` is a 400.\n- `sort` (array): `{ \"field\", \"direction\" }`, with the same field names as conditions and\n direction `asc` or `desc`. Text sorts ignore case. Sorting by `.` leaves\n out records without a link of that type.\n- `page` (integer, at least 1) and `pageSize` (integer, at least 1): page-number paging.\n- `bypassPageSizeCap` (boolean): raises the page size cap from 100 to 5000.\n- `isAgentAssigned` (boolean): `true` for watched records only, `false` for the others.\n- `enrich` (boolean, default `true`): `false` leaves out linked records' values and returns 0 for\n the activity counts. Faster for pickers.\n- `viewType` (`kanban`) with `kanbanConfig.groupByField` (a field key, default `status`): return\n a board grouped by that field.", "example": "{\"search\":\"northwind\",\"filters\":[{\"field\":\"stage\",\"operator\":\"equals\",\"value\":\"Negotiation\"}]}" } ], "responses": { "200": { "description": "A page of records, or a board when `filters.viewType` is `kanban`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "description": "The records. With `\"viewType\": \"kanban\"`, an array of `RecordKanbanColumn` instead.", "items": { "$ref": "#/components/schemas/Record" } } } }, "example": { "meta": { "message": "Objects fetched successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6721c3d5e6f7a8b9c0d1e2f3", "baseSchemaId": "66a0f1e2d3c4b5a697880003", "organizationId": "66a0f1e2d3c4b5a697887766", "objectType": "deals", "data": { "deal_name": "Northwind Traders renewal", "stage": "Negotiation", "deal_value": 48000, "close_date": "2026-12-15", "assigned_to": [ { "id": "66a0f1e2d3c4b5a697881111", "firstName": "Dana", "lastName": "Reyes", "email": "dana@example.com" } ] }, "relationships": [ { "_id": "6721c3d5e6f7a8b9c0d1e2f4", "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "website": "https://northwind.example" } } ], "isAgentAssigned": false, "aiColumnStatus": {}, "commentCount": 1, "noteCount": 2, "taskCount": 1, "metadata": { "created": { "at": "2026-11-02T14:10:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ] } } } }, "400": { "description": "VALIDATION_FAILED: `filters` is not a JSON object, carries a `$` or dotted key, mixes `and` and `or`, gives a text operator a non-string value, or `cursor` is sent with a sort or a board. A query the database rejects (for example a malformed sort) answers \"Error fetching records\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not view this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List records", "description": "Returns the records of one object (base schema), such as your companies, people, deals or a custom\nobject. Get the object's id and its field keys from the Objects endpoints.\n\nEach record's `data` holds only the object's fields. A field you may not view comes back as `null`.\nEvery record also carries its links in `relationships` (each with the linked record's field values in\n`data`) and counts of linked comments, notes and open tasks.\n\n**Paging.** There are two modes.\n\n- **Cursor (default).** Send `limit` (1 to 100, default 20). Records come newest first (by creation).\n When `meta.pagination.next_cursor` is present, send it back as `cursor` for the next page.\n- **Page number.** Used as soon as you send `page` (query or `filters`), `filters.pageSize`, a\n `filters.sort` or a board (`\"viewType\": \"kanban\"`). Without a sort, records come most recently\n updated first. `meta.pagination` is `{ page, limit, totalPages, count, hasMore }`, where `count` is\n the number of matching records and `limit` is the page size actually used. A `cursor` together\n with a sort or a board is a 400.\n\n**Page size in page-number mode** is `filters.pageSize`, or `limit` when you do not send one. It is\ncapped at 100. With `\"bypassPageSizeCap\": true` it can go up to 5000, for callers that need a\ncomplete set in one response. A `pageSize` above 200 (5000 with the bypass) is clamped rather than\nrejected.\n\n**Filtering.** Send a JSON object in `filters`, URL-encoded. Its keys are described on the parameter\nbelow. For example, deals in negotiation worth at least 50,000 that mention \"northwind\", soonest\nclose date first, 50 per page:\n\n```json\n{\n \"search\": \"northwind\",\n \"filters\": [\n {\n \"field\": \"stage\",\n \"operator\": \"equals\",\n \"value\": \"Negotiation\"\n },\n {\n \"field\": \"deal_value\",\n \"operator\": \"greaterThanOrEqual\",\n \"value\": 50000,\n \"conjunction\": \"and\"\n }\n ],\n \"sort\": [\n {\n \"field\": \"close_date\",\n \"direction\": \"asc\"\n }\n ],\n \"page\": 1,\n \"pageSize\": 50\n}\n```\n\n`curl -G --data-urlencode` encodes the JSON into the query string for you:\n\n```bash\ncurl -G \"https://api-prod.heliyos.ai/v1/platform/base-schemas/66a0f1e2d3c4b5a697880003/records\" \\\n -H \"Authorization: Bearer heliyos_...\" \\\n --data-urlencode 'filters={\n \"search\": \"northwind\",\n \"filters\": [\n {\n \"field\": \"stage\",\n \"operator\": \"equals\",\n \"value\": \"Negotiation\"\n },\n {\n \"field\": \"deal_value\",\n \"operator\": \"greaterThanOrEqual\",\n \"value\": 50000,\n \"conjunction\": \"and\"\n }\n ],\n \"sort\": [\n {\n \"field\": \"close_date\",\n \"direction\": \"asc\"\n }\n ],\n \"page\": 1,\n \"pageSize\": 50\n '}'\n```\n\n**Boards.** With `\"viewType\": \"kanban\"` the response groups records by a field instead of paging\nthem: `data` is an array of `RecordKanbanColumn` (`columnId`, `items`, `pagination`) holding every\nmatching record, and `meta.pagination` is `{ page, limit, totalCount }`.\n\nSee [Pagination](/api-reference/pagination) and [Filtering and sorting](/api-reference/filtering).", "x-mint": { "href": "/api-reference/records/list-records", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_list`](/mcp/tools/records#heliyos-records-list), [`heliyos_watchlist_get`](/mcp/tools/watchlist#heliyos-watchlist-get)." } }, "post": { "operationId": "createRecord", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The id of the object to create the record in.", "example": "66a0f1e2d3c4b5a697880003" } ], "responses": { "201": { "description": "The created record, as stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Record" } } }, "example": { "meta": { "message": "Object created successfully" }, "data": { "_id": "6721c3d5e6f7a8b9c0d1e2f3", "baseSchemaId": "66a0f1e2d3c4b5a697880003", "organizationId": "66a0f1e2d3c4b5a697887766", "objectType": "deals", "data": { "deal_name": "Northwind Traders renewal", "stage": "Negotiation", "deal_value": 48000, "close_date": "2026-12-15", "assigned_to": [ { "id": "66a0f1e2d3c4b5a697881111", "firstName": "Dana", "lastName": "Reyes", "email": "dana@example.com" } ] }, "relationships": [ { "_id": "6721c3d5e6f7a8b9c0d1e2f4", "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "enrichmentDate": null, "isAgentAssigned": false, "aiColumnStatus": {}, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a required field is missing or a value does not match its field's type or rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id, or a `relationships` id is not a record in this workspace. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: a company with this website, or a person with this email, already exists in the object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "description": "Ids of records to link to the new record, for example a person's company. Each must be a record in this workspace; otherwise nothing is created and the call is a 404." }, "": { "description": "One property per field you set, named by the field's key (for example `deal_name` or `stage`). The value's shape depends on the field's type; see the table above." } }, "additionalProperties": true, "description": "Field values keyed by the object's field keys, plus `relationships`." }, "example": { "deal_name": "Northwind Traders renewal", "stage": "Negotiation", "deal_value": 48000, "close_date": "2026-12-15", "assigned_to": [ { "id": "66a0f1e2d3c4b5a697881111", "firstName": "Dana", "lastName": "Reyes", "email": "dana@example.com" } ], "relationships": [ "66f1a8c3e4b0a1b2c3d4e5f6" ] } } } }, "summary": "Create a record", "description": "Creates a record in an object. Send the field values at the top level of the body, keyed by the\nobject's field keys (for example `company_name`, `website`, `people_name`, `email`, `deal_name`,\n`stage`), and the ids of records to link in `relationships`.\n\n**Values by field type.** Every type also accepts `null` and `\"\"`.\n\n| Field type | Value |\n| --- | --- |\n| `text`, `richText`, `phone`, `select` | A string. A `select` value is not checked against the field's options. |\n| `email` | An email address. |\n| `url` | A full URI, for example `https://northwind.example`. |\n| `number`, `currency`, `rating` | A number. |\n| `checkbox` | `true` or `false`. |\n| `date`, `timestamp` | An ISO 8601 date or date-time string. It is stored as sent. |\n| `multiSelect` | An array of strings. |\n| `user` | An array. The app stores team members as `{ \"id\", \"firstName\", \"lastName\", \"email\" }`. |\n| `image` | An object. |\n| `file` | An array of `{ \"fileName\", \"url\" }` objects, optionally with `attachmentId`, `fileSize`, `mimeType`, `storageKey`, `uploadedAt`. |\n| `relationship` | Any value. |\n\n**What is written.**\n- Fields the object marks required must be included.\n- Only fields you may edit are written. Other keys, including keys that are not fields of the object,\n are dropped without an error. Keys that start with `$` or contain a dot are dropped too.\n- Field keys with a dot, such as `company.company_name` on people and deals, show a linked record's\n value. Set them by linking that record in `relationships`.\n- A field you leave out gets its configured default value, if it has one.\n- Companies start with `account_status` and `engagement_status` set to `unknown` unless you send them,\n and get a `logo` built from `website` when you send no logo. Companies and people start with\n `enrichmentStatus` `NOT_ENRICHED`.\n- A company whose `website`, or a person whose `email`, exactly matches an existing record of the\n same object is refused with a 409.\n- Each linked record gets a link back to the new record.\n\n**Side effects.** The create fires the `company.created`, `people.created`, `deal.created` (or custom\ntype) event, which can start workers that subscribe to it. A new deal sends the workspace's deal\nnotification email when deal notifications are on. Companies, people and deals are sent to HubSpot\nwhen the workspace syncs with it. A new company is enriched automatically when automatic enrichment\nis on (Settings, Autopilot), which uses credits.", "x-mint": { "href": "/api-reference/records/create-a-record", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_create`](/mcp/tools/records#heliyos-records-create)." } } }, "/v1/platform/records/{id}": { "get": { "operationId": "getRecord", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The record's id.", "example": "6721c3d5e6f7a8b9c0d1e2f3" } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Record" } } }, "example": { "meta": { "message": "Object fetched successfully" }, "data": { "_id": "6721c3d5e6f7a8b9c0d1e2f3", "id": "6721c3d5e6f7a8b9c0d1e2f3", "baseSchemaId": "66a0f1e2d3c4b5a697880003", "organizationId": "66a0f1e2d3c4b5a697887766", "objectType": "deals", "data": { "deal_name": "Northwind Traders renewal", "stage": "Negotiation", "deal_value": 48000, "close_date": "2026-12-15" }, "relationships": [ { "_id": "6721c3d5e6f7a8b9c0d1e2f4", "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "fullData": { "_id": "66f1a8c3e4b0a1b2c3d4e5f6", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "website": "https://northwind.example" } } } ], "notes": [ { "_id": "6720b1f4c2a9e3d1f0a4b5c6", "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1." } ], "tasks": [], "isAgentAssigned": false, "aiColumnStatus": {}, "metadata": { "created": { "at": "2026-11-02T14:10:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not view this record's object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a record", "description": "Returns one record by id, from any object. Record ids are unique across objects.\n\n`data` holds only the object's fields; a field you may not view is `null`. Each entry in\n`relationships` carries the complete linked record in `fullData`. The response also includes every\nnote (`notes`) and task (`tasks`) linked to the record, newest first.", "x-mint": { "href": "/api-reference/records/get-a-record", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_get`](/mcp/tools/records#heliyos-records-get), [`heliyos_records_lookup`](/mcp/tools/records#heliyos-records-lookup), [`heliyos_records_update`](/mcp/tools/records#heliyos-records-update)." } }, "patch": { "operationId": "updateRecord", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The record's id.", "example": "6721c3d5e6f7a8b9c0d1e2f3" } ], "responses": { "200": { "description": "The updated record, as stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Record" } } }, "example": { "meta": { "message": "Object updated successfully" }, "data": { "_id": "6721c3d5e6f7a8b9c0d1e2f3", "baseSchemaId": "66a0f1e2d3c4b5a697880003", "organizationId": "66a0f1e2d3c4b5a697887766", "objectType": "deals", "data": { "deal_name": "Northwind Traders renewal", "stage": "Won", "deal_value": 52000, "close_date": "2026-12-15" }, "relationships": [ { "_id": "6721c3d5e6f7a8b9c0d1e2f4", "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-02T14:10:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T10:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a value does not match its field's type or rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this object, or the update changes a field you may not edit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "relationships": { "type": "array", "description": "Ids of records to link. Adds to the existing links.", "items": { "$ref": "#/components/schemas/ObjectId" } }, "": { "description": "A new value for the field with this key. `null` clears it." } }, "additionalProperties": true, "description": "The field values to change, keyed by field key, plus optional `relationships`. May be empty. Keys that start with `$` or contain a dot are dropped. Keys that are not fields of the object are not rejected, but list and get never return them, so send field keys only." } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "stage": "Won", "deal_value": 52000 } } } } }, "summary": "Update a record", "description": "Changes some of a record's field values. Send them in `data`, keyed by field key, with the same value\nshapes as Create a record.\n\n**Fields you leave out keep their values.** Each key you send replaces that one field's value; send\n`null` to clear a field. Required fields only need to be sent when you change them.\n\n**Permissions.** Changing a field you may not edit is a 403 and writes nothing. Sending such a field\nwith its current value (or `null` for a field you may not view) is accepted and ignored, so you can\nsend back a whole record you read.\n\n**Links.** `data.relationships` adds links to the records you name and never removes existing ones.\nEach newly linked record gets a link back. Ids that are not records in this workspace are not\nlinked, and the call fails when none of the new ids is. To remove links, use\n`DELETE /v1/platform/records/{id}/relationships`.\n\n**Side effects.** Changing a company's `website` rebuilds its `logo` (or clears it). The update fires\nthe `.updated` event and, when any value changed, `.attribute_updated` with the changed\nfield keys; workers can subscribe to either. A deal update sends the workspace's deal notification\nemail when deal notifications are on, and synced records are updated in HubSpot. Enrichment status\ncannot be changed here.", "x-mint": { "href": "/api-reference/records/update-a-record", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_update`](/mcp/tools/records#heliyos-records-update)." } } }, "/v1/platform/base-schemas/{id}/records/bulk-delete": { "post": { "operationId": "bulkDeleteRecords", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The id of the object the records belong to.", "example": "66a0f1e2d3c4b5a697880003" } ], "responses": { "200": { "description": "The records were deleted. `data` is an empty object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Objects deleted successfully" }, "data": {} } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not edit this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id, or none of the ids is a record of this object. Nothing is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "objectIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "minItems": 1, "maxItems": 1000, "description": "Ids of the records to delete, 1 to 1000." } }, "required": [ "objectIds" ], "additionalProperties": false }, "example": { "objectIds": [ "6721c3d5e6f7a8b9c0d1e2f3", "6721c3d5e6f7a8b9c0d1e2f5" ] } } } }, "summary": "Delete records", "description": "Permanently deletes up to 1000 records of one object in a single call.\n\nIds that are not records of this object are ignored. The response does not say how many records\nwere deleted. Deleting removes the records from every other record's `relationships`. Notes and\ntasks linked to them are kept. Each deleted record fires the `.deleted` event, and records\nsynced to HubSpot are deleted there too.", "x-mint": { "href": "/api-reference/records/delete-records", "metadata": {}, "content": "Deleting records cannot be undone. Linked records lose their links to the deleted records.\n\nIn the Heliyos MCP server: [`heliyos_records_delete`](/mcp/tools/records#heliyos-records-delete)." } } }, "/v1/platform/base-schemas/{id}/records/lookup": { "get": { "operationId": "listRecordLookup", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The object's id.", "example": "66a0f1e2d3c4b5a697880001" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 1000 }, "description": "The most records to return, 1 to 2000. Defaults to 1000.", "example": 1000 } ], "responses": { "200": { "description": "The index rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLookupRow" } } } }, "example": { "meta": { "message": "Object lookup fetched successfully" }, "data": [ { "id": "66f1a8c3e4b0a1b2c3d4e5f6", "name": "Northwind Traders", "imageUrl": "https://img.logo.example/northwind.example", "isWatched": true, "updatedAt": "2026-11-04T09:30:00.000Z" }, { "id": "66f1a8c3e4b0a1b2c3d4e5f7", "name": "Contoso", "isWatched": false, "updatedAt": "2026-11-03T16:05:00.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you may not view this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no object with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List record names", "description": "Returns a compact index of an object's records, for searching by name on your side: each record's id,\ndisplay name, one supporting value, image and watched state. Use it to turn a name into a record id.\n\nThe index holds up to `limit` records, most recently updated first. It takes no search text and has\nno further pages; for older records, use List records with `search`.\nNames and values come only from fields you may view. `meta.count` is the number of rows returned.", "x-mint": { "href": "/api-reference/records/list-record-names", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_lookup`](/mcp/tools/records#heliyos-records-lookup)." } } }, "/v1/platform/records/{id}/timeline": { "get": { "operationId": "listRecordTimeline", "tags": [ "Timeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The record's id (a company, person or deal).", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Entries per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "The page number, starting at 1. Defaults to 1.", "example": 1 } ], "responses": { "200": { "description": "The record's relationship summary and a page of timeline entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "data": { "type": "object", "properties": { "summary": { "type": "string", "description": "The record's current relationship summary, kept up to date by workers. An empty string when the record has none yet." }, "events": { "type": "array", "description": "Timeline entries, newest first.", "items": { "$ref": "#/components/schemas/TimelineEntry" } } } } } }, "example": { "meta": { "message": "Timeline events fetched successfully", "pagination": { "total": 2, "page": 1, "limit": 20, "hasMore": false } }, "data": { "summary": "Northwind Traders is evaluating the Growth plan. Procurement asked for a security review before signing.", "events": [ { "_id": "6728c0a1b2c3d4e5f6a7b8c9", "timestamp": "2026-11-04T06:00:00.000Z", "metadata": { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "relationshipObjectType": "company", "summary": "Ana Silva confirmed budget for Q1 on a pricing call and asked for the security questionnaire by Friday." } }, { "_id": "6727a3f0b2c3d4e5f6a7b8c1", "timestamp": "2026-11-03T06:00:00.000Z", "metadata": { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "relationshipObjectType": "company", "summary": "Sent the proposal to the buying committee. No reply yet." } } ] } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you cannot view records of this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: the record, or its object, is not in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List timeline entries", "description": "Returns the AI-written timeline of a company, person or deal, newest first, together with the\nrecord's current relationship summary.\n\nEntries are written on a schedule, not on every change. A record with no recent activity can\nhave no entries. For the exact change history use List record events, and for the emails and meetings themselves use List interactions with `filters.objectId`.\n\nThis list pages by page number only: send `page` and `limit`. `meta.pagination` holds `total`,\n`page`, `limit` and `hasMore`. The relationship summary is also repeated in `meta.summary`.", "x-mint": { "href": "/api-reference/timeline/list-timeline-entries", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_timeline`](/mcp/tools/timeline-and-activity#heliyos-records-timeline)." } } }, "/v1/platform/records/{id}/events": { "get": { "operationId": "listRecordEvents", "tags": [ "Activities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The record's id: a company, person, deal or custom object record. Ids of tasks, notes and interactions answer 404; for a task's history use List task events.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Events per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. When you send both `cursor` and `page`, `cursor` wins." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` events long." }, { "name": "objectType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Has no effect on records created in Heliyos: the record's own type is always used. Only read for a record with no stored type. Leave it out." }, { "name": "eventType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "string", "maxLength": 2000 } ] }, "description": "Only events of these types. Comma-separated, or repeat the parameter. Exact, case-sensitive values:\n- `AUDIT`: changes made by people and workers.\n- `INTERACTION`: email threads and meetings synced, updated or analysed.\n- `ENRICHMENT`: data enrichment results.", "example": "AUDIT,ENRICHMENT" }, { "name": "operationType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "string", "maxLength": 2000 } ] }, "description": "Only these operations: `CREATE`, `UPDATE`, `DELETE`. Comma-separated, or repeat the parameter.", "example": "UPDATE" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only events at or after this time. An ISO 8601 date or date-time (a date alone means midnight UTC).", "example": "2026-11-01T00:00:00.000Z" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only events at or before this time. An ISO 8601 date or date-time (a date alone means midnight UTC, so send the next day or a full time to include a whole day).", "example": "2026-11-04T23:59:59.999Z" }, { "name": "actorId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only events by this actor, matched exactly against `metadata.actor.uuid`: a user id for a person's changes, a worker run id for a worker's, or `system`.", "example": "66a0f1e2d3c4b5a697881111" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Only events whose change summary contains this text, case-insensitive. Up to 200 characters.", "example": "stage" } ], "responses": { "200": { "description": "A page of events, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordEvent" } } } }, "example": { "meta": { "message": "Events fetched successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6728d2e4b2c3d4e5f6a7b8d0", "timestamp": "2026-11-04T10:12:00.000Z", "metadata": { "eventType": "AUDIT", "operationType": "UPDATE", "objectType": "company", "objectUUID": "66f1a8c3e4b0a1b2c3d4e5f6", "organizationUUID": "66a0f1e2d3c4b5a697887766", "actor": { "type": "USER", "uuid": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel" } }, "changeSummary": "Priya Patel changed the stage of Northwind Traders from Discovery to Proposal.", "originalVersion": { "data": { "company_name": "Northwind Traders", "stage": "Discovery" } }, "updatedVersion": { "data": { "company_name": "Northwind Traders", "stage": "Proposal" } } }, { "_id": "6728c9b0b2c3d4e5f6a7b8cf", "timestamp": "2026-11-04T09:40:00.000Z", "metadata": { "eventType": "AUDIT", "operationType": "CREATE", "objectType": "task", "objectUUID": "6728c9afb2c3d4e5f6a7b8ce", "organizationUUID": "66a0f1e2d3c4b5a697887766", "actor": { "type": "AGENT", "uuid": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c", "name": "Account Researcher" } }, "changeSummary": "Account Researcher created the task Send security questionnaire to Northwind Traders.", "originalVersion": null, "updatedVersion": { "title": "Send security questionnaire to Northwind Traders", "status": "backlog", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company" } ] } } ] } } } }, "400": { "description": "VALIDATION_FAILED: a malformed query value or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you cannot view records of this object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace, or the id belongs to a task, note or interaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List record events", "description": "Serves records only (companies, people, deals and custom objects). Heliyos looks the record up,\nchecks that you may view its object, and uses the record's own object type. For a task use\nList task events.\n\nReturns the change history of a company, person or deal, newest first: who created, changed\nor deleted what, and when, with a one-line summary of each change and before and after\nsnapshots.\n\nThe list includes the record's own events and the events of anything linked to it: a task,\nnote, email thread, meeting, comment, file or other record whose `relationships` names this\nrecord in either snapshot. Check `metadata.objectType` and `metadata.objectUUID` to tell them apart.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor`. Sending `page` switches to page-number paging, where `meta.pagination` holds\n`page`, `limit`, `total` and `hasMore`. See [Pagination](/api-reference/pagination).\n\nFilters combine with AND. `eventType` and `operationType` match any of the values you send.", "x-mint": { "href": "/api-reference/activities/list-record-events", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_records_events`](/mcp/tools/timeline-and-activity#heliyos-records-events)." } } }, "/v1/platform/tasks/{id}/events": { "get": { "operationId": "listTaskEvents", "tags": [ "Activities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The task's id. Ids of companies, people, deals, custom object records, notes and interactions answer 404; for a record's history use List record events.", "example": "6728c9afb2c3d4e5f6a7b8ce" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Events per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. When you send both `cursor` and `page`, `cursor` wins." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` events long." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000 }, "description": "Only these fields of `originalVersion` and `updatedVersion`, comma-separated, for example `title,status,relationships.objectId`. Up to 30 field paths, each one to three dot-separated names of letters, digits and `_` (starting with a letter or `_`, up to 64 characters each). `_id`, `timestamp`, `metadata` and `changeSummary` are always returned. Leave it out for whole snapshots.", "example": "title,status,dueDate" } ], "responses": { "200": { "description": "A page of the task's events, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskEvent" } } } }, "example": { "meta": { "message": "Task events fetched successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6728e1a0b2c3d4e5f6a7b8e2", "timestamp": "2026-11-04T15:20:00.000Z", "metadata": { "eventType": "AUDIT", "operationType": "UPDATE", "objectType": "task", "objectUUID": "6728c9afb2c3d4e5f6a7b8ce", "organizationUUID": "66a0f1e2d3c4b5a697887766", "actor": { "type": "USER", "uuid": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel" } }, "changeSummary": "Priya Patel moved Send security questionnaire to Northwind Traders from Backlog to In progress.", "originalVersion": { "title": "Send security questionnaire to Northwind Traders", "status": "backlog", "dueDate": "2026-11-08T00:00:00.000Z" }, "updatedVersion": { "title": "Send security questionnaire to Northwind Traders", "status": "in_progress", "dueDate": "2026-11-08T00:00:00.000Z" } }, { "_id": "6728c9b0b2c3d4e5f6a7b8cf", "timestamp": "2026-11-04T09:40:00.000Z", "metadata": { "eventType": "AUDIT", "operationType": "CREATE", "objectType": "task", "objectUUID": "6728c9afb2c3d4e5f6a7b8ce", "organizationUUID": "66a0f1e2d3c4b5a697887766", "actor": { "type": "AGENT", "uuid": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c", "name": "Account researcher" } }, "changeSummary": "Account researcher created the task Send security questionnaire to Northwind Traders.", "originalVersion": null, "updatedVersion": { "title": "Send security questionnaire to Northwind Traders", "status": "backlog", "dueDate": "2026-11-08T00:00:00.000Z" } } ] } } } }, "400": { "description": "VALIDATION_FAILED: a malformed query value or cursor, or a `fields` value that is not up to 30 comma-separated field paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you cannot view tasks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no task with this id in the workspace (including a task that was deleted), or the id belongs to a record, note or interaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List task events", "description": "Serves tasks only. The id must be a task's; any other id answers 404. For a company, person,\ndeal or custom object record use List record events.\n\nReturns the change history of one task, newest first: who created or changed it, when, a\none-line summary of each change, and before and after snapshots of the task.\n\nThe two lists differ in scope. List record events folds in the events of everything linked to\nthe record (its tasks, notes, emails, meetings, comments and files). This list holds only the\ntask's own changes: a note or comment linked to the task does not appear here. The task's own\nchanges also show up in List record events of every record the task is linked to.\n\nChanges made by people (in the app or through the API) and by workers are both recorded. An\nevent is written just after the change it describes, so a change you have just made can take a\nmoment to appear. A worker write that changes nothing a person would see (for example only its\nown run bookkeeping) is not recorded.\n\nThis list has no filters: no event type, operation, date, actor or text search. Read the pages\nand filter on `metadata.operationType` and `metadata.actor` yourself.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor`. Sending `page` switches to page-number paging, where `meta.pagination` holds\nonly `page` and `limit` (no total and no `hasMore`): a page shorter than `limit` is the last\none. See [Pagination](/api-reference/pagination).\n\nTask snapshots can be large. Send `fields` to get back only the parts of each snapshot you read.", "x-mint": { "href": "/api-reference/activities/list-task-events", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_tasks_events`](/mcp/tools/tasks#heliyos-tasks-events)." } } }, "/v1/platform/interactions": { "get": { "operationId": "listInteractions", "tags": [ "Interactions" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Interactions per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid without a `sort` (a 400 otherwise). When you send both `cursor` and `page`, `cursor` wins." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` interactions long." }, { "name": "filters", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20000, "description": "JSON-encoded filter object (search, filters, sort, page, pageSize). Optional. pageSize above 200 is clamped to 200." }, "description": "A JSON object, URL-encoded. Keys:\n- `objectId` (id): only interactions linked to this record.\n- `channelType` (string or array): `email`, `meeting`, or both (an array or a comma-separated string).\n- `categoryIds` (string or array): only interactions with any of these label ids.\n- `search` (string): case-insensitive text match on the subject, title, summary, message\n previews, takeaways, transcript and participant addresses.\n- `uniqByRelationships` (any non-empty value): keep one interaction per distinct set of linked records.\n- `sort` (array): `{ \"field\", \"direction\" }` with direction `asc` or `desc`. Useful fields:\n `thread_date` (newest email message), `start_time` (meeting start), `createdAt` (when synced).\n- `filters` (array): conditions `{ \"field\", \"operator\", \"value\", \"conjunction\" }`. Conditions with\n `\"conjunction\": \"and\"` must all match. Conditions without it, or with `\"or\"`, are combined with OR,\n so set `\"conjunction\": \"and\"` on every condition you need to hold. Operators: `equals`, `not_equals`,\n `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty`, `in`, `not_in`,\n `greater_than`, `less_than`, `greater_than_equal`, `less_than_equal`, `after`, `before`, `between`\n (value `{\"startDate\",\"endDate\"}` as a JSON string), and `is` / `is_not` for `participants`.\n Special fields: `channelType`, `categoryIds`, `participants` (meeting invitee addresses),\n `hasAgentDraft` (true for threads holding a worker's unsent draft), and\n `relationships..` to match a linked record's field value, for example\n `relationships.company.company_name`.\n- `page` and `pageSize`: page-number paging. `pageSize` is capped at 200.", "example": "{\"objectId\":\"66f1a8c3e4b0a1b2c3d4e5f6\",\"channelType\":\"email\",\"sort\":[{\"field\":\"thread_date\",\"direction\":\"desc\"}]}" } ], "responses": { "200": { "description": "A page of interactions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Interaction" } } } }, "example": { "meta": { "message": "Meetings fetched successfully.", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6728b1c2d3e4f5a6b7c8d9e0", "organizationId": "66a0f1e2d3c4b5a697887766", "integrationId": "66a0f1e2d3c4b5a697885555", "channel": { "type": "email", "email": "priya@example.com" }, "subject": "Security questionnaire for Northwind Traders", "thread_id": "thr_7f3a9c", "threads": [ { "message_id": "msg_91b2", "thread_id": "thr_7f3a9c", "subject": "Security questionnaire for Northwind Traders", "snippet": "Hi Priya, attached is our standard questionnaire. Could you return it by Friday?", "date": 1762250400, "from": [ { "name": "Ana Silva", "email": "ana.silva@northwind.example.com" } ], "to": [ { "name": "Priya Patel", "email": "priya@example.com" } ], "cc": [], "unread": false, "starred": false } ], "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "schemaId": "66a0f1e2d3c4b5a697880001", "object": { "_id": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "isAgentAssigned": true, "data": { "company_name": "Northwind Traders", "domain": "northwind.example.com" } } } ], "categoryIds": [], "classificationLabels": [], "summary": "Northwind sent its security questionnaire and wants it back by Friday.", "sentiment": "Positive", "sentimentReason": "The buyer is moving the deal forward.", "isSummarized": true, "createdAt": "2026-11-04T10:00:05.000Z" }, { "_id": "6728b1c2d3e4f5a6b7c8d9e1", "organizationId": "66a0f1e2d3c4b5a697887766", "integrationId": "66a0f1e2d3c4b5a697885556", "channel": { "type": "meeting", "email": "priya@example.com" }, "title": "Northwind Traders pricing review", "when": { "start_time": 1762329600, "end_time": 1762331400, "start_timezone": "UTC", "end_timezone": "UTC" }, "participants": [ { "email": "priya@example.com", "status": "yes" }, { "email": "ana.silva@northwind.example.com", "status": "yes" } ], "meetingStatus": "NOT_STARTED", "relationships": [], "summary": "", "sentiment": null, "isSummarized": false, "createdAt": "2026-11-04T10:05:00.000Z" } ] } } } }, "400": { "description": "VALIDATION_FAILED: `filters` is not a JSON object, has a malformed condition or `objectId`, or `cursor` was sent with a sort.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List interactions", "description": "Returns the workspace's synced email threads and meetings, from every connected mailbox and\ncalendar, with their AI analysis and the records they are linked to. Each row is the full\ninteraction, including message bodies and meeting transcripts, so keep `limit` small.\n\nBy default the list pages with a cursor, newest synced first: pass `limit`, then send\n`meta.pagination.next_cursor` back as `cursor`. A `sort`, or `page` (as a parameter or inside\n`filters`), switches to page-number paging, where `meta.pagination` holds `page`, `limit`,\n`totalPages`, `count` and `hasMore`. See [Pagination](/api-reference/pagination).\n\nTo list only the interactions linked to one record, send `{\"objectId\": \"\"}` in `filters`.", "x-mint": { "href": "/api-reference/interactions/list-interactions", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_interactions_list`](/mcp/tools/timeline-and-activity#heliyos-interactions-list)." } } }, "/v1/platform/interactions/{id}": { "get": { "operationId": "getInteraction", "tags": [ "Interactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The interaction's id.", "example": "6728b1c2d3e4f5a6b7c8d9e0" } ], "responses": { "200": { "description": "The interaction.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Interaction" } } }, "example": { "meta": { "message": "Interaction fetched successfully." }, "data": { "_id": "6728b1c2d3e4f5a6b7c8d9e1", "organizationId": "66a0f1e2d3c4b5a697887766", "integrationId": "66a0f1e2d3c4b5a697885556", "channel": { "type": "meeting", "email": "priya@example.com" }, "title": "Northwind Traders pricing review", "when": { "start_time": 1762329600, "end_time": 1762331400, "start_timezone": "UTC", "end_timezone": "UTC" }, "participants": [ { "email": "priya@example.com", "status": "yes" }, { "email": "ana.silva@northwind.example.com", "status": "yes" } ], "creator": { "name": "Priya Patel", "email": "priya@example.com" }, "meetingStatus": "COMPLETED", "transcript": [ { "timestamp": "00:01:12", "speaker": "Ana Silva", "dialogue": "We can commit to the Growth plan if the security review passes." } ], "takeaways": "Budget confirmed for Q1. Security review is the last blocker.", "nextSteps": "Send the security questionnaire answers by Friday.", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "schemaId": "66a0f1e2d3c4b5a697880001", "object": { "_id": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "data": { "company_name": "Northwind Traders" } } } ], "summary": "Pricing review with Northwind Traders. Budget is confirmed and the security review is the last step.", "sentiment": "Positive", "isSummarized": true, "createdAt": "2026-11-04T10:05:00.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no interaction with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get an interaction", "description": "Returns one email thread or meeting with every stored field: all messages and bodies for an\nemail, the transcript and analysis for a meeting, its labels, and the records it is linked to.", "x-mint": { "href": "/api-reference/interactions/get-an-interaction", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_interactions_get`](/mcp/tools/timeline-and-activity#heliyos-interactions-get)." } } }, "/v1/platform/notes": { "get": { "operationId": "listNotes", "tags": [ "Notes" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Notes per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid with the default order (newest first) and no `page`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` notes long." }, { "name": "filters", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20000, "description": "JSON-encoded filter object (search, filters, sort, page, pageSize). Optional. pageSize above 200 is clamped to 200." }, "description": "A JSON object, URL-encoded. Keys:\n- `search` (string): matches text in the title or body, case-insensitive.\n- `relatedObjectId` (id): only notes linked to this record, task or interaction.\n- `filters` (array): conditions `{ \"field\", \"operator\", \"value\" }`. Fields: `title`, `content`,\n `metadata.created.at`, `metadata.created.by`. Operators: `equals`, `not_equals`, `contains`,\n `after`, `before`, `gt`, `gte`, `lt`, `lte`, `in`, `empty`, `not_empty`.\n- `sort` (array): `{ \"field\", \"direction\" }` with direction `asc` or `desc`, for example\n `[{\"field\": \"metadata.updated.at\", \"direction\": \"desc\"}]`.", "example": "{\"search\":\"pricing\",\"relatedObjectId\":\"66f1a8c3e4b0a1b2c3d4e5f6\"}" } ], "responses": { "200": { "description": "A page of notes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } } }, "example": { "meta": { "message": "Notes fetched successfully.", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6720b1f4c2a9e3d1f0a4b5c6", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1. Procurement wants a security review first.", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List notes", "description": "Returns the workspace's notes, newest first.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor` for the next page. To filter, search or sort, send a JSON `filters` object.\nA custom sort or `page` switches to page-number paging. See [Pagination](/api-reference/pagination)\nand [Filtering and sorting](/api-reference/filtering).\n\nTo list only the notes linked to one record, send `{\"relatedObjectId\": \"\"}` in `filters`.", "x-mint": { "href": "/api-reference/notes/list-notes", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notes_list`](/mcp/tools/notes#heliyos-notes-list)." } }, "post": { "operationId": "createNote", "tags": [ "Notes" ], "parameters": [], "responses": { "201": { "description": "The created note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "meta": { "message": "Note created successfully." }, "data": { "_id": "6720b1f4c2a9e3d1f0a4b5c6", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1. Procurement wants a security review first.", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: the resource, or a relationships[] entry naming a record, schema, task, note, comment, chat, list or interaction that is not this organization's (unknown and foreign ids answer alike). Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The note's title. Required, but may be an empty string.", "example": "Pricing call follow-up" }, "content": { "type": "string", "description": "The body, as plain text or simple HTML. May be empty.", "example": "Champion confirmed budget for Q1." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipInput" }, "description": "Records, tasks or interactions to link the note to. Each must belong to this workspace." } }, "required": [ "title" ], "additionalProperties": false }, "example": { "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1. Procurement wants a security review first.", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ] } } } }, "summary": "Create a note", "description": "Creates a note and, optionally, links it to records, tasks or interactions. The note appears on the\ntimeline of every linked record.", "x-mint": { "href": "/api-reference/notes/create-a-note", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notes_create`](/mcp/tools/notes#heliyos-notes-create)." } } }, "/v1/platform/notes/{id}": { "get": { "operationId": "getNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The note's id.", "example": "6720b1f4c2a9e3d1f0a4b5c6" } ], "responses": { "200": { "description": "The note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "meta": { "message": "Note fetched successfully." }, "data": { "_id": "6720b1f4c2a9e3d1f0a4b5c6", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1. Procurement wants a security review first.", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "logo": "https://logo.example/northwind.example" }, "schema": { "_id": "66a0f1e2d3c4b5a697880001", "name": "Companies", "objectType": "company" } } ], "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no note with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a note", "description": "Returns one note with its full body. Each entry in `relationships` is hydrated with a summary of\nthe linked resource in `data` and, for records, the record's object in `schema`.", "x-mint": { "href": "/api-reference/notes/get-a-note", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notes_get`](/mcp/tools/notes#heliyos-notes-get)." } }, "patch": { "operationId": "updateNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The note's id.", "example": "6720b1f4c2a9e3d1f0a4b5c6" } ], "responses": { "200": { "description": "The updated note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "meta": { "message": "Note updated successfully." }, "data": { "_id": "6720b1f4c2a9e3d1f0a4b5c6", "title": "Pricing call follow-up", "content": "Champion confirmed budget for Q1. Security review booked for Nov 12." } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no note with this id, or a relationships entry names a resource outside the workspace. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "A new title. May be an empty string." }, "content": { "type": "string", "description": "A new body. May be an empty string." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipInput" }, "description": "The complete new set of links. Replaces the current links." } }, "additionalProperties": false, "minProperties": 1 }, "example": { "content": "Champion confirmed budget for Q1. Security review booked for Nov 12." } } } }, "summary": "Update a note", "description": "Changes a note's title, body or links. Send at least one field. `relationships`, when sent,\nreplaces the note's links completely: include the existing ones you want to keep.", "x-mint": { "href": "/api-reference/notes/update-a-note", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notes_update`](/mcp/tools/notes#heliyos-notes-update)." } }, "delete": { "operationId": "deleteNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The note's id.", "example": "6720b1f4c2a9e3d1f0a4b5c6" } ], "responses": { "204": { "description": "The note was deleted. The response has no body." }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no note with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a note", "description": "Deletes a note permanently. Its links are removed with it; the linked records are not changed.", "x-mint": { "href": "/api-reference/notes/delete-a-note", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notes_delete`](/mcp/tools/notes#heliyos-notes-delete)." } } }, "/v1/platform/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Tasks per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid with the default order (no `sort`, no `groupBy`); a 400 otherwise. When you send both `cursor` and `page`, `cursor` wins." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` tasks long." }, { "name": "filters", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20000, "description": "JSON-encoded filter object (search, filters, sort, page, pageSize). Optional. pageSize above 200 is clamped to 200." }, "description": "A JSON object, URL-encoded. Keys:\n- `search` (string): matches text in the title or description, case-insensitive.\n- `relatedObjectId` (id): only tasks linked to this record.\n- `filters` (array): conditions `{ \"field\", \"operator\", \"value\", \"conjunction\" }`. Conditions are\n combined with AND; a condition with `\"conjunction\": \"or\"` joins an OR group instead. Operators:\n `equals`, `not_equals`, `contains`, `in` (value is a list), `gt` or `after`, `gte`, `lt` or `before`,\n `lte`, `empty`, `not_empty`. Fields include `status`, `priority`, `title`, `description`, `dueDate`,\n `isFinished` (value `\"true\"` or `\"false\"` as a string), `assignedUser` (matches the assignee's name,\n case-insensitive), `metadata.created.by` (a user id),\n `metadata.created.at` and `metadata.updated.at` (`equals` matches the whole day, plus `after`, `before`).\n- `sort` (array): `{ \"field\", \"direction\" }` with direction `asc` or `desc`, for example\n `[{\"field\": \"dueDate\", \"direction\": \"asc\"}]`. Text sorts ignore case.\n- `groupBy` (string): one of `status`, `priority`, `assignedUser`, `dueDate`, `createdAt`,\n `isFinished`, `title`. Each item in `data` is then a group `{ groupValue, count, tasks }`\n instead of a task. Grouping by `status` or `priority` returns one group per value, each with\n its total `count` and its first `pageSize` tasks. Other groupings return at most 1000 tasks in all.\n- `page` and `pageSize`: page-number paging. `pageSize` is capped at 200.", "example": "{\"relatedObjectId\":\"66f1a8c3e4b0a1b2c3d4e5f6\",\"filters\":[{\"field\":\"status\",\"operator\":\"equals\",\"value\":\"in_progress\"}]}" } ], "responses": { "200": { "description": "A page of tasks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } }, "example": { "meta": { "message": "Tasks fetched successfully.", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6728c9afb2c3d4e5f6a7b8ce", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Send security questionnaire to Northwind Traders", "description": "Fill in the questionnaire Ana sent and return it by Friday.", "status": "in_progress", "priority": "high", "isFinished": false, "dueDate": "2026-11-07T17:00:00.000Z", "assignedUser": [ { "id": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel", "profilePicture": null } ], "assignedAgents": [ { "agentId": "66a0f1e2d3c4b5a697882222", "name": "Account Researcher", "role": "executor" } ], "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "domain": "northwind.example.com" }, "schema": { "_id": "66a0f1e2d3c4b5a697880001", "name": "Companies", "objectType": "company" } } ], "currentRunId": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c", "currentRun": { "status": "awaiting_approval", "planSteps": 3, "completedSteps": 2, "artifactsCount": 1, "lastRunAt": "2026-11-04T10:20:00.000Z" }, "artifactsCount": 1, "agentPaused": false, "metadata": { "created": { "at": "2026-11-04T09:40:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T10:20:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ] } } } }, "400": { "description": "VALIDATION_FAILED: `filters` is not a JSON object, names an unknown `groupBy`, has a malformed condition or `relatedObjectId`, or `cursor` was sent with a sort or grouping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List tasks", "description": "Returns the workspace's tasks, newest first. Each task includes its linked records (with their\nfield values) and the state of the workers' current run.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor` for the next page. A `sort`, `groupBy`, or `page` (as a parameter or inside\n`filters`) switches to page-number paging, where `meta.pagination` holds `page`, `limit`,\n`totalPages`, `count` and `hasMore`. See [Pagination](/api-reference/pagination) and\n[Filtering and sorting](/api-reference/filtering).\n\nTo list only the tasks linked to one record, send `{\"relatedObjectId\": \"\"}` in `filters`.\nTo list one stage, send `{\"filters\": [{\"field\": \"status\", \"operator\": \"equals\", \"value\": \"in_progress\"}]}`.", "x-mint": { "href": "/api-reference/tasks/list-tasks", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_tasks_list`](/mcp/tools/tasks#heliyos-tasks-list)." } }, "post": { "operationId": "createTask", "tags": [ "Tasks" ], "parameters": [], "responses": { "200": { "description": "The created task as stored: its id is in `id` (not `_id`), relationships are not hydrated, and there is no `currentRun` yet.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "meta": { "message": "Task created successfully." }, "data": { "id": "6728c9afb2c3d4e5f6a7b8ce", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Send security questionnaire to Northwind Traders", "description": "Fill in the questionnaire Ana sent and return it by Friday.", "status": "backlog", "priority": "high", "isFinished": false, "dueDate": "2026-11-07T17:00:00.000Z", "assignedUser": [ { "id": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel", "_id": "6728c9afb2c3d4e5f6a7b8d1" } ], "assignedAgents": [], "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "planCheckpoints": [], "agentPaused": false, "metadata": { "created": { "at": "2026-11-04T09:40:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:40:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a field has the wrong type or value (for example an unknown `status` or `priority`), or an id is malformed. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: a relationships entry, assignee or worker is not in this workspace. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The task's title. Required, but may be an empty string.", "example": "Send security questionnaire to Northwind Traders" }, "description": { "type": "string", "description": "The body, as plain text or markdown. May be empty." }, "status": { "type": "string", "enum": [ "backlog", "in_progress", "scheduled_for_later", "on_hold", "cancelled", "completed" ], "allOf": [ { "$ref": "#/components/schemas/TaskStatus" } ], "description": "The stage. Defaults to `backlog`. Setting it does not change `isFinished`." }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high", "urgent" ], "description": "The priority. Defaults to `medium`. Any other value is rejected with a 400." }, "dueDate": { "type": "string", "format": "date-time", "description": "When the task is due, as an ISO 8601 date or date-time.", "example": "2026-11-07T17:00:00.000Z" }, "isFinished": { "type": "boolean", "description": "The done flag. Defaults to false. Send `true` together with `status` `completed`." }, "assignedUser": { "type": "array", "items": { "$ref": "#/components/schemas/TaskAssignee" }, "description": "People to assign. Each `id` must be a member of the workspace (you can always assign yourself); `name` and `profilePicture` are stored as sent for display." }, "assignedAgents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TaskWorkerAssignment" } ], "required": [ "agentId" ] }, "description": "Workers to assign. Each `agentId` is required and must be one of the workspace's workers." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRelationshipInput" }, "description": "Records (or tasks, notes, interactions) to link the task to. At most 200, each in this workspace." } }, "required": [ "title" ], "additionalProperties": false }, "example": { "title": "Send security questionnaire to Northwind Traders", "description": "Fill in the questionnaire Ana sent and return it by Friday.", "status": "backlog", "priority": "high", "dueDate": "2026-11-07T17:00:00.000Z", "assignedUser": [ { "id": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel" } ], "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ] } } } }, "summary": "Create a task", "description": "Creates a task and, optionally, links it to records and assigns people and workers.\n\nAfter the task is saved, Heliyos records an audit event, sends the workspace's task-created\nnotification email if it is turned on, creates the task in HubSpot if HubSpot is connected, and\nfires the `task.created` trigger: workers that subscribe to new tasks can start on it, and their\nruns use credits. Assigning a worker does not start it by itself. To start workers on the task now,\ncall Run workers on a task with the returned id.\n\nCalling this twice creates two tasks.", "x-mint": { "href": "/api-reference/tasks/create-a-task", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_tasks_create`](/mcp/tools/tasks#heliyos-tasks-create)." } } }, "/v1/platform/tasks/{id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The task's id.", "example": "6728c9afb2c3d4e5f6a7b8ce" } ], "responses": { "200": { "description": "The task.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "meta": { "message": "Task fetched successfully." }, "data": { "_id": "6728c9afb2c3d4e5f6a7b8ce", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Send security questionnaire to Northwind Traders", "description": "Fill in the questionnaire Ana sent and return it by Friday.", "status": "in_progress", "priority": "high", "isFinished": false, "dueDate": "2026-11-07T17:00:00.000Z", "assignedUser": [ { "id": "66a0f1e2d3c4b5a697881111", "name": "Priya Patel", "profilePicture": null } ], "assignedAgents": [ { "agentId": "66a0f1e2d3c4b5a697882222", "name": "Account Researcher", "role": "executor" } ], "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "domain": "northwind.example.com" }, "schema": { "_id": "66a0f1e2d3c4b5a697880001", "name": "Companies", "objectType": "company" } } ], "planCheckpoints": [ { "id": "step-1", "kind": "step", "title": "Read the questionnaire", "worker": "account_researcher", "status": "completed" }, { "id": "step-2", "kind": "step", "title": "Draft the answers", "worker": "account_researcher", "status": "completed" }, { "id": "step-3", "kind": "step", "title": "Email the answers to Ana", "worker": "email_writer", "status": "pending" } ], "currentRunId": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c", "currentRun": { "status": "awaiting_approval", "planSteps": 3, "completedSteps": 2, "artifactsCount": 1, "lastRunAt": "2026-11-04T10:20:00.000Z" }, "artifactsCount": 1, "agentPaused": false, "metadata": { "created": { "at": "2026-11-04T09:40:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T10:20:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no task with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a task", "description": "Returns one task with its full description, its linked records (each with the record's field\nvalues in `data` and its object in `schema`), its plan and the state of the workers' current run.", "x-mint": { "href": "/api-reference/tasks/get-a-task", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_tasks_get`](/mcp/tools/tasks#heliyos-tasks-get)." } }, "patch": { "operationId": "updateTask", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The task's id.", "example": "6728c9afb2c3d4e5f6a7b8ce" } ], "responses": { "200": { "description": "The updated task as stored: its id is in `id` (not `_id`) and relationships are not hydrated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "meta": { "message": "Task updated successfully." }, "data": { "id": "6728c9afb2c3d4e5f6a7b8ce", "organizationId": "66a0f1e2d3c4b5a697887766", "title": "Send security questionnaire to Northwind Traders", "status": "completed", "priority": "high", "isFinished": true, "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-04T09:40:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T08:15:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: an empty body, a field with the wrong type or value, or a malformed id. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no task with this id, or a relationships entry, assignee or worker is not in this workspace. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "A new title. May be an empty string." }, "description": { "type": "string", "description": "A new body. May be an empty string." }, "status": { "type": "string", "enum": [ "backlog", "in_progress", "scheduled_for_later", "on_hold", "cancelled", "completed" ], "allOf": [ { "$ref": "#/components/schemas/TaskStatus" } ], "description": "A new stage." }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high", "urgent" ], "description": "A new priority. Use one of these values; an update does not check it." }, "dueDate": { "type": "string", "format": "date-time", "description": "A new due date, as an ISO 8601 date or date-time." }, "isFinished": { "type": "boolean", "description": "The done flag." }, "assignedUser": { "type": "array", "items": { "$ref": "#/components/schemas/TaskAssignee" }, "description": "The complete new list of people. Newly added ids must be workspace members (you can always assign yourself); ids already on the task are kept even if that person has left." }, "assignedAgents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TaskWorkerAssignment" } ], "required": [ "agentId" ] }, "description": "The complete new list of workers. Newly added `agentId`s must be workspace workers; each entry needs `agentId`." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRelationshipInput" }, "description": "The complete new set of links. Replaces the current links. At most 200." } }, "additionalProperties": false, "minProperties": 1 }, "example": { "status": "completed", "isFinished": true } } } }, "summary": "Update a task", "description": "Changes the fields you send and keeps the rest. Send at least one field. `relationships`,\n`assignedUser` and `assignedAgents`, when sent, each replace the whole list: include the entries\nyou want to keep.\n\nSetting `status` does not change `isFinished`; send both when you complete or reopen a task.\nMoving a task off `scheduled_for_later` cancels the worker's pending wake-up.\n\nAfter the write, Heliyos records an audit event, sends the workspace's task-updated notification\nemail if it is turned on, updates the task in HubSpot if it is synced there, and fires a trigger\n(`task.cancelled` when the status changes to `cancelled`, `task.updated` otherwise): workers that\nsubscribe to it can start, and their runs use credits. No trigger fires while workers are paused on\nthe task, or when the change only adds or removes whitespace.", "x-mint": { "href": "/api-reference/tasks/update-a-task", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_tasks_update`](/mcp/tools/tasks#heliyos-tasks-update)." } }, "delete": { "operationId": "deleteTask", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The task's id.", "example": "6728c9afb2c3d4e5f6a7b8ce" } ], "responses": { "200": { "description": "The task was deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Always `Task deleted successfully`." } } } } }, "example": { "meta": { "message": "Task deleted successfully" }, "data": { "message": "Task deleted successfully" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no task with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a task", "description": "Deletes a task permanently. Linked records are not changed. Heliyos records an audit event and\nfires the `task.deleted` trigger (unless workers are paused on the task), so subscribed workers\ncan react.", "x-mint": { "href": "/api-reference/tasks/delete-a-task", "metadata": {}, "content": "Deleting a task cannot be undone.\n\nIn the Heliyos MCP server: [`heliyos_tasks_delete`](/mcp/tools/tasks#heliyos-tasks-delete)." } } }, "/v1/platform/tasks/{id}/runs": { "post": { "operationId": "createTaskRun", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The task's id.", "example": "6728c9afb2c3d4e5f6a7b8ce" } ], "responses": { "200": { "description": "The run that is now working the task.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/TaskRunStart" } } }, "example": { "meta": { "message": "Task run started." }, "data": { "triggered": true, "orchestratorRunId": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c", "status": "queued" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no task with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: the workers did not start, for example because the workspace is out of credits. The message gives the reason. The task is put back as it was.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The workers could not be reached. Nothing started and the task is put back as it was. Try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Run workers on a task", "description": "Starts Heliyos workers on a task now, the same as pressing Play on the task. The call takes no body.\n\nWhat it does, in order:\n1. Clears the task's paused flag and, unless the task is `completed` or `cancelled`, moves it to\n `in_progress` (and sets `isFinished` to false).\n2. Looks for a run already open on the task (`queued`, `running`, `paused`, `awaiting_approval` or\n `waiting`). If there is one, it is returned with `triggered: false` and no new run starts. A\n `queued` or `running` run that has written nothing for 20 minutes is treated as dead and does not count.\n3. Otherwise starts a new run with `triggered: true` and status `queued`. The run starts even when no\n worker subscribes to new tasks, and it cancels any wake-up a worker had scheduled for the task.\n\nThe call returns as soon as the run is queued. Follow it with `GET /v1/platform/workers/runs/{id}`\nusing `orchestratorRunId`.\n\n**Credits.** Each time the run calls one of your custom workers, the workspace is charged a fixed\nnumber of credits; Heliyos's built-in workers are free. If the workspace cannot cover a custom worker\ncall when the run starts, nothing starts and the call answers 409. Actions the workers take (for\nexample enrichment) can use credits of their own.\n\n**Reviews.** Workers write companies, people, tasks, notes and email drafts directly. Deal changes,\nsending email, booking meetings, actions in connected apps and anything a worker asks you to decide\nwait for a person's review unless the workspace's autopilot settings allow them, and even then a call\nbelow the confidence threshold still waits. While an action waits, the run's status is `awaiting_approval`.\n\n**Idempotency.** Calling again while a run is open returns that run. The check is not atomic, so two\ncalls at the same moment can start two runs.", "x-mint": { "href": "/api-reference/tasks/run-workers-on-a-task", "metadata": {}, "content": "This starts workers that act on your data and can spend credits. Writes to companies, people, tasks and notes apply without review; deal changes, emails, meetings and actions in connected apps wait for review unless your autopilot settings allow them.\n\nIn the Heliyos MCP server: [`heliyos_tasks_run`](/mcp/tools/tasks#heliyos-tasks-run)." } } }, "/v1/platform/agents": { "get": { "operationId": "listAgents", "tags": [ "Workers and runs" ], "parameters": [], "responses": { "200": { "description": "Every worker.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Worker" } } } }, "example": { "meta": { "message": "Successful request" }, "data": [ { "_id": "6720f3a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Account researcher", "type": "custom", "isActive": true, "icon": "search", "isExcluded": false, "description": "Researches a company before a first call and writes a brief on the record.", "instructions": "When a meeting is booked with a new company, research it and add a note with...", "toolName": "account_researcher", "toolNames": [ "web_search" ], "actionIds": [], "toolPolicy": { "readOnly": false }, "memory": { "enabled": true }, "resources": { "scope": "everything", "allKbFiles": true, "linkedKbFileIds": [], "fileIds": [] }, "triggers": [ { "type": "event", "events": [ "meeting.booked" ], "source": "user" } ], "runtime": "sandbox", "metadata": { "created": { "at": "2026-10-12T14:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-01T09:20:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } }, "createdAt": "2026-10-12T14:00:00.000Z", "updatedAt": "2026-11-01T09:20:00.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List workers", "description": "Returns every worker in the workspace, default and custom, in one response: custom workers\nfirst, then default ones, each group by name. A workspace has a handful, so the list is not paged.", "x-mint": { "href": "/api-reference/workers-and-runs/list-workers", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_workers_list`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-list)." } }, "post": { "operationId": "createAgent", "tags": [ "Workers and runs" ], "parameters": [], "responses": { "201": { "description": "The created worker, with the outcome of its schedule registration.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WorkerSaved" } } }, "example": { "meta": { "message": "Agent created." }, "data": { "_id": "6720f3a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Account researcher", "type": "custom", "isActive": true, "isExcluded": false, "description": "Researches a company before a first call and writes a brief on the record.", "instructions": "When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities.", "toolName": "account_researcher", "toolNames": [], "actionIds": [], "toolPolicy": { "readOnly": false }, "memory": { "enabled": true }, "resources": { "scope": "everything", "allKbFiles": true, "linkedKbFileIds": [], "fileIds": [] }, "triggers": [ { "type": "event", "events": [ "meeting.booked" ], "source": "user" }, { "type": "scheduled", "events": [], "match": { "schedule": "0 8 * * 1", "timezone": "Europe/Berlin" }, "dependencies": [], "source": "user" } ], "runtime": "sandbox", "metadata": { "created": { "at": "2026-11-05T10:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T10:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } }, "createdAt": "2026-11-05T10:00:00.000Z", "updatedAt": "2026-11-05T10:00:00.000Z", "scheduleSync": { "created": [ "6729c0d1e2f3a4b5c6d7e8f9" ], "deleted": [], "failed": [] } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: an action, file or dependency worker id is not this workspace's. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: a worker with this name already exists. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The worker's name, 1 to 200 characters after trimming. Unique in the workspace.", "example": "Account researcher" }, "description": { "type": "string", "maxLength": 2000, "description": "One line on what the worker is for, up to 2,000 characters. Heliyos reads it to decide when to call the worker.", "example": "Researches a company before a first call and writes a brief on the record." }, "icon": { "type": "string", "maxLength": 100, "description": "An icon name for the Heliyos app, up to 100 characters.", "example": "search" }, "instructions": { "type": "string", "maxLength": 50000, "description": "What the worker does and how, in Markdown, up to 50,000 characters. Defaults to empty.", "example": "When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities." }, "isActive": { "type": "boolean", "description": "`false` creates the worker paused. Defaults to `true`." }, "toolName": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "The snake_case name Heliyos calls the worker by, 1 to 48 characters of `a-z`, `0-9` and `_`. Defaults to one made from `name`. Cannot be changed later.", "example": "account_researcher" }, "toolNames": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 500, "description": "Built-in tools the worker may use, by name. Up to 500. Defaults to none." }, "actionIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 500, "description": "Workspace actions the worker may run. Each must be an action of this workspace. Up to 500." }, "toolPolicy": { "type": "object", "properties": { "readOnly": { "type": "boolean", "description": "`true`: read only." } }, "additionalProperties": false, "description": "`{ readOnly }`: `true` lets the worker read but never change data." }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Memory on or off." } }, "additionalProperties": false, "description": "`{ enabled }`: whether the worker keeps memory across runs. Defaults to on." }, "resources": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "everything", "org_knowledge", "account_files", "selected_files" ] }, "allKbFiles": { "type": "boolean" }, "linkedKbFileIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 1000 }, "fileIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 1000 } }, "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/WorkerResources" } ], "description": "The files the worker reads. Merged over the defaults (`scope` `everything`, every knowledge base file)." }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerTriggerInput" }, "maxItems": 50, "description": "What starts the worker, up to 50 entries. Defaults to none." }, "schedule": { "type": "object", "properties": { "cron": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 }, "description": "5-field cron expressions." } }, "additionalProperties": false, "description": "Legacy. Up to 20 cron expressions in `cron`. Use a `scheduled` trigger instead." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Account researcher", "description": "Researches a company before a first call and writes a brief on the record.", "instructions": "When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities.", "toolPolicy": { "readOnly": false }, "triggers": [ { "type": "event", "events": [ "meeting.booked" ] }, { "type": "scheduled", "match": { "schedule": "0 8 * * 1", "timezone": "Europe/Berlin" } } ] } } } }, "summary": "Create a worker", "description": "Creates a custom worker. It starts active unless you send `isActive: false`, and its triggers\ntake effect at once.\n\nWhat you leave out gets a default: empty instructions, no tools or actions, memory on, and every\nknowledge base file linked. `toolName` is made from the name (lowercase, other characters as `_`,\nat most 48 characters) unless you send one. Scheduled triggers are registered after the save;\n`scheduleSync` in the response says whether each one is in place.\n\nCreating a worker is free. Its runs are not: each call to a custom worker during a run spends\ncredits (feature `worker_run` in **List credit usage**).\n\nNeeds a workspace owner or admin. An API key counts as an admin.", "x-mint": { "href": "/api-reference/workers-and-runs/create-a-worker", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_workers_create`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-create)." } } }, "/v1/platform/agents/{id}": { "get": { "operationId": "getAgent", "tags": [ "Workers and runs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The worker's id.", "example": "6720f3a1b2c3d4e5f6a7b8c9" } ], "responses": { "200": { "description": "The worker.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/Worker" } } }, "example": { "meta": { "message": "Successful request" }, "data": { "_id": "6720f3a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Account researcher", "type": "custom", "isActive": true, "icon": "search", "isExcluded": false, "description": "Researches a company before a first call and writes a brief on the record.", "instructions": "When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities.", "toolName": "account_researcher", "toolNames": [ "web_search" ], "actionIds": [], "toolPolicy": { "readOnly": false }, "memory": { "enabled": true }, "resources": { "scope": "everything", "allKbFiles": true, "linkedKbFileIds": [], "fileIds": [] }, "triggers": [ { "type": "event", "events": [ "meeting.booked" ], "source": "user" }, { "type": "scheduled", "match": { "schedule": "0 8 * * 1", "timezone": "Europe/Berlin" }, "dependencies": [], "source": "user" } ], "runtime": "sandbox", "metadata": { "created": { "at": "2026-10-12T14:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-01T09:20:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } }, "createdAt": "2026-10-12T14:00:00.000Z", "updatedAt": "2026-11-01T09:20:00.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no worker with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a worker", "description": "Returns one worker with its full instructions, tools, files and triggers.", "x-mint": { "href": "/api-reference/workers-and-runs/get-a-worker", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_workers_create`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-create), [`heliyos_workers_delete`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-delete), [`heliyos_workers_get`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-get), [`heliyos_workers_list`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-list), [`heliyos_workers_update`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-update)." } }, "patch": { "operationId": "updateAgent", "tags": [ "Workers and runs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The worker's id.", "example": "6720f3a1b2c3d4e5f6a7b8c9" } ], "responses": { "200": { "description": "The updated worker, with the outcome of its schedule registration.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WorkerSaved" } } }, "example": { "meta": { "message": "Agent updated." }, "data": { "_id": "6720f3a1b2c3d4e5f6a7b8c9", "name": "Account researcher", "type": "custom", "isActive": false, "toolName": "account_researcher", "triggers": [ { "type": "event", "events": [ "meeting.booked" ], "source": "user" } ], "scheduleSync": { "created": [], "deleted": [], "failed": [] } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no worker with this id, or a new action, file or dependency worker id is not this workspace's. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: another worker already has this name. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new name, 1 to 200 characters after trimming, unique in the workspace. Custom workers only." }, "description": { "type": "string", "maxLength": 2000, "description": "A new one-line description, up to 2,000 characters." }, "icon": { "type": "string", "maxLength": 100, "description": "A new icon name, up to 100 characters." }, "instructions": { "type": "string", "maxLength": 50000, "description": "New instructions in Markdown, up to 50,000 characters. Replaces the current ones." }, "isActive": { "type": "boolean", "description": "`false` pauses the worker, `true` resumes it." }, "toolName": { "type": "string", "pattern": "^[a-z0-9_]{1,48}$", "description": "Accepted and ignored. A worker's `toolName` is fixed at create." }, "toolNames": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 500, "description": "The complete list of built-in tools, up to 500. Replaces the current list. Custom workers only." }, "actionIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 500, "description": "The complete list of workspace actions, up to 500. Replaces the current list. Custom workers only." }, "toolPolicy": { "type": "object", "properties": { "readOnly": { "type": "boolean", "description": "`true`: read only." } }, "additionalProperties": false, "description": "`{ readOnly }`. Replaces the current policy. Custom workers only." }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Memory on or off." } }, "additionalProperties": false, "description": "`{ enabled }`. Replaces the current memory setting." }, "resources": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "everything", "org_knowledge", "account_files", "selected_files" ] }, "allKbFiles": { "type": "boolean" }, "linkedKbFileIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 1000 }, "fileIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 1000 } }, "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/WorkerResources" } ], "description": "The worker's files. Replaces the current setting as a whole. Custom workers only." }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerTriggerInput" }, "maxItems": 50, "description": "The complete list of triggers you want, up to 50. Replaces the current ones (a default worker keeps its built-in ones)." }, "schedule": { "type": "object", "properties": { "cron": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 }, "description": "5-field cron expressions." } }, "additionalProperties": false, "description": "Legacy cron list. Replaces the current one. Custom workers only. Use a `scheduled` trigger instead." } }, "additionalProperties": false, "minProperties": 1 }, "example": { "isActive": false } } } }, "summary": "Update a worker", "description": "Changes a worker. Send at least one field; what you leave out is kept.\n\n- On a custom worker you can change `name`, `description`, `icon`, `instructions`, `isActive`,\n `toolNames`, `actionIds`, `toolPolicy`, `memory`, `resources`, `triggers` and `schedule`.\n- On a default worker only `description`, `icon`, `instructions`, `isActive`, `memory` and\n `triggers` apply. Other fields are accepted and ignored.\n- `toolName` is accepted and ignored on every worker: it never changes after create.\n\n`triggers`, when sent, replaces the worker's own triggers. On a default worker its built-in\n(`source` `default`) triggers always stay: your list replaces only the ones added by people, and\nevents or trigger types the built-in ones already cover are dropped. Send `[]` to remove every\ntrigger you added.\n\n`resources`, `toolPolicy` and `memory` are replaced as a whole when sent. Set `isActive: false` to\npause a worker instead of deleting it. Needs a workspace owner or admin.", "x-mint": { "href": "/api-reference/workers-and-runs/update-a-worker", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_workers_update`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-update)." } }, "delete": { "operationId": "deleteAgent", "tags": [ "Workers and runs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The custom worker's id.", "example": "6720f3a1b2c3d4e5f6a7b8c9" } ], "responses": { "200": { "description": "The worker was deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Always `true`." } } } } }, "example": { "meta": { "message": "Agent deleted." }, "data": { "deleted": true } } } } }, "400": { "description": "The worker is a default worker, which cannot be deleted (message \"Default agents cannot be deleted.\"). Nothing is changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no worker with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a worker", "description": "Deletes a custom worker permanently and removes its schedules. Its past runs and their history\nare kept. Default workers cannot be deleted: pause them with `isActive: false` instead.\n\nOther workers that list this one in a trigger's `dependencies` keep the id. Needs a workspace\nowner or admin.", "x-mint": { "href": "/api-reference/workers-and-runs/delete-a-worker", "metadata": {}, "content": "\nDeleting a worker cannot be undone. Its instructions, triggers and settings are gone, and its\nschedules stop. To stop a worker for now, update it with `isActive: false`.\n\n\nIn the Heliyos MCP server: [`heliyos_workers_delete`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-delete)." } } }, "/v1/platform/orchestrator/chats": { "post": { "operationId": "createOrchestratorChat", "tags": [ "Workers and runs" ], "parameters": [], "responses": { "200": { "description": "The run handling the message, and its reply when it finished within `wait`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/AskHeliyosResult" } } }, "example": { "meta": { "message": "Successful request" }, "data": { "runId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e", "status": "completed", "threadId": "3fa9c2d17b4e", "output": { "final_response_by": "Heliyos", "response": "Contoso moved to Negotiation on Tuesday. Two risks: procurement wants a security review, and the champion is out until Nov 12." } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: an attachments id is not a file of this workspace. Nothing runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The question or instruction, in plain language. 1 to 20,000 characters after trimming.", "example": "Summarise what changed with Contoso this week and list open risks." }, "threadId": { "type": "string", "pattern": "^[A-Za-z0-9_.:@=+-]+$", "minLength": 1, "maxLength": 100, "description": "The `threadId` from an earlier answer, to continue that conversation. 1 to 100 characters of letters, digits and `_ . : @ = + -`. Leave it out to start a new conversation. An id Heliyos has not seen starts a new conversation under that id.", "example": "3fa9c2d17b4e" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 20, "description": "Ids of files you already uploaded, up to 20. Heliyos and its workers can read them during the run. Each must be a file of this workspace." }, "wait": { "type": "integer", "minimum": 0, "maximum": 90, "default": 0, "description": "Seconds to hold the request while the run works, 0 to 90. 0 (the default) answers at once. The call returns as soon as the run finishes or waits on a person or a schedule.", "example": 60 } }, "required": [ "message" ], "additionalProperties": false }, "examples": { "ask": { "summary": "Ask and wait for the answer", "value": { "message": "Summarise what changed with Contoso this week and list open risks.", "wait": 60 } }, "followUp": { "summary": "Follow up in the same conversation", "value": { "message": "Draft a follow-up email to their champion about the security review.", "threadId": "3fa9c2d17b4e" } } } } } }, "summary": "Ask Heliyos", "description": "Sends a message to Heliyos, the same as typing it into Ask Heliyos in the app. Heliyos reads the\nworkspace, plans, and calls workers to do the work. It can answer a question (\"summarise what\nchanged with Contoso this week\") or carry out a job (\"draft a follow-up to the Fabrikam thread\").\n\n**What it returns.** The call starts a run and answers with `runId`, `status` and `threadId`.\nWith `wait` above 0 it holds the request for up to that many seconds until the run settles:\nfinishes, or stops to wait on a person or a schedule. If the run completes in time, `output`\ncarries the reply. Otherwise follow the run:\n\n1. Call **Get a run** with the `runId` and `wait=30`. Repeat while\n `status` is `queued` or `running`.\n2. When `status` is `completed`, read `output.response`. On `failed`, read `error` with\n `include=detail`.\n3. When `status` is `awaiting_approval`, `paused`, `waiting` or `scheduled`, polling will not\n move it. A person has to act in Heliyos (Review), or the scheduled time has to come.\n\n**List runs** with `threadId` returns every run of a conversation.\n\n**Conversations.** Leave `threadId` out to start a new conversation; Heliyos returns its id.\nSend it back to continue. If the thread's run is still open, your message joins that run instead\nof starting another: it is queued while the run works, read after the decision while it waits\nfor a review, and resumes it when it is paused.\n\n**Reviews.** Consequential actions, such as sending an email or changing a deal, wait for a\nperson's approval unless the workspace's autopilot allows them. The run then shows\n`awaiting_approval` and lists the reviews in `reviews`.\n\n**Credits.** Each call to a custom worker during the run spends credits once the call finishes.\nDefault workers and Heliyos's own reasoning are free. Tools the run uses can spend credits too,\nfor example company enrichment. The run's total is in `usage.credits` on **Get a run**, and each\ncharge is in **List credit usage** under `worker_run`.\n\n**Timeouts.** `wait` is at most 90 seconds; set your HTTP client's timeout above it (120 seconds\nis safe). A run has no fixed time limit and keeps working after the call returns. If you\ndisconnect early, the run is not affected.\n\nEvery call starts or continues work: calling twice with the same message runs it twice.", "x-mint": { "href": "/api-reference/workers-and-runs/ask-heliyos", "metadata": { "sidebarTitle": "Ask Heliyos" }, "content": "\nAsk Heliyos acts on your workspace. Depending on the request it can create and change records and\ntasks, draft and send email, and spend credits. Consequential actions wait for approval in\nHeliyos unless your autopilot settings allow them. Calling it twice starts the work twice.\n\n\nIn the Heliyos MCP server: [`heliyos_ask`](/mcp/tools/ask-runs-and-reviews#heliyos-ask)." } } }, "/v1/platform/workers/runs": { "get": { "operationId": "listWorkerRuns", "tags": [ "Workers and runs" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Runs per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid with the default order (newest first)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for offset paging. Pages are `limit` runs long." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Runs to skip, for offset paging. Wins over `page`." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Same as `offset`." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 }, "description": "Case-insensitive text matched against the run id, title, the message that started it, worker names, the triggering event name and the final reply. Up to 500 characters.", "example": "Contoso" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Only runs in this status, exact match: `queued`, `running`, `awaiting_approval`, `paused`, `waiting`, `scheduled`, `completed`, `failed`, `skipped`, `cancelled` or `stopped`.", "example": "awaiting_approval" }, { "name": "surface", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Only runs that started here: `chat` (Ask Heliyos), `worker_chat` (a chat with one worker), `task_chat` (a chat on a task), `background` (events, schedules and tasks) or `worker_direct`.", "example": "chat" }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only runs on this task, including chats that mention it.", "example": "6721a0b1c2d3e4f5a6b7c8d9" }, { "name": "threadId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:@=+-]+$", "minLength": 1, "maxLength": 100 }, "description": "Only runs of this conversation (the `threadId` from Ask Heliyos).", "example": "3fa9c2d17b4e" }, { "name": "interactionId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only runs about this email thread or meeting, or started by it.", "example": "6721a3c4d5e6f7a8b9c0d1e2" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only runs about this company record, or started by it.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, { "name": "personId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only runs about this person record, or started by it.", "example": "66f1a8c3e4b0a1b2c3d4e5f7" }, { "name": "runtime", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sandbox", "light" ] }, "description": "`sandbox` or `light`. Runs started through workers are `sandbox`. `light` runs come from an older pipeline that is hidden unless you also send its `surface`." }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only runs this worker took part in, was considered for, or focused on.", "example": "6720f3a1b2c3d4e5f6a7b8c9" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only runs created at or after this ISO 8601 date-time.", "example": "2026-11-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only runs created at or before this ISO 8601 date-time.", "example": "2026-11-05T23:59:59.999Z" }, { "name": "triggerType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Comma-separated trigger kinds, e.g. \"event,mention\"." }, "description": "Comma-separated trigger kinds: only runs set off by one of them, for example `event,mention`. Kinds include `chat`, `event`, `webhook`, `mention`, `task_created` and `scheduled`.", "example": "event,scheduled" }, { "name": "interactionIds", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5000, "description": "Comma-separated interaction ids." }, "description": "Comma-separated email thread or meeting ids. Only runs about any of them, or started by one." }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "status", "title", "surface" ] }, "description": "Sort field: `createdAt` (default), `updatedAt`, `status`, `title` or `surface`. Anything but `createdAt` switches to offset paging." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "`desc` (default) or `asc`. `asc` switches to offset paging." }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "run", "timeline" ], "description": "\"timeline\": the run + steps view the inbox renders." }, "description": "`run` (default) returns runs as described here. `timeline` returns each run flattened into the run-and-steps shape the Heliyos inbox renders; that shape is for the app and may change." } ], "responses": { "200": { "description": "A page of runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerRunListItem" } } } }, "example": { "meta": { "message": "Successful request", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6729d1e2f3a4b5c6d7e8f9a0", "orchestratorRunId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e", "organizationId": "66a0f1e2d3c4b5a697887766", "status": "completed", "title": "Contoso weekly summary", "surface": "chat", "runtime": "sandbox", "userInput": "Summarise what changed with Contoso this week and list open risks.", "triggerRef": { "type": "chat" }, "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company" } ], "threadId": "3fa9c2d17b4e", "userId": "66a0f1e2d3c4b5a697881111", "workers": [ { "agentId": "6720f3a1b2c3d4e5f6a7b8c9", "agentName": "Account researcher", "nodeId": "w1", "status": "completed" } ], "toolCalls": 6, "finalOutput": { "final_response_by": "Heliyos", "response": "Contoso moved to Negotiation on Tuesday." }, "usage": { "credits": 5, "requests": 9, "inputTokens": 48210, "outputTokens": 1630, "totalTokens": 49840 }, "createdAt": "2026-11-05T10:12:02.000Z", "updatedAt": "2026-11-05T10:12:41.000Z", "completedAt": "2026-11-05T10:12:41.000Z" } ] } } } }, "400": { "description": "VALIDATION_FAILED: for example a cursor sent with a sort other than newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List runs", "description": "Returns the workspace's runs, newest first: Ask Heliyos conversations, worker chats, task runs,\nand runs started by events and schedules. Read one run's steps with\n**Get a run**, using its `orchestratorRunId`.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor`. Sending `page`, `offset` or `skip`, or a sort other than newest first, switches to\noffset paging: `meta.pagination` then has `limit`, `offset`, `total` and `hasMore`, and there is no\ncursor. See [Pagination](/api-reference/pagination).\n\nFilters combine with AND.", "x-mint": { "href": "/api-reference/workers-and-runs/list-runs", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_runs_list`](/mcp/tools/ask-runs-and-reviews#heliyos-runs-list)." } } }, "/v1/platform/workers/runs/{id}": { "get": { "operationId": "getWorkerRun", "tags": [ "Workers and runs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:@=+-]+$", "minLength": 1, "maxLength": 128 }, "description": "The run id (`runId` from Ask Heliyos, or `orchestratorRunId` from **List runs**).", "example": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e" }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Seconds to long-poll until the run finishes or waits on a person (0 = answer at once)." }, "description": "Seconds to wait for the run to finish or stop on a person, 0 to 30. Defaults to 0 (answer at once).", "example": 30 }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(detail|step_payloads)(,(detail|step_payloads))*$", "description": "Comma list. detail: title, surface, error, workers, toolCalls, createdAt (the run view). step_payloads: each step's raw input, output and error, and the execution graph." }, "description": "Comma-separated extras: `detail`, `step_payloads`, or both (`detail,step_payloads`).", "example": "detail" } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WorkerRun" } } }, "example": { "meta": { "message": "Successful request" }, "data": { "id": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e", "status": "awaiting_approval", "trigger": { "type": "chat" }, "startedAt": "2026-11-05T10:12:02.000Z", "endedAt": null, "threadId": "3fa9c2d17b4e", "taskId": null, "steps": [ { "seq": 1, "type": "worker", "title": "Account researcher", "status": "completed", "startedAt": "2026-11-05T10:12:05.000Z", "endedAt": "2026-11-05T10:12:31.000Z", "summary": "Contoso moved to Negotiation on Tuesday. Procurement asked for a security review." }, { "seq": 2, "type": "approval", "title": "send_email", "status": "pending", "startedAt": "2026-11-05T10:12:38.000Z", "endedAt": null, "summary": null } ], "reviews": [ { "id": "6729d2f0a1b2c3d4e5f6a7b8", "status": "PENDING", "type": "email_draft" } ], "usage": { "credits": 5, "requests": 7, "inputTokens": 40120, "outputTokens": 1210, "totalTokens": 41330 }, "title": "Contoso follow-up", "agentName": "Heliyos", "surface": "chat", "error": null, "workers": [ { "nodeId": "w1", "agentId": "6720f3a1b2c3d4e5f6a7b8c9", "agentName": "Account researcher", "status": "completed" } ], "toolCalls": 4, "createdAt": "2026-11-05T10:12:02.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no run with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a run", "description": "Returns one run: its status, what set it off, every step with a one-line summary, the reviews it\nraised, its credit and model usage, and its final reply once it has one.\n\nSend `wait` to long-poll: the call holds for up to that many seconds while the run is `queued` or\n`running`, and returns as soon as it finishes or starts waiting on a person or a schedule. A run\nthat is already in one of those states returns at once.\n\n`include=detail` adds the title, error, the workers that took part and the tool-call count.\n`include=step_payloads` adds each step's raw input, output and error, and the execution graph;\nthese can be large.", "x-mint": { "href": "/api-reference/workers-and-runs/get-a-run", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_runs_get`](/mcp/tools/ask-runs-and-reviews#heliyos-runs-get)." } } }, "/v1/platform/workers/triggers": { "get": { "operationId": "listWorkerTriggers", "tags": [ "Workers and runs" ], "parameters": [], "responses": { "200": { "description": "Every trigger in the catalogue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "triggers": { "type": "array", "description": "The shared triggers by name, then the workspace's own by name.", "items": { "$ref": "#/components/schemas/WorkerTriggerCatalogEntry" } } } } } }, "example": { "meta": { "message": "Successful request" }, "data": { "triggers": [ { "_id": "6710a1b2c3d4e5f6a7b8c901", "organizationId": null, "name": "deal.attribute_updated", "kind": "event", "label": "Deal attribute changed", "description": "Chosen deal fields changed. Pick the pipeline (schema) and the attributes to watch.", "objectType": "deals", "source": "platform", "selectsAttributes": true, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" }, { "_id": "6710a1b2c3d4e5f6a7b8c902", "organizationId": null, "name": "mention", "kind": "mention", "label": "@mention", "description": "A person mentioned the worker in a comment or note.", "objectType": null, "source": "platform", "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" }, { "_id": "6710a1b2c3d4e5f6a7b8c903", "organizationId": null, "name": "schedule", "kind": "schedule", "label": "Schedule", "description": "Runs once at a date and time, or on a repeating schedule you configure on the worker.", "objectType": null, "source": "internal", "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" }, { "_id": "6710a1b2c3d4e5f6a7b8c904", "organizationId": null, "name": "task.created", "kind": "event", "label": "Task created", "description": "A task was created.", "objectType": "task", "source": "platform", "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" }, { "_id": "6710a1b2c3d4e5f6a7b8c905", "organizationId": null, "name": "typeform.response", "kind": "event", "label": "Typeform response", "description": "A form was submitted. The answers the form maps are already saved to the company, person and, when the form creates deals, the deal. Your own instructions say what to do with them.", "objectType": "company", "source": "typeform", "provider": "typeform", "providerRef": "TYPEFORM_NEW_RESPONSE", "integration": { "title": "Typeform", "iconSrc": "https://cdn.example.com/icons/typeform.svg", "connected": false }, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" } ] } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you cannot view workers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List triggers", "description": "Returns the catalogue of triggers a worker can be set to run on: the events it can subscribe\nto, mentions and schedules. Use it to fill `triggers` on **Create a worker** and **Update a\nworker**. The whole catalogue comes back in one response; it is not paged.\n\nEvery workspace has the same shared triggers. A workspace can also have entries of its own,\nlisted after the shared ones; an own entry with the same `name` as a shared one replaces it.\n\n**From catalogue entry to worker trigger.**\n\n| Catalogue entry | Trigger object on the worker |\n| --- | --- |\n| `kind` `event`, for example `deal.updated` | `{ \"type\": \"event\", \"events\": [\"deal.updated\"] }`. One trigger can list several event names; `\"*\"` means every event. |\n| `kind` `mention` (`mention`) | `{ \"type\": \"mention\" }`. Every active worker answers mentions, with or without it. |\n| `kind` `schedule` (`schedule`) | `{ \"type\": \"scheduled\", \"match\": { \"schedule\": \"0 8 * * 1-5\", \"timezone\": \"Europe/Berlin\" } }` for a repeating 5-field cron, or `match.at` (`YYYY-MM-DDTHH:MM:SS` local time) with `match.timezone` for one run. |\n| Not in the catalogue | `{ \"type\": \"task_created\" }` runs on every new task; `match.taskType` limits it to some task types. |\n\n**Things to know.**\n- The API does not check event names against this catalogue when you save a worker. A name\n that is not in it never fires.\n- Triggers with an `integration` only fire while that app is connected (`integration.connected`).\n- `company.attribute_updated`, `people.attribute_updated` and `deal.attribute_updated` watch\n fields picked in the Heliyos app. Created through the API, they run on a change to any field\n of that object.\n- A trigger with `type` `scheduled` is registered when you save the worker; check\n `scheduleSync` in that response.", "x-mint": { "href": "/api-reference/workers-and-runs/list-triggers", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_triggers_list`](/mcp/tools/workers-triggers-and-tools#heliyos-triggers-list), [`heliyos_workers_tools_list`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-tools-list)." } } }, "/v1/platform/workers/tools": { "get": { "operationId": "listWorkerTools", "tags": [ "Workers and runs" ], "parameters": [], "responses": { "200": { "description": "Every action a worker can take.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "tools": { "type": "array", "description": "Heliyos's own actions first, then the workspace's.", "items": { "$ref": "#/components/schemas/WorkerAction" } } } } } }, "example": { "meta": { "message": "Successful request" }, "data": { "tools": [ { "name": "create_task", "label": "Created task", "display_name": null, "description": "Create a follow-up task for the organization, linked to the company, people and deal.", "source": "builtin", "is_internal": true, "action_id": null, "provider": null, "risk": "write_crm", "review_type": "task", "common": false, "is_hidden": false, "input": { "type": "object", "properties": { "title": { "type": "string", "description": "Short imperative title, e.g. 'Send revised quote to Contoso'", "minLength": 2, "maxLength": 200 }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent", "none" ], "default": "medium" } }, "required": [ "title" ] }, "output": { "type": "object", "properties": { "ok": { "type": "boolean", "default": true, "description": "Whether the change was applied" }, "id": { "type": "string", "nullable": true, "description": "Id of the record created or changed" } } } }, { "name": "web_search", "label": "Searched the web", "display_name": null, "description": "Search the web and read pages to answer a question with sources.", "source": "builtin", "is_internal": true, "action_id": null, "provider": null, "risk": "read", "review_type": "web_search", "common": false, "is_hidden": false, "input": { "type": "object" }, "output": { "type": "object" } }, { "name": "schedule_meeting", "label": "Scheduled meeting", "display_name": "Schedule Meeting", "description": "Put a meeting on the calendar and invite the guests: a one-time or a repeating event, timed or all day, with a video call link created with it unless it is in person.", "source": "action", "is_internal": false, "action_id": "6721b2c3d4e5f6a7b8c9d0e1", "risk": "schedule_meeting", "review_type": "meeting_scheduled", "common": false, "is_hidden": false, "integration": { "title": "Gmail", "iconSrc": "https://cdn.example.com/icons/gmail.svg", "connected": true }, "input": { "type": "object" }, "output": { "type": "object" } } ] } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: you cannot view workers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List actions", "description": "Returns every action a worker in this workspace can take. The API calls them tools. Use it to\nfill `toolNames` and `actionIds` on **Create a worker** and **Update a worker**. The whole list\ncomes back in one response; it is not paged.\n\n**Two sources.**\n- `builtin`: Heliyos's own actions, the same in every workspace. Put the `name` in the worker's\n `toolNames`.\n- `action`: your workspace's actions, performed by a connected app, such as sending email or\n booking meetings through the connected mailbox, or working with files in connected storage.\n Put the `action_id` in the worker's `actionIds`.\n\n**What a worker gets.** A worker can use every action with `common: true`, plus the `builtin`\nactions named in `toolNames` and the actions in `actionIds`. A name in `toolNames` that is not\nin this list is saved but ignored when the worker runs. Each id in `actionIds` must be an action\nof this workspace (404 otherwise). Leave out actions with `is_hidden: true`.\n\n**Connected apps.** An action with an `integration` needs that app connected to work.\n`integration.connected` says whether it is connected now; the action is listed either way.\n\n**Reviews.** `risk` decides whether a call waits for a person: reads and writes to companies,\npeople, tasks and notes apply directly; deal changes, sending email, meetings and changes in\nconnected apps wait for review unless the workspace's autopilot settings allow them, and even\nthen a call below the confidence threshold waits. `send_email` is only available to workers\nwhile the workspace sends email automatically; otherwise workers draft with\n`create_email_draft` and the draft waits for review, where approving it sends it.\n\n`input` holds each action's full JSON Schema, so the response can be large.", "x-mint": { "href": "/api-reference/workers-and-runs/list-actions", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_triggers_list`](/mcp/tools/workers-triggers-and-tools#heliyos-triggers-list), [`heliyos_workers_tools_list`](/mcp/tools/workers-triggers-and-tools#heliyos-workers-tools-list)." } } }, "/v1/platform/reviews": { "get": { "operationId": "listReviews", "tags": [ "Reviews" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Reviews per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Takes precedence over `offset` and `page`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for offset paging. Skips `(page - 1) * limit` reviews. Ignored when `offset` is sent." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "The number of reviews to skip, for offset paging.", "example": 0 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "description": "Only reviews with this decision. Omit for all.\n- `PENDING`: waiting for a person.\n- `APPROVED`: approved by a person or by the workspace's autopilot settings.\n- `REJECTED`: rejected by a person.", "example": "PENDING" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "description": "Only reviews of this type, exact match, for example `email_draft` or `deal_update` (see `type` in the response for the values). `decision` also matches older questions and approval requests stored under other names. An unknown type returns an empty list.", "example": "email_draft" }, { "name": "objectId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "description": "A record, task, inbox thread or attachment id." }, "description": "Only reviews about this record, task, email thread or file: a review matches when the id is one of its records (`objectRefs`), its task, the email thread of its draft or the file it saves.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, { "name": "objectType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Accepted with `objectId` for compatibility. It does not narrow the results further.", "example": "company" }, { "name": "relationshipObjectId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "An older name for `objectId`. Ignored when `objectId` is sent." }, { "name": "relationshipObjectType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "An older name for `objectType`. Ignored when `objectType` is sent." } ], "responses": { "200": { "description": "A page of reviews.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } }, "example": { "meta": { "message": "Successful request", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6731f0a9b2c4d5e6f7a8b9c0", "id": "6731f0a9b2c4d5e6f7a8b9c0", "organizationId": "66a0f1e2d3c4b5a697887766", "type": "email_draft", "kind": "action", "origin": "model", "status": "PENDING", "approval": { "status": "PENDING", "by": null, "at": null, "comment": null, "feedback": null }, "agent": "Account researcher", "agentRef": { "id": "6720a0b1c2d3e4f5a6b7c8d9", "name": "Account researcher" }, "runId": "0f1e2d3c4b5a69788766554433221100", "taskId": "6729e1f2a3b4c5d6e7f80910", "tool": { "name": "send_email", "callId": "call_7f3a9c2e" }, "proposal": { "title": "Send email: Renewal terms for 2027", "summary": "Send Dana Whitfield the renewal terms discussed on Tuesday's call.", "args": { "to": [ "dana.whitfield@northwind.example.com" ], "subject": "Renewal terms for 2027", "body": "Hi Dana, as promised, here are the renewal terms we discussed on Tuesday." } }, "confidence": 72, "reasoning": "Dana asked for the terms in writing by Friday.", "approvalReason": "Sending email requires approval in this workspace.", "objectRef": { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "name": "Northwind Traders" }, "objectRefs": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "objectType": "company", "name": "Northwind Traders" } ], "draftEmail": { "subject": "Renewal terms for 2027", "body": "Hi Dana, as promised, here are the renewal terms we discussed on Tuesday.", "to": [ "dana.whitfield@northwind.example.com" ], "isSend": true }, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z" }, "updated": { "at": "2026-11-04T09:30:00.000Z" } } } ] } } } }, "400": { "description": "VALIDATION_FAILED: a parameter is invalid, or the cursor is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List reviews", "description": "Returns the workspace's reviews: worker actions waiting for a person, and the ones already decided. Without\n`status`, every status is returned. To see what needs a person now, send `status=PENDING`.\n\nBy default the list pages with a cursor, newest review first: pass `limit`, then send\n`meta.pagination.next_cursor` back as `cursor` for the next page. Sending `offset` or `page` (without\n`cursor`) switches to offset paging, ordered by most recent activity, so a review a later run proposed again\nmoves up. Then `meta.pagination` is `{ page, limit, count, totalPages, hasMore }`.\nSee [Pagination](/api-reference/pagination).\n\nEach item is the full review, as in Get a review, without the resolved records and work.", "x-mint": { "href": "/api-reference/reviews/list-reviews", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_reviews_list`](/mcp/tools/ask-runs-and-reviews#heliyos-reviews-list)." } } }, "/v1/platform/reviews/{id}": { "get": { "operationId": "getReview", "tags": [ "Reviews" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The review's id.", "example": "6731f0a9b2c4d5e6f7a8b9c0" } ], "responses": { "200": { "description": "The review.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/ReviewDetail" } } }, "example": { "meta": { "message": "Successful request" }, "data": { "_id": "6731f2c4d5e6f7a8b9c0d1e2", "id": "6731f2c4d5e6f7a8b9c0d1e2", "organizationId": "66a0f1e2d3c4b5a697887766", "type": "deal_update", "kind": "action", "origin": "model", "status": "PENDING", "approval": { "status": "PENDING", "by": null, "at": null, "comment": null, "feedback": null }, "agent": "Pipeline keeper", "agentRef": { "id": "6720a0b1c2d3e4f5a6b7c8da", "name": "Pipeline keeper" }, "runId": "1a2b3c4d5e6f708192a3b4c5d6e7f809", "proposal": { "title": "Update deal: Contoso expansion", "summary": "Move the deal to Negotiation and raise the amount to 48,000.", "args": { "deal_id": "6730aa11bb22cc33dd44ee55", "fields": { "stage": "Negotiation", "amount": 48000 } } }, "confidence": 64, "reasoning": "Procurement confirmed the expanded seat count on the call.", "approvalReason": "The stated confidence is below the workspace's threshold.", "objectRef": { "objectId": "6730aa11bb22cc33dd44ee55", "objectType": "deals" }, "objectRefs": [ { "objectId": "6730aa11bb22cc33dd44ee55", "objectType": "deals", "name": "Contoso expansion" } ], "dealAction": "Update", "previousVersion": { "_id": "6730aa11bb22cc33dd44ee55", "data": { "deal_name": "Contoso expansion", "stage": "Proposal", "amount": 36000 }, "relationships": [] }, "newVersion": { "_id": "6730aa11bb22cc33dd44ee55", "data": { "deal_name": "Contoso expansion", "stage": "Negotiation", "amount": 48000 }, "relationships": [] }, "relatedObjects": [ { "_id": "6730aa11bb22cc33dd44ee55", "objectType": "deals", "data": { "deal_name": "Contoso expansion", "stage": "Proposal", "amount": 36000 } } ], "previousVersionRelatedObjects": [], "newVersionRelatedObjects": [], "metadata": { "created": { "at": "2026-11-04T14:05:00.000Z" }, "updated": { "at": "2026-11-04T14:05:00.000Z" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no review with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a review", "description": "Returns one review with everything a person needs to decide it: the worker's proposal (`proposal`, and the\ntype's own fields such as `draftEmail` or `previousVersion` and `newVersion`), its `reasoning`, `confidence`\nand `approvalReason`, the worker and run it came from (`agentRef`, `runId`), and the records it is about.\n\nUnlike List reviews, the records and work the review refers to are resolved: `relatedObjects` holds the\ncompany, people and deal records, `interactionData` the email thread or meeting, and `taskData` the task.\nOnce decided, `approval` holds the decision and `outcome` what happened.", "x-mint": { "href": "/api-reference/reviews/get-a-review", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_reviews_get`](/mcp/tools/ask-runs-and-reviews#heliyos-reviews-get)." } } }, "/v1/platform/reviews/{id}/decisions": { "post": { "operationId": "createReviewDecision", "tags": [ "Reviews" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The review's id.", "example": "6731f2c4d5e6f7a8b9c0d1e2" } ], "responses": { "200": { "description": "The decision and the review after it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/ReviewDecisionResult" } } }, "example": { "meta": { "message": "Review approved." }, "data": { "status": "APPROVED", "applied": { "action": "Update", "dealId": "6730aa11bb22cc33dd44ee55", "schemaId": "66a0f1e2d3c4b5a697880003", "object": { "_id": "6730aa11bb22cc33dd44ee55", "objectType": "deals", "data": { "deal_name": "Contoso expansion", "stage": "Negotiation", "amount": 45000 } } }, "orchestrator": { "status": "APPROVED", "runId": "1a2b3c4d5e6f708192a3b4c5d6e7f809", "resuming": true }, "review": { "_id": "6731f2c4d5e6f7a8b9c0d1e2", "id": "6731f2c4d5e6f7a8b9c0d1e2", "type": "deal_update", "status": "APPROVED", "approval": { "status": "APPROVED", "by": "66a0f1e2d3c4b5a697881111", "at": "2026-11-04T15:12:00.000Z", "comment": "Amount agreed on the call.", "feedback": null }, "outcome": { "ok": true, "at": "2026-11-04T15:12:00.000Z", "appliedBy": "platform", "action": "Update", "dealId": "6730aa11bb22cc33dd44ee55" } } } } } } }, "400": { "description": "VALIDATION_FAILED: the body is invalid; the review is already decided (`Review is already approved.`, `rejected` or `processing`); or, for a deal, the edited fields fail the deal object's validation, the chosen pipeline is not a deal object, or the record is not a deal. Nothing is changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: your role cannot decide reviews, or the workspace's subscription is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no review with this id in the workspace, or the deal it changes (or that deal's object) no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: another decision on this deal or label review is being applied. Read the review before trying again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The deal or label review cannot be applied as stored: it names no deal to update, no pipeline to create the deal in, or no label name. The review stays pending; reject it instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The decision could not be passed to the worker's run. Read the review before retrying: if it is still `PENDING`, decide it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ], "description": "`approved` carries out the action. `rejected` drops it.", "example": "approved" }, "comment": { "type": "string", "maxLength": 5000, "nullable": true, "description": "A note kept on the review, up to 5,000 characters. Empty or null stores nothing.", "example": "Confirmed with Dana by phone." }, "feedback": { "type": "string", "maxLength": 5000, "nullable": true, "description": "What to tell the worker, up to 5,000 characters: why you rejected it, what to change, or your answer to a question (`kind: question`). Empty or null sends nothing.", "example": "Hold the email until legal signs off on the discount." }, "data": { "type": "object", "properties": {}, "additionalProperties": true, "description": "`deal_update`, approving only: the deal's fields to write, as field key to value. Replaces the worker's proposed fields, so include every field you want written. Validated against the deal's object. Omit to write the proposal as it is.", "example": { "stage": "Negotiation", "amount": 45000 } }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 500, "description": "`deal_update`, approving only: ids of the company and people records to link to the deal, up to 500. Omit, or send an empty list, to keep the links the worker proposed." }, "schemaId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "`deal_update` creating a deal, approving only: the pipeline (deal object) to create it in. Defaults to the one the worker proposed. Must be a deal object of this workspace." }, "args": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A paused action, approving only: the arguments you changed, by name, as in `proposal.args`. They are merged over the worker's arguments, so send only what changes.", "example": { "start": "2026-11-12T15:00:00", "timezone": "Europe/London" } } }, "required": [ "decision" ], "additionalProperties": false }, "examples": { "approve": { "summary": "Approve as proposed", "value": { "decision": "approved" } }, "approveWithChanges": { "summary": "Approve a deal change with edited fields", "value": { "decision": "approved", "comment": "Amount agreed on the call.", "data": { "stage": "Negotiation", "amount": 45000 } } }, "reject": { "summary": "Reject and tell the worker why", "value": { "decision": "rejected", "feedback": "Hold the email until legal signs off on the discount." } } } } } }, "summary": "Approve or reject a review", "description": "Records a person's decision on a pending review and acts on it. A review is decided once.\n\n**Approving** carries out the worker's action:\n- `deal_update` and `classification_label`: Heliyos applies the change before it answers, the same way an\n edit in Heliyos would, and reports it in `applied`. If applying fails, nothing is recorded and the review\n stays pending.\n- A saved email draft (`origin: artifact`): the draft is sent before the call answers. If sending fails, the\n approval is still recorded and `orchestrator.error` says why.\n- Every other type: the worker's run resumes in the background and carries out the action. This happens only\n once every pending review of that run is decided (`orchestrator.pending` counts the rest). Read the run, or\n the review's `outcome`, to see the result. If the run is no longer waiting, the decision is recorded and\n nothing runs.\n\n**Rejecting** drops the action and tells the worker your `feedback`. A saved email draft is discarded. As\nwith approval, a paused run resumes, without the action, once every review it waits on is decided.\n\n**Changing the proposal before approving.** For `deal_update`, send the fields to write in `data` (and\n`relationships` or `schemaId`). For other paused actions, send the changed arguments in `args`. They are\nchecked by the same rules as the worker's; if they fail, the action does not run and `outcome.error`\nsays why. `data`, `relationships`, `schemaId` and `args` are ignored on rejection. A saved email draft is\nsent as saved: `args` does not change it.\n\n**Already decided.** A review that is not pending answers 400 and nothing happens, so sending a decision\nagain after it succeeded does not repeat the action. Send one decision at a time per review: of two\ndecisions sent at the same moment on a deal or label review, one wins and the other answers 409.\n\n**Who can decide.** Any member of the workspace, and any API key. A decision made with an API key counts as\na person's: it is recorded under the user who created the key and carried out exactly as if that person\nhad approved it in Heliyos. Deciding is blocked while the workspace's subscription is inactive.\n\n`meta.message` is `Review approved.` or `Review rejected.`. When a deal or label change was applied but the\nrun could not be told yet, it is `Review approved; the change is applied, but the agent run could not be\nnotified.` and `orchestratorError` is set: the run picks the decision up later on its own.", "x-mint": { "href": "/api-reference/reviews/approve-or-reject-a-review", "metadata": {}, "content": "\n Approving through the API carries out the worker's action as if a person clicked Approve in Heliyos: the\n email is sent, the deal is changed, the meeting is booked. It cannot be undone. Read the review with\n Get a review first, and approve only what a person has confirmed.\n\n\nIn the Heliyos MCP server: [`heliyos_reviews_decide`](/mcp/tools/ask-runs-and-reviews#heliyos-reviews-decide)." } } }, "/v1/platform/global-scouts": { "get": { "operationId": "listGlobalScouts", "tags": [ "Scouts" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "custom" ] }, "description": "`default` for built-in Scouts only, `custom` for the Scouts you created.", "example": "custom" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Only Scouts with exactly this category (case-sensitive), up to 200 characters.", "example": "Hiring" }, { "name": "isActive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` for running Scouts, `false` for paused Scouts and custom Scouts not yet confirmed.", "example": true }, { "name": "applyTo", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "watchlist", "selected_watchlist", "entire_web" ] }, "description": "Only Scouts with this scope. `watchlist` also matches older Scouts saved without a scope.", "example": "watchlist" } ], "responses": { "200": { "description": "The workspace's Scouts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalScoutSummary" } } } }, "example": { "meta": { "message": "Global scouts retrieved successfully" }, "data": [ { "_id": "6731c0a2b4e5f60718293a4b", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Hiring for data roles", "type": "custom", "applyTo": "watchlist", "selectedCompanyIds": [], "category": "Hiring", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "weekly", "effort": "medium", "outputSchema": { "type": "json", "json_schema": { "type": "object", "properties": { "signals": { "type": "array" } } } }, "isActive": true, "previewStatus": "completed", "previewRunId": "trun_4b8e2f1a9c7d", "previewData": null, "metadata": { "created": { "at": "2026-10-02T08:15:00.000Z", "by": "system" }, "updated": { "at": "2026-10-02T08:20:00.000Z", "by": "system" } }, "signal_counts": { "total": 12, "new": 3 }, "latest_signal": { "_id": "6735a9d1e2f3a4b5c6d7e8f9", "scoutSchemaId": "6732d4e5f6a7b8c9d0e1f2a3", "baseSchemaObjectId": "66f1a8c3e4b0a1b2c3d4e5f6", "category": "Hiring", "scout_name": "Hiring for data roles", "summary": "Northwind Traders posted three senior data engineer roles in Lisbon.", "status": "new", "detected_date": "2026-11-03T06:00:00.000Z", "companyName": "Northwind Traders" }, "active_company_count": 8 } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns every workspace Scout, built-in and custom, sorted by category and then name. Each one carries\nits signal totals, its latest signal and how many companies it is running on.\n\nThe list is not paged: a workspace has a handful of Scouts.\n\nA workspace Scout defines what to look for. The copies running on each company are company Scouts:\nsee List a company's Scouts (`GET /v1/platform/companies/{id}/scouts`).", "summary": "List workspace Scouts", "x-mint": { "href": "/api-reference/scouts/list-workspace-scouts", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_scouts_list`](/mcp/tools/scouts-and-signals#heliyos-scouts-list)." } }, "post": { "operationId": "createGlobalScout", "tags": [ "Scouts" ], "parameters": [], "responses": { "200": { "description": "The new Scout, inactive while its preview runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/GlobalScout" } } }, "example": { "meta": { "message": "Custom global scout created successfully" }, "data": { "_id": "6731c0a2b4e5f60718293a4b", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Hiring for data roles", "type": "custom", "applyTo": "watchlist", "selectedCompanyIds": [], "category": "Hiring", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "weekly", "effort": "medium", "isActive": false, "previewStatus": "running", "previewRunId": "trun_4b8e2f1a9c7d", "previewData": null, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "system" }, "updated": { "at": "2026-11-04T09:30:01.000Z", "by": "system" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a field is invalid, `selectedCompanyIds` is missing for `selected_watchlist`, or a selected company is not a watched company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: a `selectedCompanyIds` entry is not a record in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The Scout's name, 1 to 200 characters after trimming.", "example": "Hiring for data roles" }, "category": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A short label, 1 to 200 characters after trimming. Signals inherit it.", "example": "Hiring" }, "queryTemplate": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "What to look for, in plain language, 1 to 5,000 characters after trimming. For the watchlist scopes,\nwrite it about \"the company\": each company's name and website are added when it runs. For\n`entire_web`, describe the event anywhere on the web.\n", "example": "New job postings at the company for data engineering or analytics roles." }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "How often it runs: `daily`, `weekly` (default) or `monthly`.", "example": "weekly" }, "applyTo": { "type": "string", "enum": [ "watchlist", "selected_watchlist", "entire_web" ], "description": "The scope, fixed once created: `watchlist` (default, every watched company), `selected_watchlist`\n(only `selectedCompanyIds`) or `entire_web` (one run across the web).\n", "example": "watchlist" }, "effort": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Search depth: `low`, `medium` (default) or `high`. Higher effort costs more credits per run.", "example": "medium" }, "selectedCompanyIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 1000, "description": "Required, with at least one id, when `applyTo` is `selected_watchlist`; ignored otherwise. Up to 1,000\ncompany record ids, each a watched company in this workspace. Duplicates are removed.\n" }, "previewCompanyData": { "type": "object", "properties": { "company_name": { "type": "string", "description": "The company's name." }, "website": { "type": "string", "description": "The company's website." } }, "additionalProperties": false, "description": "`selected_watchlist` only: the company the preview runs on, as `company_name` (up to 500 characters)\nand optional `website` (up to 2,000 characters). Ignored for other scopes or when `company_name` is empty.\n" }, "previewLookbackPeriod": { "type": "string", "enum": [ "1_month", "3_months", "6_months" ], "description": "How far back the preview searches: `1_month` (default), `3_months` or `6_months`.", "example": "1_month" }, "outputSchema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "The structured output each run returns. Send `{ \"type\": \"json\", \"json_schema\": { ... } }` or a bare JSON\nSchema object (`{ \"type\": \"object\", \"properties\": { ... } }`); anything else becomes an empty object\nschema. In `signals[].items`, `citations`, `confidence_score` and `source` are removed and a `sources`\narray is added. Omit it for the default schema (see the `ScoutOutputSchema` component).\n" } }, "required": [ "name", "category", "queryTemplate" ], "additionalProperties": false }, "examples": { "watchlist": { "summary": "Every watched company", "value": { "name": "Hiring for data roles", "category": "Hiring", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "weekly", "effort": "medium" } }, "selected": { "summary": "Selected watched companies", "value": { "name": "Expansion into Europe", "category": "Growth & Expansion", "queryTemplate": "The company opening an office or entity in a European country.", "applyTo": "selected_watchlist", "selectedCompanyIds": [ "66f1a8c3e4b0a1b2c3d4e5f6", "66f1a8c3e4b0a1b2c3d4e5f7" ], "previewCompanyData": { "company_name": "Northwind Traders", "website": "https://northwind.example.com" }, "previewLookbackPeriod": "3_months" } } } } } }, "description": "Creates a custom workspace Scout and starts a preview run of its query. The Scout is created inactive\n(`isActive: false`) and does not run on any company yet.\n\n1. Create the Scout. `previewStatus` is `running` (or `failed` if the preview could not start; the Scout\n is still created).\n2. Poll Get a workspace Scout (`GET /v1/platform/global-scouts/{id}`) until `previewStatus` is `completed`, and\n review `previewData`.\n3. Send `{\"state\": \"confirmed\"}` to Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`) to\n activate it, or `{\"state\": \"cancelled\"}` to discard it.\n\nOnce confirmed, the Scout runs on its scope at its cadence, and each run on a company (or on the web)\ncosts credits by `effort`: `low` 2.5, `medium` 7.5, `high` 10. Calling this twice creates two Scouts.", "summary": "Create a custom Scout", "x-mint": { "href": "/api-reference/scouts/create-a-custom-scout", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_scouts_create`](/mcp/tools/scouts-and-signals#heliyos-scouts-create)." } } }, "/v1/platform/global-scouts/{id}": { "get": { "operationId": "getGlobalScout", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The workspace Scout's id.", "example": "6731c0a2b4e5f60718293a4b" } ], "responses": { "200": { "description": "The workspace Scout.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/GlobalScoutSummary" } } }, "example": { "meta": { "message": "Global scout retrieved successfully" }, "data": { "_id": "6731c0a2b4e5f60718293a4b", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Hiring for data roles", "type": "custom", "applyTo": "watchlist", "selectedCompanyIds": [], "category": "Hiring", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "weekly", "effort": "medium", "isActive": false, "previewStatus": "completed", "previewRunId": "trun_4b8e2f1a9c7d", "previewData": { "signals": [ { "company_name": "Contoso", "website": "https://contoso.example.com", "summary": "Contoso opened two analytics engineer roles.", "sources": [ "https://contoso.example.com/careers/analytics-engineer" ] } ], "total_count": 1, "query_summary": "Data and analytics job postings in the last month." }, "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "system" }, "updated": { "at": "2026-11-04T09:32:00.000Z", "by": "system" } }, "signal_counts": { "total": 0, "new": 0 }, "latest_signal": null, "active_company_count": 0 } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no workspace Scout with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns one workspace Scout with its signal totals, its latest signal and how many companies it is\nrunning on. For a custom Scout you just created, poll this until `previewStatus` is `completed`,\nthen confirm it with Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`).", "summary": "Get a workspace Scout", "x-mint": { "href": "/api-reference/scouts/get-a-workspace-scout", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_scouts_get`](/mcp/tools/scouts-and-signals#heliyos-scouts-get)." } }, "patch": { "operationId": "updateGlobalScout", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The custom Scout's id.", "example": "6731c0a2b4e5f60718293a4b" } ], "responses": { "200": { "description": "The updated Scout (without signal totals).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/GlobalScout" } } }, "example": { "meta": { "message": "Global scout updated successfully" }, "data": { "_id": "6731c0a2b4e5f60718293a4b", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Hiring for data roles", "type": "custom", "applyTo": "watchlist", "category": "Hiring", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "daily", "effort": "high", "isActive": true, "previewStatus": "completed" } } } } }, "400": { "description": "VALIDATION_FAILED: a field is invalid, `applyTo` differs from the Scout's scope, `selectedCompanyIds` was sent for a Scout that is not `selected_watchlist`, or a selected company is not watched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN: the Scout is built in. Only its state can change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no workspace Scout with this id, or a `selectedCompanyIds` entry is not a record in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new name, 1 to 200 characters after trimming." }, "category": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new category, 1 to 200 characters after trimming." }, "queryTemplate": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "A new query, 1 to 5,000 characters after trimming." }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "`daily`, `weekly` or `monthly`." }, "applyTo": { "type": "string", "enum": [ "watchlist", "selected_watchlist", "entire_web" ], "description": "The scope cannot change. Only the Scout's current value is accepted." }, "effort": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "`low`, `medium` or `high`. Changes the credits each run costs." }, "selectedCompanyIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "maxItems": 1000, "description": "`selected_watchlist` Scouts only: the complete new set of watched company record ids, up to 1,000." }, "outputSchema": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A new output schema, normalized as on create." } }, "additionalProperties": false, "minProperties": 1 }, "example": { "cadence": "daily", "effort": "high" } } } }, "description": "Changes a custom Scout's fields. Send at least one field; what you leave out is kept. The changes are\ncopied to every company Scout it runs on.\n\n- The scope (`applyTo`) cannot change. Sending the current value is accepted; any other value is a 400.\n- `selectedCompanyIds` replaces the selected companies of a `selected_watchlist` Scout. If the Scout is\n active, it starts on the added companies, and the company Scouts of removed companies are deleted\n (their signals are kept).\n- Built-in Scouts cannot be edited (403). Pause or resume them with\n Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`), which is also how you activate or pause a custom Scout.", "summary": "Update a custom Scout", "x-mint": { "href": "/api-reference/scouts/update-a-custom-scout", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_scouts_update`](/mcp/tools/scouts-and-signals#heliyos-scouts-update)." } }, "delete": { "operationId": "deleteGlobalScout", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The custom Scout's id.", "example": "6731c0a2b4e5f60718293a4b" } ], "responses": { "200": { "description": "What was deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true`." }, "deleted_company_scouts": { "type": "integer", "description": "Company Scouts deleted with it." }, "monitors_deleted": { "type": "integer", "description": "Running monitors stopped." } } } } }, "example": { "meta": { "message": "Global scout deleted successfully" }, "data": { "success": true, "deleted_company_scouts": 8, "monitors_deleted": 0 } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN: the Scout is built in and cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no workspace Scout with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Deletes a custom Scout permanently, with every company Scout it runs on, and stops their monitors.\nSignals it already found stay in the workspace: they still appear in List signals (`GET /v1/platform/signals`),\nbut no longer in the Scout's own signal list. Built-in Scouts cannot be deleted; pause them instead.", "summary": "Delete a custom Scout", "x-mint": { "href": "/api-reference/scouts/delete-a-custom-scout", "metadata": {}, "content": "This cannot be undone. The Scout and all of its company Scouts are deleted.\n\nIn the Heliyos MCP server: [`heliyos_scouts_delete`](/mcp/tools/scouts-and-signals#heliyos-scouts-delete)." } } }, "/v1/platform/global-scouts/{id}/state": { "post": { "operationId": "setGlobalScoutState", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The workspace Scout's id.", "example": "6731c0a2b4e5f60718293a4b" } ], "responses": { "200": { "description": "The result. Its shape depends on `state`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "oneOf": [ { "$ref": "#/components/schemas/GlobalScoutStateChange" }, { "allOf": [ { "$ref": "#/components/schemas/GlobalScout" } ], "title": "confirmed", "description": "The confirmed Scout." }, { "type": "object", "title": "cancelled", "properties": { "success": { "type": "boolean", "description": "Always `true`." } } } ] } } }, "example": { "meta": { "message": "Global scout activated successfully" }, "data": { "success": true, "scout": { "_id": "6731c0a2b4e5f60718293a4b", "name": "Hiring for data roles", "type": "custom", "applyTo": "watchlist", "cadence": "weekly", "effort": "medium", "isActive": true, "previewStatus": "completed" }, "activated_count": 8 } } } } }, "400": { "description": "VALIDATION_FAILED: `state` is missing or not one of the four values, or `confirmed` was sent before the preview completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no workspace Scout with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "paused", "confirmed", "cancelled" ], "description": "`active`, `paused`, `confirmed` or `cancelled`. See the table above.", "example": "confirmed" } }, "required": [ "state" ], "additionalProperties": false }, "examples": { "confirm": { "summary": "Activate a new custom Scout after its preview", "value": { "state": "confirmed" } }, "pause": { "summary": "Pause a Scout on every company", "value": { "state": "paused" } } } } } }, "description": "Activates, pauses, confirms or discards a workspace Scout. `state` decides what happens:\n\n| `state` | Works on | What it does | `data` |\n| --- | --- | --- | --- |\n| `active` | Any Scout | Sets `isActive: true`, resumes its paused company Scouts and starts it on its scope again. | `{ success, scout, activated_count }` |\n| `paused` | Any Scout | Sets `isActive: false`, pauses every company Scout and stops their monitors. Signals are kept. | `{ success, scout, deactivated_count, monitors_deleted }` |\n| `confirmed` | A custom Scout whose `previewStatus` is `completed` | Activates it and starts it on its scope: every watched company, the selected companies, or the web. | The Scout |\n| `cancelled` | A custom Scout with `isActive: false` | Deletes the Scout permanently. On any other Scout it changes nothing. | `{ success: true }` |\n\n`meta.message` depends on `state`: `Global scout activated successfully`, `Global scout deactivated successfully`,\n`Scout confirmed and activated successfully` or `Scout preview cancelled successfully`.\n\nOnce active, a custom Scout's runs cost credits by `effort`.", "summary": "Set a workspace Scout state", "x-mint": { "href": "/api-reference/scouts/set-a-workspace-scout-state", "metadata": {}, "content": "\n`cancelled` deletes any inactive custom Scout, including one you paused, and only the workspace Scout\nitself: its company Scouts are left behind. To remove a custom Scout that has run, use\nDelete a custom Scout (`DELETE /v1/platform/global-scouts/{id}`) instead. `active` also activates a custom Scout\nwhose preview has not completed; use `confirmed` for new Scouts.\n\n\nIn the Heliyos MCP server: [`heliyos_scouts_update`](/mcp/tools/scouts-and-signals#heliyos-scouts-update)." } } }, "/v1/platform/companies/{id}/scouts": { "get": { "operationId": "listCompanyScouts", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The company record's id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "failed" ] }, "description": "Only company Scouts in this status: `active`, `paused` or `failed`.", "example": "active" } ], "responses": { "200": { "description": "The company's Scouts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyScout" } } } }, "example": { "meta": { "message": "Scouts retrieved successfully" }, "data": [ { "_id": "6732d4e5f6a7b8c9d0e1f2a3", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaObjectId": "66f1a8c3e4b0a1b2c3d4e5f6", "defaultScoutId": "6731c0a2b4e5f60718293a4b", "scoutType": "custom", "executionMode": "task", "effort": "medium", "name": "Hiring for data roles", "category": "Hiring", "query": "Find data for the company Northwind Traders with the website https://northwind.example.com. New job postings at the company for data engineering or analytics roles.", "queryTemplate": "New job postings at the company for data engineering or analytics roles.", "cadence": "weekly", "scope": "watchlist", "status": "active", "lastRunDate": "2026-11-03T06:00:00.000Z", "metadata": { "created": { "at": "2026-10-02T08:20:00.000Z", "by": "system" }, "updated": { "at": "2026-11-03T06:00:00.000Z", "by": "system" } } } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List company Scouts", "description": "Returns the Scouts running on one company, newest first. Each entry is a company Scout: a copy of a\nworkspace Scout (`defaultScoutId`) for this company. The list is not paged.", "x-mint": { "href": "/api-reference/scouts/list-company-scouts", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_companies_scouts_list`](/mcp/tools/scouts-and-signals#heliyos-companies-scouts-list)." } }, "post": { "operationId": "createCompanyScouts", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The company record's id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "Setup started in the background.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "A note that setup started." }, "status": { "type": "string", "description": "`processing`: setup continues in the background." }, "total_scouts": { "type": "integer", "description": "The number of Scout ids sent." } } } } }, "example": { "meta": { "message": "Scouts creation initiated successfully" }, "data": { "message": "Scout creation triggered successfully", "status": "processing", "total_scouts": 2 } } } } }, "400": { "description": "VALIDATION_FAILED: `defaultScoutIds` is empty or too long, or a Scout is inactive or not scoped to the watchlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace, or a `defaultScoutIds` entry is not a workspace Scout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultScoutIds": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "minItems": 1, "maxItems": 50, "description": "1 to 50 workspace Scout ids. Each must be an active Scout with scope `watchlist`, built in or custom.\n" }, "companyData": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Optional company field values used to build each Scout's query (`company_name` or `name`, and\n`website` or `company_website`). When omitted or empty, the record's own values are used. Most\ncallers omit it.\n" } }, "required": [ "defaultScoutIds" ], "additionalProperties": false }, "example": { "defaultScoutIds": [ "6731c0a2b4e5f60718293a4b", "6731c0a2b4e5f60718293a4c" ] } } } }, "summary": "Add Scouts to a company", "description": "Starts the given workspace Scouts on one company. Watching a company already starts every active\n`watchlist` Scout on it; use this to add Scouts to a company that is missing some.\n\nSetup runs in the background: the response says it started, and the company Scouts appear in\nList a company's Scouts (`GET /v1/platform/companies/{id}/scouts`) once created. A Scout already set up on the\ncompany is not added twice. Custom Scouts cost credits on each run by `effort`.", "x-mint": { "href": "/api-reference/scouts/add-scouts-to-a-company", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_companies_scouts_add`](/mcp/tools/scouts-and-signals#heliyos-companies-scouts-add)." } }, "delete": { "operationId": "deleteCompanyScouts", "tags": [ "Scouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The company record's id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "Which company Scouts were removed. If the removal fails as a whole, the call can still answer 200 with\n`{ \"success\": false, \"error\": \"...\" }`: check `success` is an array.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "success": { "type": "array", "description": "Ids of the company Scouts removed.", "items": { "$ref": "#/components/schemas/ObjectId" } }, "failed": { "type": "array", "description": "Company Scouts that could not be removed. Call again to retry.", "items": { "type": "object", "properties": { "scout_id": { "$ref": "#/components/schemas/ObjectId" }, "error": { "type": "string", "description": "Why it failed." } } } }, "total": { "type": "integer", "description": "Company Scouts found on the company." }, "success_count": { "type": "integer", "description": "How many were removed." }, "failed_count": { "type": "integer", "description": "How many could not be removed." } } } } }, "example": { "meta": { "message": "Scouts deleted successfully" }, "data": { "success": [ "6732d4e5f6a7b8c9d0e1f2a3", "6732d4e5f6a7b8c9d0e1f2a4" ], "failed": [], "total": 2, "success_count": 2, "failed_count": 0 } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Remove company Scouts", "description": "Stops and deletes every company Scout running on one company. There is no per-Scout removal. The\nsignals those Scouts found are deleted with them. The company stays watched and keeps using its Watcher,\nand the workspace Scouts are not changed. Add Scouts back with Add Scouts to a company (`POST /v1/platform/companies/{id}/scouts`).\n\nUnwatching a company does this for you.", "x-mint": { "href": "/api-reference/scouts/remove-company-scouts", "metadata": {}, "content": "This cannot be undone. The company's Scouts and their signals are deleted.\n\nIn the Heliyos MCP server: [`heliyos_companies_scouts_remove`](/mcp/tools/scouts-and-signals#heliyos-companies-scouts-remove)." } } }, "/v1/platform/signals": { "get": { "operationId": "listSignals", "tags": [ "Signals" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Signals per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Takes precedence over `offset` and `page`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for offset paging. Skips `(page - 1) * limit` signals. Ignored when `offset` is sent." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "The number of signals to skip, for offset paging.", "example": 0 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "read", "archived" ] }, "description": "Only signals in this status: `new` (unread), `read` or `archived`.", "example": "new" }, { "name": "scoutId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only signals found by this company Scout (an id from `GET /v1/platform/companies/{id}/scouts`). An unknown id returns an empty list.", "example": "6732d4e5f6a7b8c9d0e1f2a3" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only signals about this company record. An unknown id returns an empty list.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "A page of signals.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } }, "example": { "meta": { "message": "Signals retrieved successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6735a9d1e2f3a4b5c6d7e8f9", "organizationId": "66a0f1e2d3c4b5a697887766", "scoutSchemaId": "6732d4e5f6a7b8c9d0e1f2a5", "baseSchemaObjectId": "66f1a8c3e4b0a1b2c3d4e5f6", "category": "Growth & Expansion", "scout_name": "Funding, M&A, or financial news", "scope": "watchlist", "company_name": "Northwind Traders", "website": "https://northwind.example.com", "summary": "Northwind Traders raised a 40 million dollar Series C to expand into Southeast Asia.", "citations": [ "https://news.example.com/northwind-series-c" ], "relevance_score": 86, "confidence_score": 0.86, "source": "scouts", "detected_date": "2026-11-03T06:00:00.000Z", "status": "new", "metadata": { "created": { "at": "2026-11-03T06:02:00.000Z", "by": "webhook" }, "updated": { "at": "2026-11-03T06:02:00.000Z", "by": "webhook" } } } ] } } } }, "400": { "description": "VALIDATION_FAILED: a parameter is invalid, or the cursor is invalid or points at a signal that no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List signals", "description": "Returns the workspace's signals, most recently detected first. Filter by company, company Scout and status.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor` back as\n`cursor` for the next page. If the signal a cursor points at was deleted, the call answers 400; list\nagain from the first page. Sending `offset` or `page` (without `cursor`) switches to offset paging,\nwhere `meta.pagination` is `{ limit, offset, total, hasMore }`. See [Pagination](/api-reference/pagination).\n\n`scoutId` here is a company Scout id. To list everything one workspace Scout found across its companies,\nuse `GET /v1/platform/global-scouts/{id}/signals`.", "x-mint": { "href": "/api-reference/signals/list-signals", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_signals_list`](/mcp/tools/scouts-and-signals#heliyos-signals-list)." } } }, "/v1/platform/global-scouts/{id}/signals": { "get": { "operationId": "listGlobalScoutSignals", "tags": [ "Signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The workspace Scout's id.", "example": "6731c0a2b4e5f60718293a4b" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Signals per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Takes precedence over `offset` and `page`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for offset paging. Ignored when `offset` is sent." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "The number of signals to skip, for offset paging." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "read", "archived" ] }, "description": "Only signals in this status: `new` (unread), `read` or `archived`.", "example": "new" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only signals detected at or after this ISO 8601 date-time.", "example": "2026-10-01T00:00:00.000Z" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only signals detected at or before this ISO 8601 date-time.", "example": "2026-11-01T00:00:00.000Z" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Only signals about this company record. A company the Scout does not run on returns an empty list.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "A page of the Scout's signals.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignalWithCompany" } } } }, "example": { "meta": { "message": "Signals retrieved successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6735a9d1e2f3a4b5c6d7e8fa", "organizationId": "66a0f1e2d3c4b5a697887766", "scoutSchemaId": "6732d4e5f6a7b8c9d0e1f2a3", "baseSchemaObjectId": "66f1a8c3e4b0a1b2c3d4e5f6", "category": "Hiring", "scout_name": "Hiring for data roles", "scope": "watchlist", "summary": "Northwind Traders posted three senior data engineer roles in Lisbon.", "citations": [ "https://careers.northwind.example.com/jobs/data-engineer" ], "relevance_score": 72, "source": "scouts", "detected_date": "2026-11-03T06:00:00.000Z", "status": "new", "companyName": "Northwind Traders" } ] } } } }, "400": { "description": "VALIDATION_FAILED: a parameter is invalid, or the cursor is invalid or points at a signal that no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no workspace Scout with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List workspace Scout signals", "description": "Returns the signals one workspace Scout found across every company it runs on, most recently detected\nfirst, each with `companyName`. Signals of company Scouts that were deleted (for example when a company\nwas unwatched or the Scout was edited to drop it) are not included.\n\nPaging works as in List signals (`GET /v1/platform/signals`): cursor by default, offset paging when you\nsend `offset` or `page`.", "x-mint": { "href": "/api-reference/signals/list-workspace-scout-signals", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_scouts_get`](/mcp/tools/scouts-and-signals#heliyos-scouts-get), [`heliyos_signals_list`](/mcp/tools/scouts-and-signals#heliyos-signals-list)." } } }, "/v1/platform/signals/{id}/read": { "post": { "operationId": "markSignalRead", "tags": [ "Signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The signal's id.", "example": "6735a9d1e2f3a4b5c6d7e8f9" } ], "responses": { "200": { "description": "The signal, now read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true`." }, "signal": { "$ref": "#/components/schemas/Signal" } } } } }, "example": { "meta": { "message": "Signal marked as read" }, "data": { "success": true, "signal": { "_id": "6735a9d1e2f3a4b5c6d7e8f9", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaObjectId": "66f1a8c3e4b0a1b2c3d4e5f6", "scout_name": "Funding, M&A, or financial news", "summary": "Northwind Traders raised a 40 million dollar Series C to expand into Southeast Asia.", "detected_date": "2026-11-03T06:00:00.000Z", "status": "read" } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no signal with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Mark a signal read", "description": "Sets one signal's status to `read`. Marking a read signal again changes nothing; an archived signal\nbecomes `read`. To mark many at once, use `POST /v1/platform/signals/bulk-read`.", "x-mint": { "href": "/api-reference/signals/mark-a-signal-read", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_signals_mark_read`](/mcp/tools/scouts-and-signals#heliyos-signals-mark-read)." } } }, "/v1/platform/signals/bulk-read": { "post": { "operationId": "bulkMarkSignalsRead", "tags": [ "Signals" ], "parameters": [], "responses": { "200": { "description": "How many signals were marked read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "updated": { "type": "integer", "description": "Signals changed from `new` to `read`. 0 when none were unread." }, "failed": { "type": "array", "description": "Always empty. The update is all or nothing.", "items": { "type": "string" } }, "marked_count": { "type": "integer", "description": "Same as `updated`." } } } } }, "example": { "meta": { "message": "Signals marked as read" }, "data": { "updated": 4, "failed": [], "marked_count": 4 } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: `companyId` is not a record in this workspace, or `scoutId` is not a company Scout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL: the signals could not be marked. Nothing was changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Mark the unread signals about this company record." }, "scoutId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Mark the unread signals of this company Scout (not a workspace Scout id)." } }, "additionalProperties": false }, "example": { "companyId": "66f1a8c3e4b0a1b2c3d4e5f6" } } } }, "description": "Marks every `new` signal of one company, one company Scout, or both, read in one update. Send\n`companyId`, `scoutId`, or both (then only signals matching both are marked).", "summary": "Mark signals read in bulk", "x-mint": { "href": "/api-reference/signals/mark-signals-read-in-bulk", "metadata": {}, "content": "\nWith an empty body, every unread signal in the workspace is marked read. Send `companyId` or\n`scoutId` to limit it.\n\n\nIn the Heliyos MCP server: [`heliyos_signals_mark_read`](/mcp/tools/scouts-and-signals#heliyos-signals-mark-read)." } } }, "/v1/platform/watchlist/statistics": { "get": { "operationId": "getWatchlistStatistics", "tags": [ "Watchlist" ], "parameters": [], "responses": { "200": { "description": "The watchlist's statistics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WatchlistStatistics" } } }, "example": { "meta": { "message": "Watchlist statistics retrieved successfully" }, "data": { "tasks": { "total": 48, "completed": 31 }, "totalActions": 126, "totalMeetings": 19, "totalDeals": 7, "accountStatus": { "customer": 5, "prospect": 9, "unknown": 2 }, "engagementStatus": { "active": 8, "cooling": 3, "unknown": 5 } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: the workspace has no companies object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get watchlist statistics", "description": "Returns counts of the work done on watched companies: linked tasks (and how many are completed),\nAutonomous Updates runs, meetings and deals, plus how many watched companies have each account\nstatus and engagement status. When no company is watched, every count is 0 and both status maps are empty.\n\nTo list the watched companies themselves, list your companies object's records filtered on\n`isAgentAssigned`. Watchers in use and your plan's Watchers limit are on `GET /v1/platform/organization`\n(`watchersInUse`, `watchersLimit`).", "x-mint": { "href": "/api-reference/watchlist/get-watchlist-statistics", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_watchlist_get`](/mcp/tools/watchlist#heliyos-watchlist-get)." } } }, "/v1/platform/companies/{id}/watch": { "post": { "operationId": "watchCompany", "tags": [ "Watchlist" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The company record's id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "The company record, now watched.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WatchedCompanyRecord" } } }, "example": { "meta": { "message": "Company watched." }, "data": { "_id": "66f1a8c3e4b0a1b2c3d4e5f6", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "website": "https://northwind.example.com", "account_status": "unknown", "engagement_status": "unknown" }, "isAgentAssigned": true, "agentAssignmentStatus": "STARTED", "enrichmentStatus": "FINISHED", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e600", "schemaId": "66a0f1e2d3c4b5a697880002", "objectType": "people" } ], "metadata": { "created": { "at": "2026-09-12T10:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN: no Watchers left on your plan (or no active plan): `Watched accounts limit reached. Upgrade your plan to watch more companies.` Also returned when you cannot edit the companies object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace, or the record is not a company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Watch a company", "description": "Adds a company record to the watchlist. Watching an already watched company changes nothing and uses\nno Watcher.\n\nWhen the company was not watched yet:\n- It uses one Watcher from your plan. With none left, the call answers 403 and nothing changes.\n- Its `account_status` and `engagement_status` are set to `unknown` if empty, and the records linked\n to it (for example its people and deals) are marked watched too.\n- In the background, the workers enrich it and pull in its emails and meetings (enrichment uses\n credits), and every active Scout scoped to the watchlist starts on it. Custom Scouts cost credits per run.\n\nBackground steps that fail do not fail the call. Check progress in `agentAssignmentStatus` and with\n`GET /v1/platform/companies/{id}/scouts`.", "x-mint": { "href": "/api-reference/watchlist/watch-a-company", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_companies_watch`](/mcp/tools/watchlist#heliyos-companies-watch)." } }, "delete": { "operationId": "unwatchCompany", "tags": [ "Watchlist" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The company record's id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" } ], "responses": { "200": { "description": "The company record, no longer watched.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WatchedCompanyRecord" } } }, "example": { "meta": { "message": "Company unwatched." }, "data": { "_id": "66f1a8c3e4b0a1b2c3d4e5f6", "organizationId": "66a0f1e2d3c4b5a697887766", "baseSchemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company", "data": { "company_name": "Northwind Traders", "website": "https://northwind.example.com", "account_status": "customer", "engagement_status": "active" }, "isAgentAssigned": false, "agentAssignmentStatus": null, "metadata": { "created": { "at": "2026-09-12T10:00:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T14:10:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN: you cannot edit the companies object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this id in the workspace, or the record is not a company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Unwatch a company", "description": "Removes a company from the watchlist and frees its Watcher. Its company Scouts are stopped and deleted,\ntogether with the signals they found, and the workers stop monitoring it. Its emails, meetings, tasks\nand notes stay, so watching it again picks the history back up.\n\nRecords that were marked watched along with the company (its people and deals) stay marked.\nUnwatching a company that is not watched frees no Watcher, but still removes any Scouts left on it.", "x-mint": { "href": "/api-reference/watchlist/unwatch-a-company", "metadata": {}, "content": "The company's Scouts and their signals are deleted. Watching the company again starts new Scouts.\n\nIn the Heliyos MCP server: [`heliyos_companies_unwatch`](/mcp/tools/watchlist#heliyos-companies-unwatch)." } } }, "/v1/auth/organizations/current": { "get": { "operationId": "getCurrentOrganization", "tags": [ "Knowledge base" ], "parameters": [], "responses": { "200": { "description": "The workspace profile and its knowledge base.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/WorkspaceProfile" } } }, "example": { "meta": { "message": "Organization Successfully Fetched." }, "data": { "id": "66a0f1e2d3c4b5a697887766", "_id": "66a0f1e2d3c4b5a697887766", "name": "Northwind Traders", "website": "https://northwind.example.com", "industry": "Wholesale distribution", "timezone": "America/New_York", "businessContext": "Northwind Traders supplies specialty food and beverage products to independent grocers and cafes across North America.", "knowledgeBase": { "productsInformation": "Wholesale catalogue of 1,200 specialty foods, with next-day delivery in 40 metro areas.", "painPoints": "Independent grocers lose margin to stockouts and juggle too many small suppliers.", "valueProposition": "One supplier, one invoice and next-day restocking for the long tail of the shelf.", "qualificationCriteria": "Independent grocers or cafe groups with 3 or more locations and a buyer we can reach.", "entries": [ { "label": "Pricing", "content": "Volume pricing starts at $5,000 a month. Net 30 terms after the first order." }, { "label": "Competitors", "content": "Regional distributors and direct-from-brand programs. We win on breadth and delivery speed." } ] }, "createdAt": "2024-07-24T09:15:00.000Z", "updatedAt": "2026-11-02T14:30:00.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get the knowledge base", "description": "Returns the workspace your API key belongs to with its knowledge base: the business context,\nthe four fixed texts and the custom entries, plus the workspace's profile (name, website,\nindustry, time zone and address).\n\nTexts come back in full. Read this before you call **Update the knowledge base**, because\nthat call replaces the knowledge base whole.\n\nTo list the files your workers read, call **List files** with `kind=knowledge_base`.", "x-mint": { "href": "/api-reference/knowledge-base/get-the-knowledge-base", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_knowledge_entries_delete`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-entries-delete), [`heliyos_knowledge_entries_set`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-entries-set), [`heliyos_knowledge_get`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-get), [`heliyos_knowledge_update`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-update)." } }, "patch": { "operationId": "updateCurrentOrganization", "tags": [ "Knowledge base" ], "parameters": [], "responses": { "200": { "description": "The changes were saved. `data` is an empty object. Call **Get the knowledge base** to read the result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Organization details successfully updated." }, "data": {} } } } }, "400": { "description": "VALIDATION_FAILED: a field has the wrong type, `name` is empty or longer than 200 characters, `website` is not an http or https URL, or `logo` is not a Heliyos file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: the caller is not an owner or admin of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessContext": { "type": "string", "description": "What the business does, in your team's words. Plain text or Markdown. An empty string clears it." }, "knowledgeBase": { "type": "object", "properties": { "productsInformation": { "type": "string", "description": "The products and services you sell." }, "painPoints": { "type": "string", "description": "The customer problems your products solve." }, "valueProposition": { "type": "string", "description": "Why customers choose your products." }, "qualificationCriteria": { "type": "string", "description": "What makes a lead worth pursuing." }, "entries": { "type": "array", "description": "Every custom entry you want to keep, in display order. Send `[]` to remove them all.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The entry's title, for example `Pricing`." }, "content": { "type": "string", "description": "The entry's content, as plain text or HTML." } } } } }, "description": "The whole knowledge base. Replaces the stored one. Each text is plain text, Markdown or HTML, and an empty string clears it." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The workspace's name, 1 to 200 characters after trimming." }, "website": { "type": "string", "format": "uri", "description": "The company website, an `http` or `https` URL. An empty string clears it." }, "industry": { "type": "string", "description": "The industry, as free text. An empty string clears it." }, "timezone": { "type": "string", "description": "The workspace's time zone, as an IANA name such as `America/New_York`. Not checked against a list. An empty string clears it." }, "address": { "type": "string", "description": "Street address. An empty string clears it." }, "city": { "type": "string", "description": "City. An empty string clears it." }, "state": { "type": "string", "description": "State or region. An empty string clears it." }, "zipcode": { "type": "string", "description": "Postal code. An empty string clears it." }, "country": { "type": "string", "description": "Country. An empty string clears it." }, "logo": { "type": "string", "description": "The logo: the id of a file uploaded with **Upload a file**, or the https URL Heliyos returned for it. Other URLs are refused. An empty string clears it." } }, "additionalProperties": false }, "examples": { "knowledgeBase": { "summary": "Add a knowledge entry", "value": { "knowledgeBase": { "productsInformation": "Wholesale catalogue of 1,200 specialty foods, with next-day delivery in 40 metro areas.", "painPoints": "Independent grocers lose margin to stockouts and juggle too many small suppliers.", "valueProposition": "One supplier, one invoice and next-day restocking for the long tail of the shelf.", "qualificationCriteria": "Independent grocers or cafe groups with 3 or more locations and a buyer we can reach.", "entries": [ { "label": "Pricing", "content": "Volume pricing starts at $5,000 a month. Net 30 terms after the first order." }, { "label": "Competitors", "content": "Regional distributors and direct-from-brand programs. We win on breadth and delivery speed." }, { "label": "Delivery areas", "content": "Next-day delivery in 40 metro areas across the US and Canada. Two-day delivery elsewhere." } ] } } }, "businessContext": { "summary": "Change the business context only", "value": { "businessContext": "Northwind Traders supplies specialty food and beverage products to independent grocers and cafes across North America." } } } } } }, "summary": "Update the knowledge base", "description": "Changes the knowledge base, the business context and the workspace profile. Send only the\nfields you want to change. Fields you leave out keep their values.\n\n**`knowledgeBase` is replaced whole.** When you send it, the stored knowledge base becomes\nexactly what you sent: a fixed text or an entry you leave out is removed. To change one text\nor add one entry, call **Get the knowledge base**, change what you need, and send the whole\nobject back.\n\n- An empty string clears a text.\n- Top-level fields this page does not list are ignored without an error.\n- Keys inside `knowledgeBase` and its entries that are not listed here are stored as you send them.\n- Entry labels are not checked for duplicates. Keep them unique so people and workers can tell them apart.\n\nWorkers read the new knowledge base on their next run. Only workspace owners and admins can\ncall this. API keys act as an admin, so every key can.", "x-mint": { "href": "/api-reference/knowledge-base/update-the-knowledge-base", "metadata": {}, "content": "\n Sending `knowledgeBase` replaces it whole. Leaving out a text or an entry deletes it, and\n it cannot be recovered. Read the knowledge base first and send every text and entry you\n want to keep.\n\n\nIn the Heliyos MCP server: [`heliyos_knowledge_entries_delete`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-entries-delete), [`heliyos_knowledge_entries_set`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-entries-set), [`heliyos_knowledge_get`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-get), [`heliyos_knowledge_update`](/mcp/tools/knowledge-base-and-files#heliyos-knowledge-update)." } } }, "/v1/platform/attachments/presigned-urls": { "post": { "operationId": "createPresignedUrl", "tags": [ "Files" ], "parameters": [], "responses": { "200": { "description": "The upload URL and the key to create the file with.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/FileUploadUrl" } } }, "example": { "meta": { "message": "Presigned URL generated successfully" }, "data": { "presignedUrl": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost&X-Amz-Signature=3f9a0c", "fileKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "bucketName": "example-bucket" } } } } }, "400": { "description": "VALIDATION_FAILED: a field is missing or invalid, `fileSize` is 0 or above 25 MB (26,214,400 bytes), or `mimeType` is not an accepted content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "maxLength": 1000, "description": "The file's name, up to 1,000 characters. It becomes part of the storage key, with separators and control characters replaced.", "example": "pricing-2026.pdf" }, "mimeType": { "type": "string", "maxLength": 200, "description": "The file's content type, one of the accepted types listed above (case-insensitive). Send exactly this value as `Content-Type` with the upload.", "example": "application/pdf" }, "objectType": { "type": "string", "nullable": true, "description": "Optional. The type of record the file will be attached to: `company`, `people`, `deal` (or `deals`). Files for these types are stored in a separate folder per type. Any other value, an empty string or null stores the file in the workspace's main folder.", "example": "company" }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 26214400, "description": "The file's exact size in bytes, from 1 to 26,214,400 (25 MB). Send exactly this value as `Content-Length` with the upload.", "example": 482113 } }, "required": [ "fileName", "mimeType", "fileSize" ], "additionalProperties": false }, "example": { "fileName": "pricing-2026.pdf", "mimeType": "application/pdf", "objectType": "company", "fileSize": 482113 } } } }, "description": "Returns a short-lived signed URL to upload one file's bytes to, the first of three steps.\nNothing is stored and no file exists until you create it with\n**Create a file**.\n\nThe URL is valid for one hour and accepts exactly one body: the `Content-Type` and\n`Content-Length` you send with the `PUT` must equal `mimeType` and `fileSize` here, or storage\nrefuses the upload.\n\n**Accepted content types.** Images (`image/png`, `image/jpeg`, `image/jpg`, `image/gif`,\n`image/webp`, `image/heic`, `image/heif`, `image/bmp`, `image/tiff`), PDF (`application/pdf`),\nOffice and OpenDocument files (`application/msword`,\n`application/vnd.openxmlformats-officedocument.wordprocessingml.document`,\n`application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,\n`application/vnd.ms-powerpoint`,\n`application/vnd.openxmlformats-officedocument.presentationml.presentation`,\n`application/vnd.oasis.opendocument.text`, `application/vnd.oasis.opendocument.spreadsheet`,\n`application/vnd.oasis.opendocument.presentation`), `application/rtf`, text and data\n(`text/plain`, `text/csv`, `text/tab-separated-values`, `text/markdown`, `application/json`,\n`text/calendar`, `message/rfc822`), audio (`audio/mpeg`, `audio/mp4`, `audio/x-m4a`,\n`audio/wav`, `audio/x-wav`, `audio/webm`, `audio/ogg`), video (`video/mp4`, `video/quicktime`,\n`video/webm`), ZIP (`application/zip`, `application/x-zip-compressed`) and\n`application/octet-stream` for anything else. HTML, SVG, XML, scripts and executables are\nrefused. Text types and `application/json` may carry a `; charset=` parameter.", "summary": "Create an upload URL", "x-mint": { "href": "/api-reference/files/create-an-upload-url", "metadata": {}, "content": "\n \n Call this endpoint with the file's name, content type and exact size in bytes. Keep\n `presignedUrl`, `fileKey` and `bucketName` from the response.\n \n \n Send the file to `presignedUrl` within one hour, without your API key:\n\n ```bash\n curl -X PUT \"$PRESIGNED_URL\" \\\n -H \"Content-Type: application/pdf\" \\\n -H \"Content-Length: 482113\" \\\n --data-binary @pricing-2026.pdf\n ```\n\n `Content-Type` and `Content-Length` must match `mimeType` and `fileSize` exactly.\n \n \n Call **Create a file** with `storageKey` set to `fileKey`\n and `url` set to `https://{bucketName}.s3.amazonaws.com/{fileKey}`. Until then the file is\n not listed anywhere and workers cannot read it.\n \n\n\nIn the Heliyos MCP server: [`heliyos_files_upload`](/mcp/tools/knowledge-base-and-files#heliyos-files-upload)." } } }, "/v1/platform/attachments": { "post": { "operationId": "createAttachment", "tags": [ "Files" ], "parameters": [], "responses": { "200": { "description": "The created file, or the file already created with this `storageKey`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/File" } } }, "example": { "meta": { "message": "Attachment created successfully." }, "data": { "_id": "6729c0d4e5f6a7b8c9d0e1f2", "organizationId": "66a0f1e2d3c4b5a697887766", "fileName": "pricing-2026.pdf", "fileSize": 482113, "mimeType": "application/pdf", "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "storageProvider": "S3", "storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "isKbFile": false, "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: a field is missing or invalid, `fileSize` is above 25 MB, or `url` is not the storage URL of `storageKey`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: `storageKey` is outside your workspace's folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: a `relationships` entry names a resource that is not in your workspace. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "required": [ "objectId", "objectType" ], "properties": { "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the resource to attach the file to." }, "schemaId": { "type": "string", "nullable": true, "description": "The record's object (base schema) id. Send it for records; omit it or send null otherwise." }, "objectType": { "type": "string", "description": "What `objectId` points at, for example `company`, `task` or `interaction`.", "example": "company" } } }, "description": "Optional. The resources to attach the file to: records (`company`, `people`, `deal` or a custom object's type, with `schemaId`), `task`, `note`, `comment`, `interaction`, `meeting`, `email`, `chat` or `list`, up to 200 entries. Each must belong to your workspace. An `organization` entry may only name your own workspace." }, "fileName": { "type": "string", "description": "The name shown for the file. Usually the same name you sent for the upload URL.", "example": "pricing-2026.pdf" }, "fileSize": { "type": "integer", "minimum": 0, "maximum": 26214400, "description": "The file's size in bytes, 0 to 26,214,400 (25 MB). Send the size you uploaded.", "example": 482113 }, "mimeType": { "type": "string", "description": "The file's content type. Send the `mimeType` you uploaded with.", "example": "application/pdf" }, "url": { "type": "string", "maxLength": 2048, "description": "`https://{bucketName}.s3.amazonaws.com/{fileKey}`, built from the upload URL response. HTTPS only, with no port, credentials, query or fragment. Up to 2,048 characters.", "example": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf" }, "storageProvider": { "type": "string", "description": "The storage provider. Send `S3`.", "example": "S3" }, "storageKey": { "type": "string", "description": "The `fileKey` from the upload URL response. A key outside your workspace's folder is refused.", "example": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf" }, "isKbFile": { "type": "boolean", "description": "`true` to add the file to the knowledge base, where workers read it. Defaults to `false`, a file attached to the resources in `relationships`.", "example": false }, "description": { "type": "string", "description": "Optional. A short description of the file. May be empty.", "example": "2026 list prices and discount bands." } }, "required": [ "fileName", "fileSize", "mimeType", "url", "storageProvider", "storageKey" ], "additionalProperties": false }, "examples": { "recordFile": { "summary": "A file attached to a company", "value": { "fileName": "pricing-2026.pdf", "fileSize": 482113, "mimeType": "application/pdf", "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "storageProvider": "S3", "storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ] } }, "knowledgeBase": { "summary": "A knowledge base file", "value": { "fileName": "sales-playbook.pdf", "fileSize": 1048576, "mimeType": "application/pdf", "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf", "storageProvider": "S3", "storageKey": "66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf", "isKbFile": true, "description": "How we qualify and price enterprise deals." } } } } } }, "description": "Records a file you uploaded with an upload URL,\nas a knowledge base file or as a file attached to records, tasks or other resources. This is\nthe last of three steps; see the steps above.\n\n**Knowledge base files.** With `isKbFile: true` the file is linked to your workspace\nautomatically, and Heliyos copies it into the workers' workspace and extracts its text so\nworkers can read it. Text extraction can finish a little after this call returns.\n\n**Retries are safe.** Creating a file again with the same `storageKey` returns the file\nalready created, unchanged, instead of a second one.\n\nThe file is checked before anything is written: `storageKey` must be inside your workspace's\nfolder and `url` must point at exactly that key. Every entry in `relationships` must name a\nresource of your workspace.", "summary": "Create a file", "x-mint": { "href": "/api-reference/files/create-a-file", "metadata": {}, "content": "\n \n Call **Create an upload URL** with the file's name,\n content type and size.\n \n \n `PUT` the file to `presignedUrl` with the same `Content-Type` and `Content-Length`, without\n your API key.\n \n \n Call this endpoint with `storageKey` set to `fileKey`, `url` set to\n `https://{bucketName}.s3.amazonaws.com/{fileKey}`, `storageProvider` set to `S3`, and the\n same `fileName`, `mimeType` and `fileSize`.\n \n\n\nIn the Heliyos MCP server: [`heliyos_files_upload`](/mcp/tools/knowledge-base-and-files#heliyos-files-upload)." } }, "get": { "operationId": "listAttachments", "tags": [ "Files" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Files per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. Only valid with the default order (newest first) and no sort." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` files long, or `filters.pageSize` when sent." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "knowledge_base", "attachment" ] }, "description": "Which files to list:\n- `knowledge_base`: knowledge base files only.\n- `attachment`: files attached to resources only.\n\nOmit for both. Takes precedence over `isKbFile` in `filters`.", "example": "knowledge_base" }, { "name": "filters", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20000, "description": "JSON-encoded filter object (search, filters, sort, page, pageSize). Optional. pageSize above 200 is clamped to 200." }, "description": "A JSON object, URL-encoded. Keys:\n- `search` (string): matches text in the file name or content type, case-insensitive.\n- `objectId` (id): only files attached to this record, task or other resource.\n `relationshipObjectId` does the same.\n- `isKbFile` (boolean): `true` for knowledge base files, `false` for the others.\n- `filters` (array, up to 500): conditions `{ \"field\", \"operator\", \"value\" }`. Useful fields:\n `fileName`, `mimeType`, `fileSize`, `description`. Operators: `equals`, `not_equals`,\n `contains`, `gt`, `gte`, `lt`, `lte`. Any other operator is ignored. All conditions must match.\n- `sort` (array): `{ \"field\", \"direction\" }` with direction `asc` or `desc`. Switches to page-number paging.\n- `page`, `pageSize` (integers from 1): page-number paging. `pageSize` above 200 is lowered to 200.", "example": "{\"search\":\"pricing\",\"objectId\":\"66f1a8c3e4b0a1b2c3d4e5f6\"}" } ], "responses": { "200": { "description": "A page of files.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } }, "example": { "meta": { "message": "Attachments fetched successfully.", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6729c0d4e5f6a7b8c9d0e1f2", "id": "6729c0d4e5f6a7b8c9d0e1f2", "organizationId": "66a0f1e2d3c4b5a697887766", "fileName": "pricing-2026.pdf", "fileSize": 482113, "mimeType": "application/pdf", "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "storageProvider": "S3", "storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf", "isKbFile": false, "relationships": [ { "objectId": "66f1a8c3e4b0a1b2c3d4e5f6", "schemaId": "66a0f1e2d3c4b5a697880001", "objectType": "company" } ], "metadata": { "created": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } ] } } } }, "400": { "description": "VALIDATION_FAILED: `filters` is not a JSON object, holds a database operator, or `cursor` is sent with a sort or page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List files", "description": "Returns the workspace's files, newest first: knowledge base files and files attached to\nresources. Use `kind` to list only one of the two.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor` for the next page. A `sort` or `page` in `filters`, or the `page` parameter,\nswitches to page-number paging, sorted by creation date (newest first) unless you sort, with\n`meta.pagination` holding `page`, `limit`, `totalPages`, `count` and `hasMore`. See\n[Pagination](/api-reference/pagination) and [Filtering and sorting](/api-reference/filtering).\n\nTo list the files attached to one record, send `{\"objectId\": \"\"}` in `filters`.", "x-mint": { "href": "/api-reference/files/list-files", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_files_list`](/mcp/tools/knowledge-base-and-files#heliyos-files-list)." } } }, "/v1/platform/attachments/{id}": { "get": { "operationId": "getAttachment", "tags": [ "Files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The file's id.", "example": "6729c0d4e5f6a7b8c9d0e1f2" } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/File" } } }, "example": { "meta": { "message": "Attachment fetched successfully." }, "data": { "_id": "6729c0d4e5f6a7b8c9d0e1f2", "organizationId": "66a0f1e2d3c4b5a697887766", "fileName": "sales-playbook.pdf", "fileSize": 1048576, "mimeType": "application/pdf", "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf", "storageProvider": "S3", "storageKey": "66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf", "description": "How we qualify and price enterprise deals.", "isKbFile": true, "relationships": [ { "objectId": "66a0f1e2d3c4b5a697887766", "objectType": "organization" } ], "metadata": { "created": { "at": "2026-11-04T09:35:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:35:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no file with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a file", "description": "Returns one file's details: name, content type, size, kind and the resources it is attached to.\nTo download the file itself, use **Get a file download link**.", "x-mint": { "href": "/api-reference/files/get-a-file", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_files_get`](/mcp/tools/knowledge-base-and-files#heliyos-files-get)." } }, "delete": { "operationId": "deleteAttachment", "tags": [ "Files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The file's id.", "example": "6729c0d4e5f6a7b8c9d0e1f2" } ], "responses": { "200": { "description": "The file was deleted. `data` is an empty object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Attachment deleted successfully" }, "data": {} } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no file with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a file", "description": "Deletes a file permanently. It disappears from every resource it was attached to, and its\nstored bytes are removed unless another file of the workspace points at the same storage key.\nA knowledge base file is also removed from the workers' workspace, so workers stop reading it.", "x-mint": { "href": "/api-reference/files/delete-a-file", "metadata": {}, "content": "\n This cannot be undone. The file's bytes are deleted with it, and a knowledge base file stops\n informing workers at once.\n\n\nIn the Heliyos MCP server: [`heliyos_files_delete`](/mcp/tools/knowledge-base-and-files#heliyos-files-delete)." } } }, "/v1/platform/attachments/{id}/download": { "get": { "operationId": "getAttachmentDownloadUrl", "tags": [ "Files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The file's id.", "example": "6729c0d4e5f6a7b8c9d0e1f2" } ], "responses": { "200": { "description": "The download link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/FileDownloadUrl" } } }, "example": { "meta": { "message": "Download link generated" }, "data": { "url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf?response-content-disposition=attachment&X-Amz-Expires=60&X-Amz-Signature=8b2e41", "forced": true } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no file with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get a file download link", "description": "Returns a signed link that downloads the file under its `fileName`. The link expires\n60 seconds after the call, so use it at once and call again for a new one. No API key is\nneeded to open it.\n\nA few older files are stored outside Heliyos's upload storage. For those, `forced` is `false`\nand `url` is the file's stored URL, returned as is.", "x-mint": { "href": "/api-reference/files/get-a-file-download-link", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_files_get`](/mcp/tools/knowledge-base-and-files#heliyos-files-get)." } } }, "/v1/platform/classification-labels": { "get": { "operationId": "listClassificationLabels", "tags": [ "Labels" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Groups per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "next_cursor from the previous page; only valid with the default sort." }, "description": "The `next_cursor` from the previous page. When sent, `page` is ignored." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "A page number, starting at 1, for page-number paging. Pages are `limit` groups long." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Text to match, case-insensitive and literally, in the group's name, its description or any of its labels' names. Up to 200 characters.", "example": "pricing" }, { "name": "isActive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` lists only active groups, `false` only paused ones. Omit for both.", "example": true } ], "responses": { "200": { "description": "A page of label groups.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/KeysetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelGroup" } } } }, "example": { "meta": { "message": "Classification labels retrieved successfully", "pagination": { "limit": 20, "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2" } }, "data": [ { "_id": "6729d0a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Pricing questions", "description": "Emails asking about prices, discounts, quotes or billing terms.", "isActive": true, "color": "teal", "labels": [ { "_id": "6729d1e2f3a4b5c6d7e8f901", "name": "Discount request" }, { "_id": "6729d1e2f3a4b5c6d7e8f902", "name": "Quote request" } ], "createdBy": "66a0f1e2d3c4b5a697881111", "createdAt": "2026-11-04T09:30:00.000Z", "updatedAt": "2026-11-04T09:30:00.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List label groups", "description": "Returns the workspace's label groups with their labels, newest first.\n\nBy default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor`\nback as `cursor` for the next page. Sending `page` switches to page-number paging, sorted by\ncreation date (newest first), with `meta.pagination` holding `page`, `limit`, `totalPages`,\n`count` and `hasMore`. See [Pagination](/api-reference/pagination).", "x-mint": { "href": "/api-reference/labels/list-label-groups", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_labels_list`](/mcp/tools/labels#heliyos-labels-list)." } }, "post": { "operationId": "createClassificationLabels", "tags": [ "Labels" ], "parameters": [], "responses": { "201": { "description": "The created label group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/LabelGroup" } } }, "example": { "meta": { "message": "Classification labels created successfully" }, "data": { "_id": "6729d0a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Pricing questions", "description": "Emails asking about prices, discounts, quotes or billing terms.", "isActive": true, "color": "teal", "labels": [ { "_id": "6729d1e2f3a4b5c6d7e8f901", "name": "Discount request" }, { "_id": "6729d1e2f3a4b5c6d7e8f902", "name": "Quote request" } ], "createdBy": "66a0f1e2d3c4b5a697881111", "createdAt": "2026-11-04T09:30:00.000Z", "updatedAt": "2026-11-04T09:30:00.000Z" } } } } }, "400": { "description": "VALIDATION_FAILED: a field is missing or invalid, or two labels share a name (ignoring case).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: another group in the workspace already has this name. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The group's name, 1 to 200 characters. Must not equal the name of another group in the workspace (exact, case-sensitive match).", "example": "Pricing questions" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What the group covers, 1 to 1,000 characters. Heliyos reads it when it classifies email threads, so say plainly what belongs in the group.", "example": "Emails asking about prices, discounts, quotes or billing terms." }, "isActive": { "type": "boolean", "description": "`true` (the default) for an active group, `false` to create it paused.", "example": true }, "labels": { "type": "array", "items": { "type": "object", "required": [ "_id", "name" ], "properties": { "_id": { "type": "string", "description": "A new id you generate for the label, 24 hexadecimal characters.", "example": "6729d1e2f3a4b5c6d7e8f901" }, "name": { "type": "string", "description": "The label's name, 1 to 100 characters.", "example": "Discount request" } } }, "maxItems": 500, "description": "The group's labels, up to 500. Names must be unique within the group, ignoring case. Defaults to none." } }, "required": [ "name", "description" ], "additionalProperties": false }, "example": { "name": "Pricing questions", "description": "Emails asking about prices, discounts, quotes or billing terms.", "labels": [ { "_id": "6729d1e2f3a4b5c6d7e8f901", "name": "Discount request" }, { "_id": "6729d1e2f3a4b5c6d7e8f902", "name": "Quote request" } ] } } } }, "summary": "Create a label group", "description": "Creates a label group, optionally with its labels. Heliyos picks the group's colour: a family\nno other group in the workspace holds yet (no other active group, when the new group is\nactive), at random among the least used.\n\nGive each label its own new id: any 24-character hexadecimal string you generate.", "x-mint": { "href": "/api-reference/labels/create-a-label-group", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_labels_create`](/mcp/tools/labels#heliyos-labels-create)." } } }, "/v1/platform/classification-labels/{id}": { "patch": { "operationId": "updateClassificationLabels", "tags": [ "Labels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The label group's id.", "example": "6729d0a1b2c3d4e5f6a7b8c9" } ], "responses": { "200": { "description": "The updated label group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/LabelGroup" } } }, "example": { "meta": { "message": "Classification labels updated successfully" }, "data": { "_id": "6729d0a1b2c3d4e5f6a7b8c9", "organizationId": "66a0f1e2d3c4b5a697887766", "name": "Pricing and billing", "description": "Emails asking about prices, discounts, quotes or billing terms.", "isActive": true, "color": "teal", "labels": [ { "_id": "6729d1e2f3a4b5c6d7e8f901", "name": "Discount request" }, { "_id": "6729d1e2f3a4b5c6d7e8f903", "name": "Invoice question" } ], "createdBy": "66a0f1e2d3c4b5a697881111", "createdAt": "2026-11-04T09:30:00.000Z", "updatedAt": "2026-11-05T14:10:00.000Z" } } } } }, "400": { "description": "VALIDATION_FAILED: no field sent, a field is invalid, or two labels share a name (ignoring case).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no label group with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: another group in the workspace already has this name. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new name, 1 to 200 characters, not used by another group in the workspace (case-sensitive).", "example": "Pricing and billing" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "A new description, 1 to 1,000 characters." }, "isActive": { "type": "boolean", "description": "`false` pauses the group without deleting it. `true` reactivates it." }, "labels": { "type": "array", "items": { "type": "object", "required": [ "_id", "name" ], "properties": { "_id": { "type": "string", "description": "The label's current id to keep it, or a new 24-character hexadecimal id for a new label. Ids starting with `temp_` are accepted only to keep existing labels that have one.", "example": "6729d1e2f3a4b5c6d7e8f901" }, "name": { "type": "string", "description": "The label's name, 1 to 100 characters.", "example": "Discount request" } } }, "maxItems": 500, "description": "The complete new set of labels, up to 500, with names unique within the group (ignoring case). Replaces the current labels." } }, "additionalProperties": false, "minProperties": 1 }, "example": { "name": "Pricing and billing", "labels": [ { "_id": "6729d1e2f3a4b5c6d7e8f901", "name": "Discount request" }, { "_id": "6729d1e2f3a4b5c6d7e8f903", "name": "Invoice question" } ] } } } }, "summary": "Update a label group", "description": "Changes a group's name, description, active state or labels. Send at least one field.\n\n`labels`, when sent, replaces the group's labels completely. To keep a label, send it with its\ncurrent `_id`. A label sent with a new id is a new label, even if its name matches one being\nremoved.\n\nReactivating a paused group (`isActive` from `false` to `true`) can change its `color`, so\nthat it stays distinct from the other active groups.", "x-mint": { "href": "/api-reference/labels/update-a-label-group", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_labels_update`](/mcp/tools/labels#heliyos-labels-update)." } }, "delete": { "operationId": "deleteClassificationLabels", "tags": [ "Labels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The label group's id.", "example": "6729d0a1b2c3d4e5f6a7b8c9" } ], "responses": { "200": { "description": "The label group was deleted. `data` is an empty object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Classification labels deleted successfully" }, "data": {} } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no label group with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Delete a label group", "description": "Deletes a label group and its labels permanently. Email threads filed under the group no\nlonger show it. To stop using a group but keep it, set `isActive` to `false` with\n**Update a label group** instead.", "x-mint": { "href": "/api-reference/labels/delete-a-label-group", "metadata": {}, "content": "\n This cannot be undone. Email threads filed under the group stop showing it.\n\n\nIn the Heliyos MCP server: [`heliyos_labels_delete`](/mcp/tools/labels#heliyos-labels-delete)." } } }, "/v1/auth/team-memberships": { "get": { "operationId": "listTeamMemberships", "tags": [ "Team" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Text to match, case-insensitive and literally, in the email address, first name or last name. Up to 200 characters. Empty matches everyone.", "example": "northwind" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "The page number, starting at 1. Defaults to 1.", "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Memberships per page, 1 to 100. Defaults to 20.", "example": 20 }, { "name": "roleName", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ADMIN", "OWNER", "MEMBER", "AGENCY", "SUPER_ADMIN", "STAFF", "SUPPORT", "" ] }, "description": "Only memberships with this role. Workspace roles are `OWNER`, `ADMIN` and `MEMBER`, plus `AGENCY` in an agency workspace. The other accepted values are Heliyos staff roles and match no one in a workspace. Empty means every role.", "example": "ADMIN" } ], "responses": { "200": { "description": "A page of memberships.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembership" } } } }, "example": { "meta": { "message": "Team members fetched successfully.", "pagination": { "count": 2, "page": 1, "pageSize": 20 } }, "data": [ { "_id": "66a0f1e2d3c4b5a697882222", "id": "66a0f1e2d3c4b5a697882222", "email": "avery.chen@example.com", "roleId": "66a0f1e2d3c4b5a697880a01", "roleName": "OWNER", "organizationId": "66a0f1e2d3c4b5a697887766", "status": "REGISTERED", "userId": "66a0f1e2d3c4b5a697881111", "firstName": "Avery", "lastName": "Chen", "createdAt": "2026-06-02T08:00:00.000Z", "updatedAt": "2026-06-02T08:00:00.000Z" }, { "_id": "6729e1f2a3b4c5d6e7f80912", "id": "6729e1f2a3b4c5d6e7f80912", "email": "jordan.lee@example.com", "roleId": "66a0f1e2d3c4b5a697880a03", "roleName": "MEMBER", "organizationId": "66a0f1e2d3c4b5a697887766", "status": "SENT", "createdAt": "2026-11-04T09:30:00.000Z", "updatedAt": "2026-11-04T09:30:00.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List team members", "description": "Returns the workspace's memberships: people who joined and invitations still pending, oldest\nfirst. Each entry's `id` is what **Remove a team member** and **Change a team member's role**\ntake.\n\nThe list pages by page number: `meta.pagination` holds `page`, `pageSize` and `count`, the\ntotal number of matching memberships.", "x-mint": { "href": "/api-reference/team/list-team-members", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_team_members_list`](/mcp/tools/team#heliyos-team-members-list)." } }, "post": { "operationId": "createTeamMembership", "tags": [ "Team" ], "parameters": [], "responses": { "200": { "description": "The new membership, with status `SENT`. The invitation link is never returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/TeamMembership" } } }, "example": { "meta": { "message": "Invitation sent successfully." }, "data": { "id": "6729e1f2a3b4c5d6e7f80912", "email": "jordan.lee@example.com", "roleId": "66a0f1e2d3c4b5a697880a03", "organizationId": "66a0f1e2d3c4b5a697887766", "status": "SENT", "expiresOn": "2026-11-11T09:30:00.000Z", "onboardingSteps": [], "createdAt": "2026-11-04T09:30:00.000Z", "updatedAt": "2026-11-04T09:30:00.000Z" } } } } }, "400": { "description": "VALIDATION_FAILED: `email` is not a valid address, or `roleId` is not a role you can give in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: an API key invited with a role other than `MEMBER`, or the caller may not grant the owner role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CONFLICT: the address already has a pending invitation, or the person is already in the workspace. Nothing is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The person's email address. Stored in lower case.", "example": "jordan.lee@example.com" }, "roleId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The role to give them, from **List roles**. With an API key, the `MEMBER` role's id." } }, "required": [ "email", "roleId" ], "additionalProperties": false }, "example": { "email": "jordan.lee@example.com", "roleId": "66a0f1e2d3c4b5a697880a03" } } } }, "summary": "Invite a team member", "description": "Invites a person to the workspace with a role and emails them an invitation link. They join\nwhen they accept it. The link expires after 7 days; resend an expired invitation from Heliyos\nunder Settings, Team. A person who already has a Heliyos account gets an invitation addressed\nto them by name.\n\nWith an API key you can only invite with the `MEMBER` role. Get the role's id from\n**List roles**.\n\nAn address with a pending invitation, or of someone already in the workspace, is refused.", "x-mint": { "href": "/api-reference/team/invite-a-team-member", "metadata": {}, "content": "\n This sends an invitation email to the address straight away. Check the address, and check\n **List team members** first so you do not invite someone twice.\n\n\nIn the Heliyos MCP server: [`heliyos_team_members_invite`](/mcp/tools/team#heliyos-team-members-invite)." } } }, "/v1/auth/team-memberships/{id}": { "delete": { "operationId": "deleteTeamMembership", "tags": [ "Team" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The membership id, from **List team members**.", "example": "6729e1f2a3b4c5d6e7f80912" } ], "responses": { "200": { "description": "The membership was removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Always `true`." } } } } }, "example": { "meta": { "message": "Team membership revoked successfully." }, "data": { "deleted": true } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: the request used an API key, the caller is not an owner or admin, an admin tried to remove an owner, or the member is the workspace's last owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no membership with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Remove a team member", "description": "Removes a person from the workspace, or cancels a pending invitation, by membership id.\n\nFor a person who joined, removal takes effect at once: their sessions in the workspace end,\nthe API keys they created in it are revoked, and they no longer appear in the workspace. A\ncancelled invitation's link stops working. To bring someone back, invite them again.\n\nOnly owners and admins can remove members. Only an owner can remove an owner, and the\nworkspace's last owner cannot be removed.", "x-mint": { "href": "/api-reference/team/remove-a-team-member", "metadata": {}, "content": "\n API keys cannot call this endpoint: it answers `403 FORBIDDEN_ACTION` (\"API keys cannot\n access this endpoint.\"). Remove members in Heliyos under Settings, Team. Removal cannot be\n undone.\n\n\nIn the Heliyos MCP server: [`heliyos_team_members_remove`](/mcp/tools/team#heliyos-team-members-remove)." } } }, "/v1/auth/team-memberships/{id}/role": { "patch": { "operationId": "updateTeamMembershipRole", "tags": [ "Team" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "The membership id, from **List team members**.", "example": "6729e1f2a3b4c5d6e7f80912" } ], "responses": { "200": { "description": "The role was changed. `data` is an empty object.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "object", "description": "Empty object." } } }, "example": { "meta": { "message": "Role updated successfully." }, "data": {} } } } }, "400": { "description": "VALIDATION_FAILED: `roleId` is not a role you can give in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: the request used an API key, the caller is not an owner or admin, the caller targeted their own membership, an admin tried to grant or take away the owner role, or the member is the workspace's last owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no membership with this id in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The new role's id, from **List roles**: `OWNER`, `ADMIN` or `MEMBER`, or `AGENCY` in an agency workspace." } }, "required": [ "roleId" ], "additionalProperties": false }, "example": { "roleId": "66a0f1e2d3c4b5a697880a02" } } } }, "summary": "Change a team member role", "description": "Gives a member or a pending invitation a new role, by membership id. The change applies to the\nperson's next request.\n\nA person moved to a role below admin (`MEMBER`) loses the API keys they created in the\nworkspace: they are revoked.\n\nOnly owners and admins can change roles. Nobody can change their own role. Only an owner can\ngrant the owner role or change an owner's role, and the workspace's last owner cannot be\nmoved to another role.", "x-mint": { "href": "/api-reference/team/change-a-team-member-role", "metadata": {}, "content": "\n API keys cannot call this endpoint: it answers `403 FORBIDDEN_ACTION` (\"API keys cannot\n access this endpoint.\"). Change roles in Heliyos under Settings, Team.\n\n\nIn the Heliyos MCP server: [`heliyos_team_members_change_role`](/mcp/tools/team#heliyos-team-members-change-role)." } } }, "/v1/auth/roles": { "get": { "operationId": "listRoles", "tags": [ "Team" ], "parameters": [ { "name": "organizationType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "AGENCY", "STANDARD" ] }, "description": "Narrows the list to the roles of one kind of workspace:\n- `STANDARD`: `OWNER`, `ADMIN` and `MEMBER`.\n- `AGENCY`: `AGENCY` only.\n\nOmit it for every role except Heliyos staff roles.", "example": "STANDARD" } ], "responses": { "200": { "description": "The roles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } }, "example": { "meta": { "message": "Roles fetched successfully" }, "data": [ { "id": "66a0f1e2d3c4b5a697880a01", "name": "OWNER", "createdAt": "2026-01-10T00:00:00.000Z", "updatedAt": "2026-01-10T00:00:00.000Z" }, { "id": "66a0f1e2d3c4b5a697880a02", "name": "ADMIN", "createdAt": "2026-01-10T00:00:00.000Z", "updatedAt": "2026-01-10T00:00:00.000Z" }, { "id": "66a0f1e2d3c4b5a697880a03", "name": "MEMBER", "createdAt": "2026-01-10T00:00:00.000Z", "updatedAt": "2026-01-10T00:00:00.000Z" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "List roles", "description": "Returns the roles you can give people, with the ids that **Invite a team member** takes. Roles\nare the same for every workspace. Read the ids from this endpoint instead of hardcoding them.", "x-mint": { "href": "/api-reference/team/list-roles", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_team_members_change_role`](/mcp/tools/team#heliyos-team-members-change-role), [`heliyos_team_members_invite`](/mcp/tools/team#heliyos-team-members-invite), [`heliyos_team_members_list`](/mcp/tools/team#heliyos-team-members-list), [`heliyos_team_members_remove`](/mcp/tools/team#heliyos-team-members-remove)." } } }, "/v1/platform/notification-settings": { "get": { "operationId": "getNotificationSettings", "tags": [ "Notification settings" ], "parameters": [], "responses": { "200": { "description": "The settings, or an empty object when the workspace has never saved any. The message is \"Notification settings fetched successfully.\" when settings exist and \"No notification settings found.\" when they do not.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "allOf": [ { "$ref": "#/components/schemas/NotificationSettings" } ], "description": "The settings. An empty object when none were ever saved." } } }, "example": { "meta": { "message": "Notification settings fetched successfully." }, "data": { "id": "6721a9e0c4b5d6e7f8a9b0c1", "organizationId": "66a0f1e2d3c4b5a697887766", "notifyEmails": [ "ana.lopez@example.com", "revops@example.com" ], "eventTypes": [ { "type": "deal.approval", "frequency": "immediate" }, { "type": "task.created", "frequency": "daily" }, { "type": "organization.daily_summary", "frequency": "daily" } ], "isActive": true, "metadata": { "created": { "at": "2026-10-02T08:15:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-04T09:30:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Get notification settings", "description": "Returns the workspace's notification settings: whether notifications are on, who receives them,\nand which events notify and how often.\n\nThese are workspace settings, not settings of the person who owns the API key. Everyone in the\nworkspace reads and edits the same document.\n\nA workspace that has never saved settings has none: the response then has `data: {}` and\n`meta.message` \"No notification settings found.\", and no notification emails are sent (except\n`integration.not_synced`).", "x-mint": { "href": "/api-reference/notification-settings/get-notification-settings", "metadata": {}, "content": "In the Heliyos MCP server: [`heliyos_notification_settings_get`](/mcp/tools/notification-settings#heliyos-notification-settings-get)." } }, "patch": { "operationId": "updateNotificationSettings", "tags": [ "Notification settings" ], "parameters": [], "responses": { "200": { "description": "The saved settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A human-readable summary of the result." } } }, "data": { "$ref": "#/components/schemas/NotificationSettings" } } }, "example": { "meta": { "message": "Notification settings saved successfully." }, "data": { "id": "6721a9e0c4b5d6e7f8a9b0c1", "organizationId": "66a0f1e2d3c4b5a697887766", "notifyEmails": [ "ana.lopez@example.com", "revops@example.com" ], "eventTypes": [ { "type": "deal.approval", "frequency": "immediate" }, { "type": "task.created", "frequency": "daily" }, { "type": "organization.daily_summary", "frequency": "daily" } ], "isActive": true, "metadata": { "created": { "at": "2026-10-02T08:15:00.000Z", "by": "66a0f1e2d3c4b5a697881111" }, "updated": { "at": "2026-11-05T11:02:00.000Z", "by": "66a0f1e2d3c4b5a697881111" } } } } } } }, "400": { "description": "VALIDATION_FAILED: an empty body, an unknown event type or frequency, an invalid email address, or a recipient list that grows past 10 addresses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN_ACTION: notifyEmails changed by a member who is not an owner or admin. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notifyEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 0, "description": "The complete new recipient list. Replaces the current one. Each item must be a valid email address (surrounding spaces are trimmed). At most 10 addresses when you add any. Send `[]` to remove every recipient, which stops notifications.", "example": [ "ana.lopez@example.com", "revops@example.com" ] }, "eventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationEventType" }, "minItems": 0, "description": "The complete new list of notifying events, each `{ type, frequency }`. Replaces the current list. Send `[]` to turn off every event." }, "isActive": { "type": "boolean", "description": "Turns every notification email on (`true`) or off (`false`).", "example": true } }, "additionalProperties": false, "minProperties": 1 }, "examples": { "addEvent": { "summary": "Turn on approval emails and a daily task digest", "value": { "eventTypes": [ { "type": "deal.approval", "frequency": "immediate" }, { "type": "task.created", "frequency": "daily" }, { "type": "organization.daily_summary", "frequency": "daily" } ] } }, "pause": { "summary": "Pause all notification emails", "value": { "isActive": false } } } } } }, "description": "Changes the workspace's notification settings, creating them the first time. Send at least one\nfield. Each field you send replaces that setting completely; fields you leave out are kept.\n\n- `eventTypes` is the full list of notifying events. To add one event, read the current list,\n add to it and send the whole list back.\n- `notifyEmails` is the full recipient list. Changing who receives notifications needs an owner\n or admin (an API key counts as an admin). Sending the stored list back unchanged is allowed for\n anyone who can edit the settings. A list can grow to at most 10 addresses.\n- The first save of a workspace that had no settings starts from notifications on, no\n recipients and no events, then applies what you sent.", "summary": "Update notification settings", "x-mint": { "href": "/api-reference/notification-settings/update-notification-settings", "metadata": {}, "content": "\nNotification emails can contain record names and summaries. Only add addresses that should see\nthat information.\n\n\nIn the Heliyos MCP server: [`heliyos_notification_settings_update`](/mcp/tools/notification-settings#heliyos-notification-settings-update)." } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A workspace API key, sent as `Authorization: Bearer heliyos_...`. Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in." } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "message", "error" ], "properties": { "message": { "type": "string", "description": "Same as error.message." }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_FAILED", "UNAUTHENTICATED", "FORBIDDEN_ACTION", "NOT_FOUND", "RATE_LIMITED", "CONFLICT", "INTERNAL" ] }, "message": { "type": "string" }, "details": {} } } } }, "KeysetPagination": { "type": "object", "description": "Cursor paging. Pass `next_cursor` back as `cursor` with the same `limit` for the next page.", "required": [ "limit" ], "properties": { "limit": { "type": "integer", "description": "The page size used for this page.", "example": 20 }, "next_cursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." } } }, "OffsetPagination": { "type": "object", "description": "Page-number paging, used when you send `page` (or `offset`), a non-default sort, or grouping. Which keys are present depends on the endpoint; each endpoint's description lists them.", "additionalProperties": true, "properties": { "page": { "type": "integer", "description": "The page returned, starting at 1." }, "limit": { "type": "integer", "description": "Rows per page." }, "pageSize": { "type": "integer", "description": "Rows per page, on endpoints that call it pageSize." }, "offset": { "type": "integer", "description": "Rows skipped, on endpoints that page by offset." }, "total": { "type": "integer", "description": "Total matching rows, when the endpoint counts them." }, "count": { "type": "integer", "description": "Total matching rows, on endpoints that call it count." }, "totalPages": { "type": "integer", "description": "Number of pages at this page size." }, "hasMore": { "type": "boolean", "description": "Whether another page exists." } } }, "Workspace": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace's id. Every record, task and worker in this API belongs to it." }, "name": { "type": "string", "description": "The workspace's name." }, "billingStatus": { "type": "string", "nullable": true, "enum": [ "active", "trialing", "past_due", "canceled", "incomplete", "incomplete_expired", "pending_payment" ], "description": "The subscription's billing state:\n- `active`: paid and current.\n- `trialing`: in a free trial.\n- `past_due`: a payment failed and is being retried.\n- `canceled`: the subscription ended.\n- `incomplete`: the first payment has not gone through yet.\n- `incomplete_expired`: the first payment never went through and the attempt expired.\n- `pending_payment`: waiting for a payment to complete.\n\n`null` when the workspace has no billing state recorded.\n" }, "plan": { "type": "object", "nullable": true, "description": "The active plan. `null` when the workspace has no active plan.", "properties": { "name": { "type": "string", "description": "The plan's name. Can be an empty string when the plan's product has no name." } } }, "memberCount": { "type": "integer", "minimum": 0, "description": "How many distinct people have a role in the workspace." }, "recordCounts": { "type": "object", "description": "How many records the workspace holds in the built-in objects.", "properties": { "companies": { "type": "integer", "minimum": 0, "description": "Company records." }, "people": { "type": "integer", "minimum": 0, "description": "People records." }, "deals": { "type": "integer", "minimum": 0, "description": "Deal records, across every deal pipeline." } } }, "watchersInUse": { "type": "integer", "minimum": 0, "description": "How many companies are on the watchlist right now." }, "watchersLimit": { "type": "integer", "nullable": true, "minimum": 0, "description": "The most companies the active plan lets you watch. `null` when the workspace has no active plan." } } }, "UsageEntry": { "type": "object", "description": "One credit charge. Entries are written by Heliyos when a feature spends credits; you cannot create or change them.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace that was charged." }, "feature": { "type": "string", "description": "What spent the credits. Values written today:\n- `worker_run`: a custom worker called during a run (default workers are free).\n- `company_enrichment`: a company was enriched.\n- `people_enrichment`: people were enriched for a lead set.\n- `leadset_enrichment`: lead set columns were enriched.\n- `leadset_match`: a lead set search and match.\n- `ai_column`: AI column research on records.\n- `scout`: a Scout run.\n- `meeting_analysis`: a meeting recording was analysed.\n- `agent_operation`: a generic charge with no more specific feature.\n\nOlder entries can carry other names. Treat the field as an open set.\n", "example": "worker_run" }, "creditsUtilized": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Credits spent by this entry. Always greater than 0.", "example": 5 }, "objectId": { "type": "string", "description": "Id of what the credits were spent on, when there is one: a record id, or a run id for `worker_run`. Free text, not always a 24-character id." }, "objectType": { "type": "string", "description": "The kind of thing `objectId` names, for example `orchestrator_run` for a worker run. Often absent." }, "sourceService": { "type": "string", "enum": [ "platform", "agent", "other" ], "description": "Which part of Heliyos recorded the charge." }, "description": { "type": "string", "description": "A short human-readable note about the charge." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Extra detail about the charge. For `worker_run`, `workerId` and `tool` name the worker that was called." }, "meta": { "type": "object", "additionalProperties": true, "description": "An index copy of `organizationId`, `feature` and `sourceService`. Carries nothing the entry does not already have." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" } } }, "SchemaObject": { "type": "object", "description": "An object (base schema) and its fields.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The object's id. Records name it as their `schemaId`. List, create and update return it as `id`; get returns it as `_id`." }, "_id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The object's id, as returned by get." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the object belongs to." }, "name": { "type": "string", "description": "The display name, for example `Partners`. Unique in the workspace." }, "slug": { "type": "string", "description": "A short URL-safe name, unique in the workspace, used in web app links." }, "description": { "type": "string", "description": "What the object holds." }, "type": { "type": "string", "enum": [ "base", "computed", "custom" ], "description": "The object's kind. `base` for the built-in objects (companies, people and deal pipelines), `custom` for objects you create. `computed` is accepted but not used by Heliyos." }, "objectType": { "type": "string", "description": "The record type records of this object carry: `company`, `people` and `deals` for the built-in objects. For a custom object it is derived from the name when the object is created (lowercase, spaces replaced by underscores, plus a 4-digit suffix if it is already taken) and never changes afterwards.", "example": "partners" }, "icon": { "type": "string", "description": "The icon name the web app shows for the object." }, "iconColor": { "type": "string", "description": "A label colour family for the icon, for example `blue`." }, "viewType": { "type": "string", "enum": [ "table", "kanban" ], "description": "How the web app shows the object by default. Deal pipelines use `kanban`." }, "kanbanConfig": { "$ref": "#/components/schemas/SchemaKanbanConfig" }, "fields": { "type": "array", "description": "The object's fields that you may view, in storage order. Sort by `sequence` for display order. Fields whose permissions hide them from you are left out.", "items": { "$ref": "#/components/schemas/SchemaField" } }, "permissions": { "$ref": "#/components/schemas/SchemaPermissions" }, "agents": { "type": "array", "description": "Reserved for internal use.", "items": { "type": "object", "additionalProperties": true } }, "recordCount": { "type": "integer", "description": "How many records the object has. Only in a list sent with `isRecordCount=true`." }, "created": { "type": "object", "description": "When the object was created, and by whom.", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Id of the user who created it, or `system` for built-in objects." } } }, "updated": { "type": "object", "description": "When the object was last changed, and by whom.", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Id of the user who last changed it." } } } } }, "SchemaKanbanConfig": { "type": "object", "description": "The board layout. Each lane is one option of the lane field. Lanes are managed in the web app; changing the lane field's `settings.selectOptions` adds and removes lanes to match.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "laneField": { "type": "string", "description": "The key of the select field whose options are the lanes, for example `stage`." }, "lanes": { "type": "array", "description": "The board's lanes.", "items": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "name": { "type": "string", "description": "The lane's name, equal to one option of the lane field." }, "order": { "type": "number", "description": "The lane's position on the board." }, "color": { "type": "string", "description": "A label colour family, for example `green`." }, "icon": { "type": "string", "description": "An optional icon name." }, "isVisible": { "type": "boolean", "description": "false when the lane is hidden on the board." } } } } } }, "SchemaPermissions": { "type": "object", "description": "Who may view and edit. With `organization`, every member may. With `private`, only the roles and users listed (and the creator). API keys act with the `ADMIN` role.", "properties": { "visibility": { "type": "string", "description": "`organization` or `private`. Objects also store `public`, which behaves like an allow list of roles and users." }, "editableBy": { "type": "object", "description": "Who may edit when `visibility` is `private`.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names: `OWNER`, `ADMIN`, `MEMBER`, `STAFF`, `SUPPORT`, `SUPER_ADMIN`, `AGENCY`." }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "description": "User ids." } } }, "viewableBy": { "type": "object", "description": "Who may view when `visibility` is `private`.", "properties": { "roles": { "type": "array", "items": { "type": "string" }, "description": "Role names, as in `editableBy`." }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" }, "description": "User ids." } } } } }, "SchemaFieldType": { "type": "object", "description": "The field's type. See the field types table on Create a field.", "properties": { "type": { "type": "string", "enum": [ "text", "richText", "number", "currency", "rating", "checkbox", "date", "timestamp", "select", "multiSelect", "url", "email", "phone", "user", "image", "relationship", "file" ], "description": "What the field holds. `file` exists on some fields but cannot be created through the API." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Related kinds the web app uses for the field's editors, for example `[\"text\", \"richText\"]`. A list containing `multiSelect` or `array` makes CSV import split values on commas." }, "relationshipSchemaId": { "type": "string", "description": "`relationship` fields: id of the object the field links to." }, "relationshipConfig": { "type": "array", "description": "`relationship` fields: how the link maps onto the other object.", "items": { "type": "object", "properties": { "targetSchema": { "type": "string", "description": "Id of the linked object." }, "associatedField": { "type": "string", "description": "Key of the matching field on the linked object." }, "inverseName": { "type": "string", "description": "Key of this side of the link." }, "onDelete": { "type": "string", "enum": [ "cascade", "setNull", "restrict" ], "description": "What the link should do when the linked record is deleted. Defaults to `setNull`." } } } } } }, "SchemaFieldSettings": { "type": "object", "description": "Type-specific configuration.", "properties": { "selectOptions": { "type": "array", "description": "`select` and `multiSelect`: the choices, in order. Each is `{ \"value\", \"color\" }` (a label colour family) or a bare string.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string", "description": "The option's text, which is what records store." }, "color": { "type": "string", "description": "A label colour family: `red`, `orange`, `amber`, `olive`, `green`, `teal`, `blue`, `purple`, `pink` or `gray`." } } } ] } }, "currencyOptions": { "type": "object", "description": "`currency`: how the web app formats amounts.", "properties": { "currency": { "type": "string", "description": "A two-letter country code whose currency is used, for example `US` for US dollars or `DE` for euros." }, "display": { "type": "string", "description": "`symbol` ($1,200), `code` (USD 1,200) or `name` (1,200 US Dollar)." } } }, "abbreviateNumber": { "type": "boolean", "description": "`number` and `currency`: show large values as 1.2k, 3.4M and so on." }, "defaultValue": { "description": "The value a new record gets when it is created without one (missing, null or an empty string). Must fit the field's type." }, "aiRunStatus": { "type": "string", "enum": [ "RUNNING", "PENDING", "FINISHED", "ERROR", "" ], "description": "A display status for an AI column, set by the web app. Heliyos does not update it." } } }, "SchemaField": { "type": "object", "description": "One field of an object.", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The field's id. Use it as `fieldId` to change or delete the field.", "example": "6730c2d5e4f6a7b8c9d0e1f2" }, "_id": { "type": "string", "description": "An internal id some responses include. Address the field by `id`." }, "name": { "type": "string", "description": "The field's key, which records use in `data` and filters name, for example `contract_value`." }, "displayName": { "type": "string", "description": "The label shown in the web app." }, "description": { "type": "string", "description": "What the field holds. Shown in the web app and read by workers." }, "icon": { "type": "string", "description": "The icon name the web app shows next to the label." }, "sequence": { "type": "number", "description": "The field's position in the object, starting at 1." }, "type": { "$ref": "#/components/schemas/SchemaFieldType" }, "settings": { "$ref": "#/components/schemas/SchemaFieldSettings" }, "isAIEnabled": { "type": "boolean", "description": "true when workers fill the field from `aiPrompt` (an AI column)." }, "aiPrompt": { "type": "object", "nullable": true, "description": "The AI column's prompt.", "properties": { "prompt": { "type": "string", "description": "The instructions workers follow to fill the field." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Names of the fields the prompt mentions." } } }, "isHiddenField": { "type": "boolean", "description": "true when the field is hidden from table views by default." }, "isVisibleOnlyInPage": { "type": "boolean", "description": "true when the field shows only on the record page, not in tables." }, "isReadOnly": { "type": "boolean", "description": "true when the web app shows the field as read-only. The API does not enforce it." }, "required": { "type": "boolean", "description": "true when creating a record without this key fails." }, "unique": { "type": "boolean", "description": "Shown in the web app. The API does not enforce uniqueness on record writes." }, "validation": { "type": "object", "description": "Rules checked when a record is written.", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The rule. See `validation` on Create a field." }, "value": { "description": "The rule's argument." }, "message": { "type": "string", "description": "A message for people editing the record." } } } } } }, "default": { "type": "object", "description": "A stored default. Records are not filled from it; `settings.defaultValue` does that.", "properties": { "type": { "type": "string", "enum": [ "static", "dynamic" ] }, "value": { "description": "The default value." } } }, "permissions": { "$ref": "#/components/schemas/SchemaPermissions" }, "hasAccess": { "type": "boolean", "description": "Present in lists. Always true, because fields you may not view are left out." }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "RecordRelationship": { "type": "object", "description": "A link from this record to another record in the workspace.", "properties": { "_id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the link itself." }, "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the linked record." }, "schemaId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the linked record's object." }, "objectType": { "type": "string", "description": "The linked record's object type: `company`, `people`, `deals` or a custom object's type.", "example": "company" }, "data": { "type": "object", "additionalProperties": true, "description": "List responses only: the linked record's field values. Empty when the linked record no longer exists, and absent when the list was requested with `\"enrich\": false`." }, "fullData": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Get responses only. The complete linked record, in the same shape as `Record`." } } }, "Record": { "type": "object", "description": "One record. Which properties are present depends on the endpoint: list responses add activity counts, the get response adds `id`, `notes` and `tasks`.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "id": { "type": "string", "description": "Get responses only. The record's id as a string, the same as `_id`." }, "baseSchemaId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The object the record belongs to." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the record belongs to." }, "objectType": { "type": "string", "description": "The object's type: `company`, `people`, `deals` or a custom object's type.", "example": "deals" }, "data": { "type": "object", "additionalProperties": true, "description": "The field values, keyed by the object's field keys. In list and get responses `data` holds only the object's fields, and a field you may not view is `null`. Create and update responses return the values as stored." }, "relationships": { "type": "array", "description": "The records this record is linked to.", "items": { "$ref": "#/components/schemas/RecordRelationship" } }, "enrichmentStatus": { "type": "string", "nullable": true, "enum": [ "NOT_ENRICHED", "STARTED", "FINISHED", "FAILED" ], "description": "Companies and people only. `NOT_ENRICHED` on create, `STARTED` while an enrichment runs, `FINISHED` or `FAILED` after it." }, "enrichmentDate": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When the record was last enriched, or null." }, "isAgentAssigned": { "type": "boolean", "description": "`true` when a worker watches the record (the record is on the watchlist)." }, "agentAssignmentStatus": { "type": "string", "nullable": true, "description": "`STARTED` while a newly assigned worker is setting up, otherwise null or absent." }, "aiColumnStatus": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The run status of each AI field on this record, keyed by field key, for example `NOT_STARTED`." }, "hubspotId": { "type": "string", "description": "The record's HubSpot id, when the workspace syncs it to HubSpot. Not in list responses." }, "workspaceFolder": { "type": "string", "description": "The record's folder in the worker workspace, when one exists. Not in list responses." }, "commentCount": { "type": "integer", "description": "List responses only. Open comment threads linked to the record. 0 with `\"enrich\": false`." }, "noteCount": { "type": "integer", "description": "List responses only. Notes linked to the record. 0 with `\"enrich\": false`." }, "taskCount": { "type": "integer", "description": "List responses only. Unfinished tasks linked to the record. 0 with `\"enrich\": false`." }, "notes": { "type": "array", "description": "Get responses only. Every note linked to the record, newest first.", "items": { "type": "object", "additionalProperties": true } }, "tasks": { "type": "array", "description": "Get responses only. Every task linked to the record, newest first.", "items": { "type": "object", "additionalProperties": true } }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "RecordKanbanColumn": { "type": "object", "description": "One column of a board, returned by List records when `filters` has `\"viewType\": \"kanban\"`.", "properties": { "columnId": { "description": "The grouping field's value shared by the column's records, or `uncategorized` when they have none." }, "items": { "type": "array", "description": "Every matching record with this value. Items carry `_id`, `baseSchemaId`, `organizationId`, `objectType`, `data`, `metadata`, `relationships` and the three activity counts.", "items": { "$ref": "#/components/schemas/Record" } }, "pagination": { "type": "object", "description": "Always one page: `{ page: 1, limit, totalPages: 1, count, hasMore: false }`, where `limit` and `count` are the column's size.", "additionalProperties": true } } }, "RecordLookupRow": { "type": "object", "description": "A compact entry for one record, for local name search.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The record's id." }, "name": { "type": "string", "description": "The record's display name: the first non-empty text value among the object's first field (by position) and `company_name`, `people_name`, `deal_name`, `name`, `title`, using only fields you may view. Empty when none has a value." }, "secondary": { "type": "string", "description": "A supporting value: the first of `domain`, `email`, `job_title` or `stage` that the object has and you may view. Absent when that field is empty or not text." }, "imageUrl": { "type": "string", "description": "The `logo` or `profile_pic` value, when the object has one of them and it is set." }, "isWatched": { "type": "boolean", "description": "`true` when a worker watches the record." }, "updatedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the record last changed." } } }, "TimelineEntry": { "type": "object", "description": "One AI-written timeline entry. Heliyos writes entries on a schedule: each run reads the latest emails, meetings, tasks and changes around a company and writes one summary for the company and for each related person and deal that had activity.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "timestamp": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the entry was written." }, "metadata": { "type": "object", "properties": { "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The record the entry is about." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "baseSchemaId": { "type": "string", "nullable": true, "description": "The record's object (base schema) id. Null when it was not known at write time." }, "relationshipObjectType": { "type": "string", "enum": [ "company", "people", "deals" ], "description": "The kind of record the entry is about." }, "summary": { "type": "string", "description": "The entry text, in markdown. What happened in the period it covers." } } } } }, "RecordEvent": { "type": "object", "description": "One change in the audit trail. Snapshots are stored as they were at the time of the change, with credential values (tokens, secrets, passwords, API keys) replaced by `[REDACTED]`.", "additionalProperties": true, "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "timestamp": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the change happened." }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "eventType": { "type": "string", "enum": [ "AUDIT", "INTERACTION", "ENRICHMENT" ], "description": "`AUDIT`: a person or worker created, changed or deleted something (a record, task, note, comment, file, view and so on). `INTERACTION`: an email thread or meeting was synced, updated or analysed. `ENRICHMENT`: data enrichment wrote to a record." }, "operationType": { "type": "string", "enum": [ "CREATE", "UPDATE", "DELETE" ], "description": "What happened to the changed resource." }, "objectType": { "type": "string", "description": "The kind of resource that changed, for example `company`, `people`, `deals`, `task`, `note`, `comment`, `attachment` (a file) or `interaction`. Older deal events may say `deal`." }, "objectUUID": { "type": "string", "description": "The id of the resource that changed. Not always the record you asked for (see the list description)." }, "organizationUUID": { "type": "string", "description": "The workspace id." }, "actor": { "type": "object", "description": "Who made the change.", "properties": { "type": { "type": "string", "enum": [ "USER", "AGENT", "SYSTEM" ], "description": "`USER`: a person or an API key. `AGENT`: a worker. `SYSTEM`: Heliyos itself, for example the inbox sync." }, "uuid": { "type": "string", "description": "For `USER`, the user id. For `AGENT`, the worker run id (older entries say `agent`). For `SYSTEM`, usually `system`." }, "name": { "type": "string", "description": "A display name, such as the person's name or the worker's name." } } } } }, "changeSummary": { "type": "string", "description": "A one-line, human-readable description of the change, written by Heliyos." }, "originalVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The resource before the change. Null or empty for a create." }, "updatedVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The resource after the change. Null for a delete." } } }, "TaskEvent": { "type": "object", "description": "One change to a task. Snapshots are stored as they were at the time of the change, with credential values (tokens, secrets, passwords, API keys) replaced by `[REDACTED]`.", "additionalProperties": true, "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "timestamp": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the change happened." }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "eventType": { "type": "string", "description": "`AUDIT` on every task event: a person or worker created or changed the task. The other event types (`INTERACTION`, `ENRICHMENT`) belong to records and do not appear here.", "example": "AUDIT" }, "operationType": { "type": "string", "enum": [ "CREATE", "UPDATE", "DELETE" ], "description": "`CREATE`: the task was created. `UPDATE`: the task changed. `DELETE` is recorded when a task is deleted, but a deleted task's history can no longer be read here (the call answers 404)." }, "objectType": { "type": "string", "description": "Always `task`." }, "objectUUID": { "type": "string", "description": "The task's id. Always the task you asked for." }, "organizationUUID": { "type": "string", "description": "The workspace id." }, "actor": { "type": "object", "description": "Who made the change.", "properties": { "type": { "type": "string", "enum": [ "USER", "AGENT", "SYSTEM" ], "description": "`USER`: a person, in the Heliyos app or through an API key. `AGENT`: a worker. `SYSTEM`: Heliyos itself. Task changes are almost always `USER` or `AGENT`." }, "uuid": { "type": "string", "description": "For `USER`, the user id (for an API key, the key owner's id). For `AGENT`, the worker run id; older entries say `agent`." }, "name": { "type": "string", "description": "A display name: the person's name, or the worker's name (`Heliyos` when Heliyos itself made the change during a run)." } } } } }, "changeSummary": { "type": "string", "description": "A one-line, human-readable description of the change, written by Heliyos shortly after the change. Can be missing on very recent or older events." }, "originalVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The task before the change: null or empty for a create. With `fields`, only the requested fields are present." }, "updatedVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The task after the change. With `fields`, only the requested fields are present." } } }, "InteractionMessage": { "type": "object", "description": "One message in an email thread.", "additionalProperties": true, "properties": { "message_id": { "type": "string", "description": "The mail provider's message id." }, "thread_id": { "type": "string", "description": "The mail provider's thread id." }, "subject": { "type": "string", "description": "The message subject." }, "snippet": { "type": "string", "description": "A short plain-text preview." }, "body": { "type": "string", "description": "The message body (HTML or text), when synced." }, "date": { "type": "integer", "description": "When the message was sent, in Unix seconds." }, "from": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, "description": "Sender." }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, "description": "Recipients." }, "cc": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Copied recipients." }, "unread": { "type": "boolean", "description": "Whether the message is unread in the mailbox." }, "starred": { "type": "boolean", "description": "Whether the message is starred in the mailbox." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Metadata for the files attached to the message." }, "agentGenerated": { "type": "boolean", "description": "True when a worker wrote this message." }, "isDraft": { "type": "boolean", "description": "True for a worker's unsent draft." } } }, "Interaction": { "type": "object", "description": "A synced email thread (`channel.type` `email`) or calendar meeting (`channel.type` `meeting`). Heliyos stores the provider's data and adds AI analysis. Fields depend on the channel and on how far the analysis has got; treat every field except `_id`, `organizationId` and `channel` as optional, and ignore fields you do not recognise.", "additionalProperties": true, "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "channel": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "meeting" ], "description": "`email` for an email thread, `meeting` for a calendar event." }, "email": { "type": "string", "description": "The connected mailbox or calendar the interaction was synced from." } } }, "integrationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The connected mailbox or calendar integration that synced it." }, "relationships": { "type": "array", "description": "The records this interaction is linked to (matched from participants' addresses). Each entry carries `objectId`, `objectType` and `schemaId`, plus `object`: the linked record's `_id`, `objectType`, `baseSchemaId`, `isAgentAssigned` and all of its field values in `data`.", "items": { "type": "object", "additionalProperties": true, "properties": { "objectId": { "$ref": "#/components/schemas/ObjectId" }, "objectType": { "type": "string", "description": "`company`, `people` or `deals`." }, "schemaId": { "type": "string", "nullable": true, "description": "The linked record's object id." }, "object": { "type": "object", "additionalProperties": true, "description": "The linked record. Absent when the record no longer exists." } } } }, "categoryIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of the labels applied to this interaction." }, "classificationLabels": { "type": "array", "description": "The labels in `categoryIds`, resolved (`_id`, `name`, `description`, `color`, `labels`).", "items": { "type": "object", "additionalProperties": true } }, "summary": { "type": "string", "description": "The AI summary. Empty until the interaction is analysed." }, "sentiment": { "type": "string", "nullable": true, "description": "The other party's sentiment, written by the analysis. Usually `Positive`, `Negative`, `Neutral`, `Excited` or `Do Not Contact`. Null until analysed." }, "sentimentReason": { "type": "string", "description": "Why the analysis chose that sentiment." }, "isSummarized": { "type": "boolean", "description": "Whether the AI analysis has run." }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When Heliyos first synced it. Some older interactions store this as text." }, "lastMessageDate": { "type": "integer", "description": "The newest message time (email) or the start time (meeting), in Unix seconds." }, "subject": { "type": "string", "description": "Email: the thread subject." }, "thread_id": { "type": "string", "description": "Email: the mail provider's thread id." }, "threads": { "type": "array", "description": "Email: the messages in the thread, oldest first.", "items": { "$ref": "#/components/schemas/InteractionMessage" } }, "title": { "type": "string", "description": "Meeting: the event title." }, "when": { "type": "object", "description": "Meeting: start and end, in Unix seconds, with time zones.", "properties": { "start_time": { "type": "integer" }, "end_time": { "type": "integer" }, "start_timezone": { "type": "string" }, "end_timezone": { "type": "string" } } }, "participants": { "type": "array", "description": "Meeting: invitees, each with `email` and `status`, the response as the calendar provider reports it (for example `yes`, `no` or `maybe`).", "items": { "type": "object", "additionalProperties": true, "properties": { "email": { "type": "string" }, "status": { "type": "string" } } } }, "creator": { "type": "object", "description": "Meeting: who created the event (`name`, `email`).", "additionalProperties": true }, "conferencing": { "type": "object", "description": "Meeting: the video provider and join details.", "additionalProperties": true }, "meetingStatus": { "type": "string", "description": "Meeting: where recording and analysis stand. One of `NOT_STARTED`, `IN_PROGRESS`, `ANALYSING`, `COMPLETED`, `CANCELLED`, `RECORDING_NOT_PERMITTED`, `ABANDONED` or `ERROR`." }, "transcript": { "type": "array", "description": "Meeting: the transcript, when the meeting was recorded.", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "speaker": { "type": "string" }, "dialogue": { "type": "string" } } } }, "takeaways": { "type": "string", "description": "Meeting: takeaways from the analysis." }, "keyTakeaways": { "type": "string", "description": "Meeting: key takeaways from the analysis." }, "nextSteps": { "description": "Meeting: next steps from the analysis, as text or a list.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] } } }, "Note": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the note belongs to." }, "title": { "type": "string", "description": "The note's title. Can be an empty string." }, "content": { "type": "string", "description": "The note's body, as plain text or simple HTML." }, "relationships": { "type": "array", "description": "The records, tasks and interactions the note is linked to.", "items": { "$ref": "#/components/schemas/Relationship" } }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "TaskStatus": { "type": "string", "enum": [ "backlog", "in_progress", "scheduled_for_later", "on_hold", "cancelled", "completed" ], "description": "The task's stage on the board:\n- `backlog`: not started. The default.\n- `in_progress`: being worked on, by a person or by workers.\n- `scheduled_for_later`: a worker set a wake-up for it and will pick it up at that time.\n- `on_hold`: waiting on a person or an outside event.\n- `cancelled`: dropped.\n- `completed`: done.\n" }, "TaskPriority": { "type": "string", "enum": [ "none", "low", "medium", "high", "urgent" ], "description": "The task's priority. Defaults to `medium`." }, "TaskAssignee": { "type": "object", "description": "A person assigned to the task.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The user's id. Must be a member of the workspace." }, "name": { "type": "string", "description": "The name shown on the task. Stored as sent." }, "profilePicture": { "type": "string", "nullable": true, "description": "An avatar URL shown on the task. Stored as sent." } } }, "TaskWorkerAssignment": { "type": "object", "description": "A worker assigned to the task.", "properties": { "agentId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The worker's id. Must be one of the workspace's workers." }, "name": { "type": "string", "description": "The worker's name, shown on the task. Stored as sent." }, "role": { "type": "string", "enum": [ "executor", "reviewer", "approver" ], "description": "`executor` does the work, `reviewer` checks it, `approver` signs it off." } } }, "TaskRunState": { "type": "object", "description": "The workers' current or last run on the task. Present only when the task has had a run, a worker note or a scheduled wake-up.", "properties": { "status": { "type": "string", "description": "The run's status, for example `queued`, `running`, `paused`, `awaiting_approval` (a worker action waits for review), `waiting`, `completed`, `failed` or `stopped`. `stalled` means the run says it is running but has written nothing for 20 minutes." }, "summary": { "type": "string", "description": "The last note a worker left on the task." }, "planSteps": { "type": "integer", "description": "Steps in the run's plan." }, "completedSteps": { "type": "integer", "description": "Plan steps completed or skipped." }, "artifactsCount": { "type": "integer", "description": "Files linked to the task." }, "lastRunAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the run last changed." }, "hasSchedule": { "type": "boolean", "description": "True when a worker scheduled a wake-up for the task." }, "nextRunReason": { "type": "string", "description": "Why the worker scheduled the wake-up." }, "nextRunAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the wake-up fires. Absent for a recurring schedule." } } }, "Task": { "type": "object", "additionalProperties": true, "properties": { "_id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The task's id. Create and update responses name it `id` instead." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the task belongs to." }, "title": { "type": "string", "description": "The task's title. Can be an empty string." }, "description": { "type": "string", "description": "The task's body, as plain text or markdown." }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "isFinished": { "type": "boolean", "description": "A done flag kept beside `status`. Heliyos does not derive it from `status`: set it yourself when you complete or reopen a task." }, "dueDate": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the task is due. Absent when none is set." }, "assignedUser": { "type": "array", "description": "The people assigned to the task.", "items": { "$ref": "#/components/schemas/TaskAssignee" } }, "assignedAgents": { "type": "array", "description": "The workers assigned to the task.", "items": { "$ref": "#/components/schemas/TaskWorkerAssignment" } }, "relationships": { "type": "array", "description": "The records the task is linked to. In list and get responses each entry is hydrated with the record's field values in `data` and its object in `schema`.", "items": { "$ref": "#/components/schemas/Relationship" } }, "currentRunId": { "type": "string", "description": "The id of the workers' current or last run on the task." }, "currentRun": { "$ref": "#/components/schemas/TaskRunState" }, "artifactsCount": { "type": "integer", "description": "Files linked to the task. List and get only." }, "agentPaused": { "type": "boolean", "description": "True when workers are paused on this task. Starting a run clears it." }, "agentRun": { "type": "object", "additionalProperties": true, "description": "The last note a worker left on the task (`note`, `runId`, `agent`, `at`)." }, "planCheckpoints": { "type": "array", "description": "The steps of the workers' plan for the task, each with `id`, `title`, `description`, `worker`, `note` and `status` (`pending`, `running`, `completed`, `failed` or `skipped`).", "items": { "type": "object", "additionalProperties": true } }, "hubspotTaskId": { "type": "string", "description": "The linked HubSpot task id, when the workspace syncs tasks with HubSpot." }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "TaskRelationshipInput": { "type": "object", "description": "A record to link the task to.", "required": [ "objectId" ], "properties": { "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the linked record, task, note or interaction. Must belong to this workspace." }, "schemaId": { "type": "string", "nullable": true, "description": "The linked record's object (base schema) id. Recommended for records. Empty or null is dropped." }, "objectType": { "type": "string", "nullable": true, "description": "`company`, `people`, `deals` or a custom object type for records; `task`, `note` or `interaction` otherwise.", "example": "company" }, "data": { "type": "object", "additionalProperties": true, "description": "An optional display snapshot of the record, stored as sent. Get and list replace it with the record's current values." } } }, "TaskRunStart": { "type": "object", "properties": { "triggered": { "type": "boolean", "description": "True when this call started a new run. False when a run already open on the task was returned instead." }, "orchestratorRunId": { "type": "string", "description": "The run's id. Follow it with `GET /v1/platform/workers/runs/{id}`." }, "status": { "type": "string", "description": "The run's status: `queued` for a new run; for an existing run, its current status (`queued`, `running`, `paused`, `awaiting_approval` or `waiting`)." } } }, "WorkerTriggerInput": { "type": "object", "description": "One thing that starts the worker.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "task_created", "mention", "event", "scheduled", "webhook", "schedule", "playground" ], "description": "- `task_created`: the worker runs when a task is created. `match.taskType` limits it to some task types.\n- `mention`: the worker runs when someone mentions it in chat. Every active worker answers mentions, with or without this entry; `match.mentionPattern` is kept with it.\n- `event`: the worker runs on the named events in `events`, for example `task.created`,\n `deal.updated`, `email.received`, `meeting.completed` or `company.attribute_updated`.\n `*` means every event. An event name that Heliyos never emits never matches.\n- `scheduled`: the worker runs on a schedule. Put a 5-field cron in `match.schedule` (UTC unless\n `match.timezone` is set), or a one-time local time in `match.at` with `match.timezone`.\n- `webhook`: older spelling of `event`, with the event name in `match.webhookEvent`. Saved as `event`.\n- `schedule`: older spelling of `scheduled`. Saved as `scheduled`.\n- `playground`: used by test runs in the Heliyos app. Has no effect when set through the API.\n" }, "source": { "type": "string", "enum": [ "default", "user" ], "description": "Accepted and ignored. Triggers you send are always saved with `source` `user`." }, "events": { "type": "array", "maxItems": 200, "description": "`event` triggers only: the event names to run on. Up to 200 names of up to 200 characters.", "items": { "type": "string", "maxLength": 200 }, "example": [ "deal.updated", "meeting.completed" ] }, "match": { "type": "object", "description": "Conditions and timing. These keys are stored; any other key is dropped:\n- `taskType` (array of strings): `task_created` only, the task types to run on.\n- `taskStatus` (string): a task status condition.\n- `mentionPattern` (string): `mention` only, text the mention must contain.\n- `webhookEvent` (string or array): `webhook` only, the event names.\n- `schedule` (string): `scheduled` only, a 5-field cron such as `0 8 * * 1-5`.\n- `at` (string): `scheduled` only, a one-time local wall time `YYYY-MM-DDTHH:MM:SS`.\n- `timezone` (string): an IANA zone such as `Europe/Berlin` for `schedule` or `at`. Default UTC.\n- `recurrence` (object): the Heliyos app's own description of the schedule, so its editor can reopen it.\n", "additionalProperties": true, "example": { "schedule": "0 8 * * 1-5", "timezone": "Europe/Berlin" } }, "dependencies": { "type": "array", "maxItems": 50, "description": "Ids of other workers in this workspace that must finish before this one starts. Up to 50.", "items": { "$ref": "#/components/schemas/ObjectId" } } } }, "WorkerTrigger": { "type": "object", "description": "A stored trigger. Event subscriptions are stored as `event`, schedules as `scheduled`.", "properties": { "type": { "type": "string", "description": "`task_created`, `mention`, `event`, `scheduled` or `playground`. Workers saved long ago can still show `webhook` or `schedule`." }, "source": { "type": "string", "enum": [ "default", "user" ], "description": "`default`: built into a default worker. It stays when you change the worker's triggers. `user`: added by a person or the API, removable." }, "events": { "type": "array", "description": "`event` triggers: the subscribed event names.", "items": { "type": "string" } }, "match": { "type": "object", "additionalProperties": true, "description": "Conditions and timing, as in the trigger input." }, "dependencies": { "type": "array", "description": "Workers that must finish first.", "items": { "$ref": "#/components/schemas/ObjectId" } } } }, "WorkerResources": { "type": "object", "description": "The knowledge files the worker reads.", "properties": { "scope": { "type": "string", "enum": [ "everything", "org_knowledge", "account_files", "selected_files" ], "description": "The file scope picked in the Heliyos app: `everything` (the default), `org_knowledge`\n(knowledge base files), `account_files` (files on records) or `selected_files` (files you\npick). Which knowledge base files the worker reads is set by `allKbFiles` and\n`linkedKbFileIds`.\n" }, "allKbFiles": { "type": "boolean", "description": "`true` links every knowledge base file of the workspace. When absent, every file is linked unless `linkedKbFileIds` names some." }, "linkedKbFileIds": { "type": "array", "maxItems": 1000, "description": "Knowledge base files linked to the worker. Each must be a file of this workspace. Up to 1,000.", "items": { "$ref": "#/components/schemas/ObjectId" } }, "fileIds": { "type": "array", "maxItems": 1000, "description": "Other files picked for the worker. Each must be a file of this workspace. Up to 1,000.", "items": { "$ref": "#/components/schemas/ObjectId" } } } }, "Worker": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the worker belongs to." }, "name": { "type": "string", "description": "The worker's name, unique in the workspace." }, "type": { "type": "string", "enum": [ "default", "custom" ], "description": "`default`: built into every workspace. Only its instructions, description, icon, active flag, memory and its own triggers can change, and it cannot be deleted. `custom`: created by you, fully editable and deletable." }, "isActive": { "type": "boolean", "description": "`false` pauses the worker: nothing starts it and Heliyos does not call it." }, "icon": { "type": "string", "description": "The icon the Heliyos app shows for the worker." }, "isExcluded": { "type": "boolean", "description": "`true` for older built-in workers that run on a separate pipeline. They are listed for reference, and Heliyos never calls them." }, "description": { "type": "string", "description": "One line that tells Heliyos (and people) what the worker is for. Heliyos reads it to decide when to call the worker." }, "instructions": { "type": "string", "description": "What the worker does and how, in Markdown." }, "toolName": { "type": "string", "description": "The stable snake_case name Heliyos calls the worker by. Set on create and never changed." }, "toolNames": { "type": "array", "description": "The built-in tools the worker may use, by name.", "items": { "type": "string" } }, "actionIds": { "type": "array", "description": "The workspace actions the worker may run.", "items": { "$ref": "#/components/schemas/ObjectId" } }, "toolPolicy": { "type": "object", "description": "Limits on what the worker may do.", "properties": { "readOnly": { "type": "boolean", "description": "`true`: the worker may read but never change data." } } }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "`true`: the worker keeps memory across runs." } } }, "resources": { "$ref": "#/components/schemas/WorkerResources" }, "triggers": { "type": "array", "description": "What starts the worker. An empty list means it only runs when Heliyos or a person calls it.", "items": { "$ref": "#/components/schemas/WorkerTrigger" } }, "schedule": { "type": "object", "description": "Legacy cron list. Schedules live on `scheduled` triggers now.", "properties": { "cron": { "type": "array", "items": { "type": "string" }, "description": "5-field cron expressions." } } }, "runtime": { "type": "string", "enum": [ "sandbox", "light" ], "description": "How Heliyos runs the worker. Set by Heliyos, read-only." }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "WorkerScheduleSync": { "type": "object", "description": "What happened to the worker's schedules after the save. The worker is saved even when a schedule fails, but a failed schedule never fires: check `failed`.", "properties": { "created": { "type": "array", "description": "Ids of the worker's schedules that are registered after this save, including ones that already existed. A one-time `at` in the past is skipped and not listed.", "items": { "type": "string" } }, "deleted": { "type": "array", "description": "Ids of schedules removed by this save because no trigger asks for them any more.", "items": { "type": "string" } }, "failed": { "type": "array", "description": "One line per schedule that could not be registered. Empty when every schedule is in place.", "items": { "type": "string" } } } }, "WorkerSaved": { "allOf": [ { "$ref": "#/components/schemas/Worker" }, { "type": "object", "properties": { "scheduleSync": { "$ref": "#/components/schemas/WorkerScheduleSync" } } } ] }, "WorkerRunOutput": { "type": "object", "additionalProperties": true, "description": "The run's final reply.", "properties": { "final_response_by": { "type": "string", "description": "Who wrote the reply, Heliyos or the worker that owned the answer." }, "response": { "type": "string", "description": "The reply text, in Markdown." } } }, "AskHeliyosResult": { "type": "object", "properties": { "runId": { "type": "string", "nullable": true, "description": "The run that handles your message. Follow it with **Get a run**. `null` only when no run could be found for the message (status `not_found`)." }, "status": { "type": "string", "description": "With `wait` 0, what happened to the message:\n- `queued`: a new run started, or the message was queued on the thread's running run.\n- `queued_until_decision`: the thread's run waits for a review; your message is read after the decision.\n- `resuming`: the thread's paused or waiting run resumed with your message.\n- `already_running`: the thread's run was already working, and your message may not have\n reached it. Follow the run, then send the message again once it settles.\n- `not_found`: the thread's run disappeared before the message reached it. Nothing ran; send again.\n\nWith `wait` above 0, the run's own status when the call returns (see **Get a run** for every\nvalue). A run that is still working returns `running` or `queued`.\n" }, "threadId": { "type": "string", "nullable": true, "description": "The conversation. Send it back as `threadId` to continue it. Heliyos makes one up when you send none." }, "output": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunOutput" } ], "description": "The run's final reply, present when the run produced one within `wait`." } } }, "WorkerRunStep": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The step's position in the run, starting at 1." }, "type": { "type": "string", "description": "What the step was: `worker` (a worker was called), `tool` (a tool call), `approval` (a review\nwas raised), `wait` and `wakeup` (the run scheduled a wait and woke up), `handoff`, `final`\n(the reply). Older or light runs can show other kinds.\n" }, "title": { "type": "string", "nullable": true, "description": "The worker, tool or step label." }, "status": { "type": "string", "nullable": true, "description": "The step's status, for example `pending`, `running`, `completed`, `failed`, `waiting`, `approved` or `rejected`." }, "startedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When the step started." }, "endedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When the step ended. `null` while it runs." }, "summary": { "type": "string", "nullable": true, "description": "The first 200 characters of the step's error, else of its result's text. `null` when the result is raw data." }, "input": { "nullable": true, "description": "`include=step_payloads` only: the step's raw input." }, "output": { "nullable": true, "description": "`include=step_payloads` only: the step's raw output." }, "error": { "nullable": true, "description": "`include=step_payloads` only: the step's raw error." } } }, "WorkerRunReview": { "type": "object", "description": "A review the run raised. Reviews are decided by a person in Heliyos, under Review.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The review's id." }, "status": { "type": "string", "nullable": true, "enum": [ "PENDING", "PROCESSING", "APPROVED", "REJECTED", null ], "description": "- `PENDING`: waiting for a person.\n- `PROCESSING`: decided, and the decision is being carried out.\n- `APPROVED`: approved. The run goes on with the action.\n- `REJECTED`: rejected. The run goes on without it.\n" }, "type": { "type": "string", "nullable": true, "description": "What is being reviewed, for example `email_draft` (an email to send), `deal_update` (a deal change), `meeting_scheduled` or `classification_label`. The set is open: an action from a connected app uses its own name. See [List reviews](/api-reference/reviews/list-reviews)." } } }, "WorkerRunUsage": { "type": "object", "additionalProperties": true, "description": "What the run used. Counters appear once there is something to count.", "properties": { "credits": { "type": "number", "description": "Credits charged to the workspace by this run (custom worker calls)." }, "requests": { "type": "integer", "description": "Model requests made." }, "inputTokens": { "type": "integer", "description": "Input tokens used." }, "outputTokens": { "type": "integer", "description": "Output tokens used." }, "totalTokens": { "type": "integer", "description": "Input plus output tokens." } } }, "WorkerRunTrigger": { "type": "object", "description": "What set the run off, without its payload.", "properties": { "type": { "type": "string", "description": "The trigger kind, for example `chat`, `event`, `mention`, `task_created` or `scheduled`." }, "objectType": { "type": "string", "description": "The kind of record the trigger named, for example `task`, `company` or `interaction`." }, "objectId": { "type": "string", "description": "The id of that record." }, "event": { "type": "string", "description": "The event name, for example `deal.updated`." } } }, "WorkerRun": { "type": "object", "properties": { "id": { "type": "string", "description": "The run id." }, "status": { "type": "string", "enum": [ "queued", "running", "awaiting_approval", "paused", "waiting", "scheduled", "completed", "failed", "skipped", "cancelled", "stopped" ], "description": "Still going:\n- `queued`: created, about to start.\n- `running`: working now.\n\nWaiting on a person or a schedule (it will not move until that happens):\n- `awaiting_approval`: paused on one or more reviews in `reviews`. It resumes when every one is decided.\n- `paused`: paused by a person. It resumes when someone resumes it or sends a message on its thread.\n- `waiting`: it set itself a wait and wakes up at the scheduled time.\n- `scheduled`: it waits for a scheduled time.\n\nFinished, never changes again:\n- `completed`: done. `output` has the reply.\n- `failed`: stopped on an error. Read `error` (with `include=detail`) and the failed step.\n- `skipped`: did not run, for example because the same event already started a run.\n- `cancelled`: cancelled before it finished.\n- `stopped`: stopped by a person.\n" }, "trigger": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunTrigger" } ], "nullable": true, "description": "What set the run off." }, "startedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When the run started." }, "endedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When it finished. `null` until it is in a finished status." }, "threadId": { "type": "string", "nullable": true, "description": "The conversation the run belongs to, for chat runs." }, "taskId": { "type": "string", "nullable": true, "description": "The task the run works on, for task runs." }, "steps": { "type": "array", "description": "Every step so far, in order.", "items": { "$ref": "#/components/schemas/WorkerRunStep" } }, "reviews": { "type": "array", "description": "The reviews the run raised, oldest first.", "items": { "$ref": "#/components/schemas/WorkerRunReview" } }, "usage": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunUsage" } ], "nullable": true, "description": "Credits and model usage so far." }, "output": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunOutput" } ], "description": "The run's final reply, once it has one." }, "title": { "type": "string", "nullable": true, "description": "`include=detail` only: the run's title." }, "agentName": { "type": "string", "nullable": true, "description": "`include=detail` only: who planned the run, Heliyos or the worker it focused on." }, "surface": { "type": "string", "nullable": true, "description": "`include=detail` only: where the run started. See `surface` on **List runs**." }, "error": { "type": "string", "nullable": true, "description": "`include=detail` only: why the run failed." }, "workers": { "type": "array", "description": "`include=detail` only: the workers that took part.", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "description": "The worker's step in the run." }, "agentId": { "type": "string", "description": "The worker's id." }, "agentName": { "type": "string", "description": "The worker's name." }, "status": { "type": "string", "description": "The worker's status in this run." }, "startedAt": { "$ref": "#/components/schemas/Timestamp" }, "endedAt": { "$ref": "#/components/schemas/Timestamp" } } } }, "toolCalls": { "type": "integer", "description": "`include=detail` only: how many tool calls the run made." }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "`include=detail` only: when the run was created." }, "graph": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`include=step_payloads` only: the run's full execution graph (`nodes`, `edges`)." } } }, "WorkerRunListItem": { "type": "object", "additionalProperties": true, "description": "A run as stored, without its step log and execution graph. Read one run with **Get a run** for its steps. Runs can carry more fields than these; treat unknown ones as internal and subject to change.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "orchestratorRunId": { "type": "string", "description": "The run id. Pass it to **Get a run**." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "status": { "type": "string", "description": "The run's status. See `status` on **Get a run** for every value." }, "title": { "type": "string", "description": "A short title for the run." }, "surface": { "type": "string", "description": "Where the run started: `chat` (Ask Heliyos), `worker_chat`, `task_chat`, `background` (an event, schedule or task) or `worker_direct`." }, "runtime": { "type": "string", "description": "`sandbox` or `light`." }, "agentName": { "type": "string", "nullable": true, "description": "The worker the run focused on, when there was one." }, "userInput": { "type": "string", "description": "The message that started a chat run, up to 4,000 characters." }, "trigger": { "type": "object", "additionalProperties": true, "description": "The trigger that started the run, with its payload." }, "triggerRef": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunTrigger" } ], "description": "The trigger kind and the record it named." }, "relationships": { "type": "array", "description": "Every record the run touched.", "items": { "type": "object", "properties": { "objectId": { "type": "string", "description": "The record's id." }, "objectType": { "type": "string", "description": "The record's kind, for example `company`, `people`, `deals`, `task` or `interaction`." } } } }, "taskId": { "type": "string", "nullable": true, "description": "The task the run works on." }, "threadId": { "type": "string", "nullable": true, "description": "The conversation, for chat runs." }, "userId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "nullable": true, "description": "The person who started the run, for chat runs." }, "workers": { "type": "array", "description": "The workers that took part (`agentId`, `agentName`, `nodeId`, `status`).", "items": { "type": "object", "additionalProperties": true } }, "toolCalls": { "type": "integer", "description": "How many tool calls the run made." }, "finalOutput": { "allOf": [ { "$ref": "#/components/schemas/WorkerRunOutput" } ], "nullable": true, "description": "The final reply, once there is one." }, "usage": { "$ref": "#/components/schemas/WorkerRunUsage" }, "error": { "type": "string", "description": "Why the run failed." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "completedAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the run finished." } } }, "WorkerIntegrationLink": { "type": "object", "description": "The connected app that delivers this trigger or performs this action. Present only when one does; Heliyos's own triggers and tools have none.", "properties": { "title": { "type": "string", "description": "The app's name, for example `Gmail`, `Outlook`, `Google Drive`, `OneDrive`, `HubSpot` or `Typeform`. Where two apps can do the job (email and calendar through Gmail or Outlook), the connected one is named; with neither connected, the first one is." }, "iconSrc": { "type": "string", "description": "The app's logo URL. Absent when Heliyos has no logo for it." }, "connected": { "type": "boolean", "description": "`true` when the workspace has this app connected and working now. While it is `false`, the trigger does not fire and the action cannot work. Connect the app in Heliyos first." } } }, "WorkerTriggerCatalogEntry": { "type": "object", "additionalProperties": true, "description": "One trigger a worker can be set to run on.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "nullable": true, "description": "`null` for the triggers every workspace has. A workspace's own entry carries its id." }, "name": { "type": "string", "description": "The trigger's name. For a `kind` `event` entry, this is the event name you put in a trigger's `events`, for example `deal.updated`." }, "kind": { "type": "string", "enum": [ "event", "mention", "schedule" ], "description": "How the entry maps to a trigger on **Create a worker** and **Update a worker**:\n- `event`: add `name` to the `events` of a trigger with `type` `event`.\n- `mention`: a trigger with `type` `mention`. Every active worker answers mentions anyway.\n- `schedule`: a trigger with `type` `scheduled` and a cron or one-time `at` in `match`.\n" }, "label": { "type": "string", "description": "A short name for the trigger, as the Heliyos app shows it." }, "description": { "type": "string", "description": "When the trigger fires, in a sentence." }, "objectType": { "type": "string", "nullable": true, "description": "What the event is about: `interaction` (an email or meeting), `task`, `company`, `people`, `deals`, `note`, `baseschema` (an object's fields), `review`, `scout` or `signal`. `null` for `mention` and `schedule`." }, "source": { "type": "string", "description": "Where the event comes from. `platform`: a change made in Heliyos, by a person, the API or a worker. `internal`: Heliyos's own background work, such as inbox sync or research. Any other value names the service that delivers the event. Informational: read `integration` to know whether a connected app is needed." }, "provider": { "type": "string", "description": "A key for the app that delivers the event. Present on entries that have `integration`." }, "providerRef": { "type": "string", "description": "The app's own name for the event, on entries that come from a connected app." }, "selectsAttributes": { "type": "boolean", "description": "`true` on `company.attribute_updated`, `people.attribute_updated` and `deal.attribute_updated`: in the Heliyos app you pick the fields to watch. The API stores only the `match` keys listed on **Create a worker**, so such a subscription created through the API runs when any field of that object changes." }, "isActive": { "type": "boolean", "description": "Absent or `true`. Inactive entries are not listed." }, "integration": { "$ref": "#/components/schemas/WorkerIntegrationLink" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "WorkerAction": { "type": "object", "additionalProperties": true, "description": "One action a worker can take. The API calls actions tools: `toolNames` and `actionIds` on a worker hold them.", "properties": { "name": { "type": "string", "description": "The action's stable snake_case name, for example `create_task` or `send_email`. For a `builtin` action, this is the value you put in a worker's `toolNames`." }, "label": { "type": "string", "description": "A short, readable name, as a run's activity shows it (for example `Created task`)." }, "display_name": { "type": "string", "nullable": true, "description": "`action` only: the action's name as the connected app's set of actions defines it, for example `Send Email`. `null` for `builtin`." }, "description": { "type": "string", "description": "What the action does, as the worker reads it when deciding whether to use it. Can be long." }, "source": { "type": "string", "enum": [ "builtin", "action" ], "description": "- `builtin`: one of Heliyos's own actions (reading and writing records, tasks and notes, web\n research, files, charts, follow-ups). Put `name` in the worker's `toolNames`.\n- `action`: an action of your workspace, performed by a connected app (email, calendar, file\n storage and so on). Put `action_id` in the worker's `actionIds`.\n" }, "is_internal": { "type": "boolean", "description": "`true` for `builtin`, `false` for `action`." }, "action_id": { "type": "string", "nullable": true, "description": "`action` only: the action's id, the value for `actionIds`. `null` for `builtin`." }, "provider": { "type": "string", "nullable": true, "description": "`action` only: a key for the app that performs it. Read `integration` for the app's name and status. `null` for `builtin`." }, "integration": { "$ref": "#/components/schemas/WorkerIntegrationLink" }, "risk": { "type": "string", "enum": [ "read", "write_crm", "write_deal", "communicate", "schedule_meeting", "external", "schedule", "plan", "confirm" ], "description": "What kind of action it is, which decides whether a call waits for a person's review:\n- `read`: reads only. Never waits.\n- `write_crm`: writes companies, people, tasks, notes, documents, email drafts and thread or\n meeting analysis. Applies directly, never waits. A saved email draft then waits for review\n before it is sent.\n- `write_deal`: creates or changes a deal. Waits unless autopilot approves deal changes.\n- `communicate`: sends email. Waits unless autopilot sends email.\n- `schedule_meeting`: books, moves or cancels a meeting. Waits unless autopilot schedules meetings.\n- `external`: changes something in a connected app. Waits unless autopilot allows external\n actions (off by default).\n- `schedule`: schedules or cancels a follow-up run. Runs unless autopilot follow-ups are turned off (on by default).\n- `plan`: submits a plan. Waits only when the workspace requires plan approval.\n- `confirm`: asks a person a question or for approval. Always waits.\n\nEven with autopilot on for a kind of action, a call waits when the worker's stated confidence\nis below the threshold set for it (80 by default) or when it states none.\n" }, "review_type": { "type": "string", "description": "The kind of review a call raises when it waits, for example `email_draft`, `deal_update` or `meeting_scheduled`. Defaults to the action's `name`." }, "common": { "type": "boolean", "description": "`true`: every worker has this action, whatever its `toolNames` say. You do not need to list it." }, "is_hidden": { "type": "boolean", "description": "`true`: Heliyos wires this action in where it is needed. It is not offered for picking in the Heliyos app; leave it out of a worker's configuration." }, "input": { "type": "object", "additionalProperties": true, "description": "The JSON Schema of the action's input, as the worker fills it in." }, "output": { "type": "object", "additionalProperties": true, "description": "The JSON Schema of the action's result." } } }, "ReviewObjectRef": { "type": "object", "description": "A record or task the review is about.", "additionalProperties": true, "properties": { "objectId": { "type": "string", "description": "Id of the record or task.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, "objectType": { "type": "string", "nullable": true, "description": "`company`, `people`, `deals`, a custom object's type, or `task`.", "example": "company" }, "name": { "type": "string", "description": "The record's display name, when the worker could resolve it.", "example": "Northwind Traders" } } }, "ReviewApproval": { "type": "object", "description": "The decision. This is the review's authoritative status.", "properties": { "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "APPROVED", "REJECTED" ], "description": "- `PENDING`: waiting for a person.\n- `PROCESSING`: a decision on a `deal_update` or `classification_label` review is being applied right now. It moves to `APPROVED` or `REJECTED` within the same request, or back to `PENDING` if applying failed.\n- `APPROVED`: approved by a person, or let through by the workspace's autopilot settings (then `by` is `autopilot`).\n- `REJECTED`: rejected by a person.\n" }, "by": { "type": "string", "nullable": true, "description": "Id of the user who decided. A decision made with an API key is recorded under the user who created the key. `autopilot` when the workspace's autopilot settings approved the action without a person. Null while pending.", "example": "66a0f1e2d3c4b5a697881111" }, "at": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When it was decided. Null while pending." }, "comment": { "type": "string", "nullable": true, "description": "The reviewer's note, kept on the review." }, "feedback": { "type": "string", "nullable": true, "description": "What the reviewer told the worker, for example why it was rejected." }, "editedArgs": { "type": "object", "additionalProperties": true, "description": "The action's arguments as the reviewer changed them on approval, when they changed any." } } }, "Review": { "type": "object", "description": "A worker action waiting for, or decided by, a person. Fields beyond the common ones depend on `type`. Reviews raised before a field existed may not carry it.", "additionalProperties": true, "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "id": { "type": "string", "description": "The review's id, the same value as `_id`.", "example": "6731f0a9b2c4d5e6f7a8b9c0" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the review belongs to." }, "type": { "type": "string", "description": "What is being reviewed. The set is open: actions in connected apps and actions your workspace defines\nuse their own name. Common values:\n- `email_draft`: an email to send.\n- `deal_update`: a deal to create (`dealAction: Create`) or change (`dealAction: Update`).\n- `meeting_scheduled`: a meeting to book or reschedule.\n- `task`: a task to create or change.\n- `document`: a file to save on a record or task.\n- `note`: a note to create.\n- `object_create`, `object_update`: a record other than a deal to create or change.\n- `schedule`: a scheduled wake-up for a worker to create or cancel.\n- `plan`: a plan the worker wants approved before it acts.\n- `decision`: a question the worker asked (`kind: question`) or an approval it asked for before going on.\n- `classification_label`: a new label to create.\n", "example": "email_draft" }, "kind": { "type": "string", "description": "- `action`: a paused action. Approving lets it run.\n- `plan`: a plan. Approving lets the worker carry it out.\n- `question`: a question for a person. Answer it in `feedback`.\n- `approval`: a saved email draft. Approving sends it.\n", "example": "action" }, "origin": { "type": "string", "description": "- `model`: the worker's run is paused on this action and resumes when it is decided.\n- `artifact`: the work is already saved (an email draft on its thread) and the decision acts on it. The run does not wait for it.\n- `autopilot`: the action ran without a person under the workspace's autopilot settings. Kept for the record, already `APPROVED`.\n", "example": "model" }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ], "description": "The decision, mirrored from `approval.status`. Read `approval.status` for the current value." }, "approval": { "$ref": "#/components/schemas/ReviewApproval" }, "agent": { "type": "string", "nullable": true, "description": "The name of the worker that raised the review.", "example": "Account researcher" }, "agentRef": { "type": "object", "description": "The worker that raised the review.", "properties": { "id": { "type": "string", "nullable": true, "description": "The worker's id. Null when Heliyos itself raised it." }, "name": { "type": "string", "description": "The worker's name." } } }, "runId": { "type": "string", "nullable": true, "description": "The run that raised the review. Read it with `GET /v1/platform/workers/runs/{id}`. A pending review a later run proposed again points at that later run.", "example": "0f1e2d3c4b5a69788766554433221100" }, "agentRunId": { "type": "string", "nullable": true, "description": "The same value as `runId`, under its older name." }, "previousRunId": { "type": "string", "description": "The run the review pointed at before a later run proposed the same change again." }, "revisions": { "type": "integer", "description": "How many times a later run replaced the proposal while the review was pending." }, "surface": { "type": "string", "description": "Where the run that raised it started, for example `chat` or `background`." }, "taskId": { "type": "string", "nullable": true, "description": "The task the run worked on, when it worked on one." }, "threadId": { "type": "string", "nullable": true, "description": "The chat conversation the run belongs to, when it started in chat." }, "tool": { "type": "object", "description": "The action the worker wants to take.", "properties": { "name": { "type": "string", "description": "The action's name, for example `send_email` or `schedule_meeting`." }, "callId": { "type": "string", "description": "Identifies this one call within the run." } } }, "proposal": { "type": "object", "description": "What the worker proposes.", "properties": { "title": { "type": "string", "description": "A one-line title, for example `Send email: Renewal terms`." }, "summary": { "type": "string", "nullable": true, "description": "The proposal in a sentence or two." }, "args": { "type": "object", "additionalProperties": true, "description": "The action's arguments as the worker proposed them. Send changed values in `args` when you approve." } } }, "proposedOutput": { "type": "object", "additionalProperties": true, "description": "The same arguments as `proposal.args`." }, "confidence": { "type": "number", "nullable": true, "description": "How sure the worker said it was, from 0 to 100. Null when it did not say.", "example": 72 }, "reasoning": { "type": "string", "description": "Why the worker proposes the action, in its own words. Empty when it gave no reason." }, "approvalReason": { "type": "string", "nullable": true, "description": "Why the action waits for a person, for example because approval is required for this kind of action or the stated confidence is below the workspace's threshold." }, "objectRef": { "allOf": [ { "$ref": "#/components/schemas/ReviewObjectRef" } ], "description": "The first of `objectRefs`." }, "objectRefs": { "type": "array", "description": "The records and tasks the review is about.", "items": { "$ref": "#/components/schemas/ReviewObjectRef" } }, "dealAction": { "type": "string", "enum": [ "Create", "Update" ], "description": "`deal_update`: whether the deal is new or an existing one changes. `meeting_scheduled`: `Create` for a new meeting, `Update` for a reschedule." }, "previousVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`deal_update` with `Update`: the deal as it is now (`_id`, `data`, `relationships`). Null for a new deal." }, "newVersion": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`deal_update`: the deal as it would be if approved (`data`, `relationships`, and for a new deal the `schemaId` of its pipeline). After an approval with edited fields, the fields as approved." }, "draftEmail": { "type": "object", "additionalProperties": true, "description": "`email_draft`: the email (`subject`, `body`, `from`, `to`, `cc`, `bcc`, `attachments`, and `interactionThreadId`, the email thread it belongs to). Recipients are email addresses or `{ email, name }` objects." }, "draft": { "type": "object", "additionalProperties": true, "description": "`email_draft` with `origin: artifact`: where the saved draft lives (`interactionId` of the email thread, `messageId`)." }, "meetingDetails": { "type": "object", "additionalProperties": true, "description": "`meeting_scheduled`: the proposed event (`title`, `startTime`, `endTime`, `timezone`, `participants`, `description`, `location`, `conferencing` and the rest of the event's fields)." }, "taskMeta": { "type": "object", "additionalProperties": true, "description": "`task`: the task (`title`, `objectId` of an existing task, `status`, `dueDate`, `description`)." }, "documentMeta": { "type": "object", "additionalProperties": true, "description": "`document`: the file (`fileName`, `description`, and when it can be opened, `url`, `mimeType`, `size`, `objectAttachmentId`)." }, "noteMeta": { "type": "object", "additionalProperties": true, "description": "`note`: the note (`title`, `content`)." }, "categoryName": { "type": "string", "description": "`classification_label`: the name of the label to create." }, "categoryDescription": { "type": "string", "description": "`classification_label`: the label's description." }, "outcome": { "type": "object", "nullable": true, "additionalProperties": true, "description": "What happened after the decision. `ok` (whether it worked), `at`, and `error` when it failed. For an action a run carried out, `result` with what the action returned. For a deal or label Heliyos applied on approval, `appliedBy: platform` with `action`, `dealId` or `labelId`. Absent until something happened." }, "metadata": { "type": "object", "description": "When the review was raised and last changed.", "properties": { "created": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" } } }, "updated": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" } } } } } } }, "ReviewDetail": { "description": "A review, with the records and work it refers to resolved.", "allOf": [ { "$ref": "#/components/schemas/Review" }, { "type": "object", "properties": { "relatedObjects": { "type": "array", "description": "The company, people and deal records the review is about: those in `objectRefs` and those linked to the email thread or meeting it sits on. Full records, at most 50.", "items": { "type": "object", "additionalProperties": true } }, "interactionData": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The email thread or meeting `objectRef` points at, when it points at one." }, "taskData": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The task `taskMeta.objectId` (or `objectRef`) points at, when it points at one." }, "previousVersionRelatedObjects": { "type": "array", "description": "`deal_update`: the records linked to the deal as it is now.", "items": { "type": "object", "additionalProperties": true } }, "newVersionRelatedObjects": { "type": "array", "description": "`deal_update`: the records linked to the deal as proposed.", "items": { "type": "object", "additionalProperties": true } } } } ] }, "ReviewDecisionResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "APPROVED", "REJECTED" ], "description": "The decision recorded." }, "review": { "allOf": [ { "$ref": "#/components/schemas/ReviewDetail" } ], "description": "The review after the decision." }, "applied": { "type": "object", "additionalProperties": true, "description": "Approved `deal_update` and `classification_label` reviews only: what Heliyos changed before answering. For a deal, `action` (`Create` or `Update`), `dealId`, `schemaId` and `object` (the deal as saved). For a label, `action` (`Create`, or `Exists` when a label with that name was already there), `labelId` and `name`." }, "orchestrator": { "type": "object", "nullable": true, "additionalProperties": true, "description": "What the worker run did with the decision:\n- `runId` and `resuming: true`: this was the last pending review of the run, which now resumes and carries out (or drops) the action.\n- `runId` and `pending`: the run still waits on this many other reviews. Nothing runs until they are decided.\n- `runId` alone: the run is no longer waiting, so nothing resumes.\n- `sent`: for a saved email draft, whether it was sent.\n- `error`: for a saved email draft, why sending or discarding failed. The decision is still recorded.\n" }, "orchestratorError": { "type": "string", "description": "Present when a deal or label change was applied and recorded but the worker run could not be told yet. The run picks the decision up later on its own." } } }, "ScoutAuditMetadata": { "type": "object", "description": "When the Scout was created and last changed. `by` is a service label such as `system`, not a user id.", "properties": { "created": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Who created it, for example `system`." } } }, "updated": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Who last changed it, for example `system`." } } } } }, "ScoutOutputSchema": { "type": "object", "additionalProperties": true, "description": "The structured output a custom Scout asks for on each run, as `{ \"type\": \"json\", \"json_schema\": { ... } }`\nwhere `json_schema` is a JSON Schema object. The default asks for a `signals` array (each item with\n`company_name`, `website`, `summary` and `sources`), plus `total_count` and `query_summary`.\nBuilt-in Scouts carry their own fixed schema.\n", "example": { "type": "json", "json_schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": "string" }, "website": { "type": "string" }, "summary": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary" ] } }, "total_count": { "type": "number" }, "query_summary": { "type": "string" } }, "required": [ "signals" ] } } }, "GlobalScout": { "type": "object", "description": "A workspace Scout: what to look for, how often, and on which companies.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the Scout belongs to." }, "name": { "type": "string", "description": "The Scout's name, 1 to 200 characters." }, "type": { "type": "string", "enum": [ "default", "custom" ], "description": "- `default`: a built-in Scout every workspace gets. Six exist: company announcements and press\n releases, product launches or updates, funding, M&A or financial news, executive changes or\n quotes, industry analysis mentioning the company, and controversies or negative coverage.\n They always apply to the watchlist, run daily, and can only be paused or resumed.\n- `custom`: a Scout you created. Every field except the scope can be changed, and it can be deleted.\n" }, "applyTo": { "type": "string", "enum": [ "watchlist", "selected_watchlist", "entire_web" ], "description": "The scope, fixed at creation.\n- `watchlist`: runs on every watched company, including companies watched later.\n- `selected_watchlist`: runs only on the companies in `selectedCompanyIds`.\n- `entire_web`: runs once across the web, not tied to a company.\n" }, "selectedCompanyIds": { "type": "array", "description": "The watched companies a `selected_watchlist` Scout runs on. Empty for other scopes.", "items": { "$ref": "#/components/schemas/ObjectId" } }, "category": { "type": "string", "description": "A short label that groups Scouts, for example `Hiring` or `Growth & Expansion`. Signals inherit it." }, "queryTemplate": { "type": "string", "description": "What the Scout looks for, in plain language, up to 5,000 characters. For the `watchlist` and\n`selected_watchlist` scopes, the placeholders `{{company_name}}` and `{{company_website}}` are\nreplaced with \"the company\" and \"the company website\", and each company's own name and website\nare added to the query when it runs.\n" }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "How often it runs. Built-in Scouts run `daily`; custom Scouts default to `weekly`." }, "effort": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Search depth for custom Scouts, `medium` by default. Each run of a custom Scout on one company\n(or on the web) costs credits by effort: `low` 2.5, `medium` 7.5, `high` 10. May be absent on built-in Scouts.\n" }, "outputSchema": { "$ref": "#/components/schemas/ScoutOutputSchema" }, "isActive": { "type": "boolean", "description": "Whether the Scout is running. A new custom Scout is `false` until you confirm its preview.\nChange it with Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`).\n" }, "previewStatus": { "type": "string", "nullable": true, "enum": [ "pending", "running", "completed", "failed", null ], "description": "The preview run of a custom Scout. `pending` when created, `running` once the preview started,\n`completed` when its results are in `previewData`, `failed` if it could not start or finish.\nNull on built-in Scouts.\n" }, "previewRunId": { "type": "string", "nullable": true, "description": "The id of the preview run. Null until a preview started." }, "previewData": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The preview's findings, in the shape of `outputSchema` (by default `signals`, `total_count` and `query_summary`). Null until the preview completed." }, "metadata": { "$ref": "#/components/schemas/ScoutAuditMetadata" } } }, "GlobalScoutSummary": { "description": "A workspace Scout with its signal totals across every company it runs on.", "allOf": [ { "$ref": "#/components/schemas/GlobalScout" }, { "type": "object", "properties": { "signal_counts": { "type": "object", "description": "Signals found by this Scout's company Scouts.", "properties": { "total": { "type": "integer", "description": "Every signal found." }, "new": { "type": "integer", "description": "Signals not read yet (status `new`)." } } }, "latest_signal": { "nullable": true, "description": "The most recently detected signal, with `companyName` added. Null when there is none.", "allOf": [ { "$ref": "#/components/schemas/Signal" } ] }, "active_company_count": { "type": "integer", "description": "Companies this Scout is actively running on (active company Scouts tied to a company)." } } } ] }, "CompanyScout": { "type": "object", "description": "A workspace Scout running on one company (or, for an `entire_web` Scout, on the web). It copies its\nworkspace Scout's fields; change them on the workspace Scout.\n", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "baseSchemaObjectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The company record it runs on. Absent for an `entire_web` Scout." }, "defaultScoutId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace Scout it is a copy of." }, "scoutType": { "type": "string", "enum": [ "default", "custom" ], "description": "The workspace Scout's type." }, "executionMode": { "type": "string", "enum": [ "monitor", "task" ], "description": "`monitor` for built-in Scouts (continuous monitoring), `task` for custom Scouts (one run per cadence period, charged in credits)." }, "effort": { "type": "string", "nullable": true, "enum": [ "low", "medium", "high", null ], "description": "Search depth of a custom Scout. Null on built-in Scouts." }, "name": { "type": "string", "description": "The workspace Scout's name." }, "category": { "type": "string", "description": "The workspace Scout's category." }, "query": { "type": "string", "description": "The query as it runs, with the company's name and website added." }, "queryTemplate": { "type": "string", "description": "The workspace Scout's query." }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "How often it runs." }, "scope": { "type": "string", "enum": [ "watchlist", "entire_web" ], "description": "`entire_web` for a web-wide Scout, `watchlist` otherwise." }, "status": { "type": "string", "enum": [ "active", "paused", "failed" ], "description": "`active` while running, `paused` while its workspace Scout is paused, `failed` when it could not run." }, "lastRunDate": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When it last ran. Null before its first run." }, "lastRunId": { "type": "string", "nullable": true, "description": "The id of its last run." }, "outputSchema": { "$ref": "#/components/schemas/ScoutOutputSchema" }, "metadata": { "$ref": "#/components/schemas/ScoutAuditMetadata" } }, "additionalProperties": true }, "GlobalScoutStateChange": { "type": "object", "title": "active or paused", "description": "The result of `active` or `paused`.", "properties": { "success": { "type": "boolean", "description": "Always `true`." }, "scout": { "$ref": "#/components/schemas/GlobalScout" }, "activated_count": { "type": "integer", "description": "`active` only: company Scouts switched from paused (or failed) to active." }, "deactivated_count": { "type": "integer", "description": "`paused` only: company Scouts of this Scout, all now paused." }, "monitors_deleted": { "type": "integer", "description": "`paused` only: running monitors stopped." } } }, "Signal": { "type": "object", "description": "One finding of a Scout.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "scoutSchemaId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The company Scout that found it (see `CompanyScout`). Its `defaultScoutId` is the workspace Scout." }, "baseSchemaObjectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The company record the signal is about. Absent for signals of `entire_web` Scouts." }, "category": { "type": "string", "description": "The Scout's category when the signal was found, for example `Growth & Expansion`." }, "scout_name": { "type": "string", "description": "The Scout's name when the signal was found." }, "scope": { "type": "string", "enum": [ "watchlist", "entire_web" ], "description": "`entire_web` for signals of web-wide Scouts, `watchlist` otherwise." }, "company_name": { "type": "string", "description": "The company name the Scout reported. May be absent; for watched companies use `baseSchemaObjectId`." }, "website": { "type": "string", "description": "The company's website the Scout reported, normalized to the site address. May be absent." }, "summary": { "type": "string", "description": "What happened, in a sentence or two." }, "citations": { "type": "array", "description": "Source URLs that support the signal.", "items": { "type": "string", "format": "uri" } }, "relevance_score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How relevant the Scout judged the signal, 0 to 100. 0 when the Scout gave no score." }, "confidence_score": { "type": "number", "description": "The raw score the Scout reported, either 0 to 1 or 0 to 100. Prefer `relevance_score`." }, "source": { "type": "string", "enum": [ "scouts", "leadsets", "linkedin" ], "description": "What produced the signal. Scouts write `scouts`." }, "detected_date": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the event was detected. For custom Scouts, the time of the run that found it. Lists sort on it." }, "status": { "type": "string", "enum": [ "new", "read", "archived" ], "description": "`new` (unread), `read`, or `archived`. This API sets `read`; it does not archive." }, "raw_output": { "type": "object", "additionalProperties": true, "description": "The Scout's structured output for this signal, in the shape of its output schema." }, "eventId": { "type": "string", "description": "The id of the detection event. Internal; unique per run." }, "parallelMonitorId": { "type": "string", "description": "The id of the monitor or run that produced the signal. Internal." }, "taskRunId": { "type": "string", "description": "The id of the custom Scout run that produced the signal. Internal; absent for built-in Scouts." }, "webhook_timestamp": { "type": "string", "description": "When the result was delivered. Internal." }, "metadata": { "$ref": "#/components/schemas/ScoutAuditMetadata" } } }, "SignalWithCompany": { "description": "A signal with the name of the company it is about.", "allOf": [ { "$ref": "#/components/schemas/Signal" }, { "type": "object", "properties": { "companyName": { "type": "string", "description": "The company record's `company_name` (or `name`, or `Unknown`) for watched companies, otherwise the name the Scout reported. Absent when neither is known." } } } ] }, "WatchlistStatistics": { "type": "object", "description": "Activity across every watched company.", "properties": { "tasks": { "type": "object", "description": "Tasks linked to a watched company.", "properties": { "total": { "type": "integer", "description": "Every linked task." }, "completed": { "type": "integer", "description": "Linked tasks with status `completed`." } } }, "totalActions": { "type": "integer", "description": "Completed background worker runs (Autonomous Updates) linked to a watched company." }, "totalMeetings": { "type": "integer", "description": "Meetings linked to a watched company." }, "totalDeals": { "type": "integer", "description": "Deal records linked to a watched company, across every deal object in the workspace." }, "accountStatus": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Watched companies per value of their `account_status` field, keyed by the stored option value. Companies without a value count under `unknown`. Empty when nothing is watched." }, "engagementStatus": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Watched companies per value of their `engagement_status` field, keyed by the stored option value. Companies without a value count under `unknown`. Empty when nothing is watched." } } }, "WatchedCompanyRecord": { "type": "object", "additionalProperties": true, "description": "The company record after the change.", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "baseSchemaId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The record's object (base schema), your companies object." }, "objectType": { "type": "string", "description": "Always `company`." }, "data": { "type": "object", "additionalProperties": true, "description": "The record's field values, keyed by field name (for example `company_name`, `website`, `account_status`, `engagement_status`)." }, "isAgentAssigned": { "type": "boolean", "description": "Whether the company is watched. `true` after watching, `false` after unwatching." }, "agentAssignmentStatus": { "type": "string", "nullable": true, "enum": [ "STARTED", "FINISHED", "FAILED", null ], "description": "How taking the account on is going: `STARTED` when watched, `FINISHED` once the workers have enriched it and pulled in its history, `FAILED` if that did not complete. Null after unwatching." }, "enrichmentStatus": { "type": "string", "description": "`NOT_ENRICHED`, `STARTED`, `FINISHED` or `FAILED`. May be absent." }, "enrichmentDate": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "nullable": true, "description": "When enrichment last started." }, "relationships": { "type": "array", "description": "The records linked to the company.", "items": { "type": "object", "additionalProperties": true, "properties": { "objectId": { "$ref": "#/components/schemas/ObjectId" }, "schemaId": { "$ref": "#/components/schemas/ObjectId" }, "objectType": { "type": "string", "description": "`people`, `deals` or a custom object type." } } } }, "metadata": { "type": "object", "description": "Who created and last changed the record, and when.", "properties": { "created": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Id of the user who created it." } } }, "updated": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "type": "string", "description": "Id of the user who last changed it." } } } } } } }, "KnowledgeEntry": { "type": "object", "description": "A custom knowledge entry, for facts the fixed texts do not cover, such as pricing or competitors.", "properties": { "label": { "type": "string", "description": "The entry's title, for example `Pricing`.", "example": "Pricing" }, "content": { "type": "string", "description": "The entry's content, as plain text or HTML. The Heliyos app edits it as rich text.", "example": "Growth is $49 per seat per month, billed yearly. Annual contracts above 50 seats get 15% off." } } }, "KnowledgeBase": { "type": "object", "description": "The knowledge base. Every text is plain text, Markdown or HTML and can be an empty string. Keys you stored that are not listed here are kept and returned as they are.", "properties": { "productsInformation": { "type": "string", "description": "The products and services you sell." }, "painPoints": { "type": "string", "description": "The customer problems your products solve." }, "valueProposition": { "type": "string", "description": "Why customers choose your products." }, "qualificationCriteria": { "type": "string", "description": "What makes a lead worth pursuing." }, "entries": { "type": "array", "description": "Your team's custom entries, in display order. Can be absent when the workspace has never saved one.", "items": { "$ref": "#/components/schemas/KnowledgeEntry" } } } }, "WorkspaceProfile": { "type": "object", "description": "The workspace's profile and knowledge base. The response also carries other workspace settings that this page does not document. Rely only on the fields listed here.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace's id." }, "_id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The same value as `id`." }, "name": { "type": "string", "description": "The workspace's name." }, "businessContext": { "type": "string", "description": "What the business does, in your team's words. Empty string when not set." }, "knowledgeBase": { "$ref": "#/components/schemas/KnowledgeBase" }, "website": { "type": "string", "description": "The company website. Absent when not set." }, "industry": { "type": "string", "description": "The industry. Absent when not set." }, "timezone": { "type": "string", "description": "The workspace's time zone. Absent when not set." }, "address": { "type": "string", "description": "Street address. Absent when not set." }, "city": { "type": "string", "description": "City. Absent when not set." }, "state": { "type": "string", "description": "State or region. Absent when not set." }, "zipcode": { "type": "string", "description": "Postal code. Absent when not set." }, "country": { "type": "string", "description": "Country. Absent when not set." }, "logo": { "type": "string", "description": "The logo, as a file id or the https URL of a file stored in Heliyos. Absent when not set." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "FileLink": { "type": "object", "description": "A resource the file is attached to.", "properties": { "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the linked record, task, interaction, or of the workspace itself for a knowledge base file." }, "schemaId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The linked record's object (base schema). Absent for links that are not records." }, "objectType": { "type": "string", "description": "What the link points at: `company`, `people`, `deal` or a custom object's type for a record, `task`, `note`, `comment`, `interaction`, or `organization` for a knowledge base file.", "example": "company" } } }, "File": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The same value as `_id`. Present in list results only." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the file belongs to." }, "fileName": { "type": "string", "description": "The file's display name, as sent when the file was created." }, "fileSize": { "type": "integer", "description": "Size in bytes, as sent when the file was created." }, "mimeType": { "type": "string", "description": "The content type, for example `application/pdf`." }, "url": { "type": "string", "description": "Where the file is stored. To download the file, use Get a file download link." }, "storageProvider": { "type": "string", "description": "The storage provider recorded when the file was created." }, "storageKey": { "type": "string", "description": "The file's storage key, inside your workspace's folder." }, "description": { "type": "string", "description": "An optional description. Absent when none was sent." }, "isKbFile": { "type": "boolean", "description": "`true` for a knowledge base file (workers read it), `false` for a file attached to a resource." }, "relationships": { "type": "array", "description": "The resources the file is attached to. Not hydrated.", "items": { "$ref": "#/components/schemas/FileLink" } }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "FileUploadUrl": { "type": "object", "properties": { "presignedUrl": { "type": "string", "description": "The signed upload URL. Send the file's bytes to it with `PUT`, within one hour. Do not send your API key to it." }, "fileKey": { "type": "string", "description": "The storage key the file will be stored under. Send it back as `storageKey` when you create the file. Its extension comes from `mimeType`, not from `fileName`." }, "bucketName": { "type": "string", "description": "The storage bucket the URL uploads to. You need it to build `url` when you create the file." } } }, "FileDownloadUrl": { "type": "object", "properties": { "url": { "type": "string", "description": "The link. When `forced` is `true` it is a signed link that downloads the file under its `fileName` and expires 60 seconds after the call." }, "forced": { "type": "boolean", "description": "`true` for a short-lived signed download link. `false` for an older file stored outside Heliyos's upload storage: `url` is then the file's stored URL, returned as is." } } }, "LabelValue": { "type": "object", "description": "One label inside a group.", "properties": { "_id": { "type": "string", "description": "The label's id: a 24-character hexadecimal id, or `temp_` followed by digits on labels made by older versions of Heliyos.", "example": "6729d1e2f3a4b5c6d7e8f901" }, "name": { "type": "string", "description": "The label's name, 1 to 100 characters, unique within its group (case-insensitive).", "example": "Discount request" } } }, "LabelGroup": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ObjectId" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the group belongs to." }, "name": { "type": "string", "description": "The group's name, unique in the workspace." }, "description": { "type": "string", "description": "What the group covers. Heliyos reads it when it classifies email threads." }, "isActive": { "type": "boolean", "description": "`true` for an active group, `false` for a paused one." }, "color": { "type": "string", "description": "The colour family the group's chip renders in, chosen by Heliyos: one of `red`, `orange`, `amber`, `olive`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Groups created before these families existed can hold an older colour name. Absent on some older groups.", "example": "teal" }, "labels": { "type": "array", "description": "The labels in the group.", "items": { "$ref": "#/components/schemas/LabelValue" } }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the user (or the API key's owner) who created the group." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "TeamMembership": { "type": "object", "description": "A person's membership of the workspace, or a pending invitation.", "properties": { "_id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The membership id. Present in list results." }, "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The membership id, the same value as `_id`. Use it to remove the member or change their role." }, "email": { "type": "string", "format": "email", "description": "The address the invitation was sent to, in lower case." }, "roleId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The role's id. See **List roles**." }, "roleName": { "type": "string", "description": "The role's name: `OWNER`, `ADMIN`, `MEMBER`, or `AGENCY` in an agency workspace. List results only.", "example": "MEMBER" }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace." }, "userId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The person's user id. Absent while an invited person has no Heliyos account." }, "firstName": { "type": "string", "description": "The person's first name, once they have an account. List results only." }, "lastName": { "type": "string", "description": "The person's last name, once they have an account. List results only." }, "pictureUrl": { "type": "string", "description": "The person's profile picture, when they set one. List results only." }, "status": { "type": "string", "enum": [ "SENT", "ACCEPTED", "REGISTERED", "REJECTED", "REVOKED" ], "description": "- `SENT`: invited, not joined yet. The invitation link expires 7 days after it was sent.\n- `ACCEPTED`: joined by accepting an invitation.\n- `REGISTERED`: joined by creating the workspace.\n- `REJECTED`, `REVOKED`: found on older invitations only.\n", "example": "ACCEPTED" }, "expiresOn": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the invitation link expires. Returned by **Invite a team member** only." }, "onboardingSteps": { "type": "array", "description": "The person's onboarding progress in Heliyos. Empty for a new invitation. Returned by **Invite a team member** only.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The step's name." }, "isCompleted": { "type": "boolean", "description": "Whether the step is done." }, "isSkipped": { "type": "boolean", "description": "Whether the step was skipped." } } } }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When the invitation was sent or the membership was created." }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "Role": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ObjectId" }, "name": { "type": "string", "description": "- `OWNER`: full control, including granting and taking away the owner role.\n- `ADMIN`: manages members and roles, except owners and the owner role.\n- `MEMBER`: works in the workspace; cannot manage members, roles or API keys.\n- `AGENCY`: the role for agency workspaces only.\n", "example": "MEMBER" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } } }, "NotificationEventType": { "type": "object", "required": [ "type", "frequency" ], "properties": { "type": { "type": "string", "enum": [ "task.created", "task.updated", "deal.created", "deal.updated", "deal.approval", "leadset.created", "leadset.records.available", "organization.daily_summary", "scout.signal_detected", "integration.not_synced" ], "description": "The event that notifies:\n- `task.created`: a task was created.\n- `task.updated`: a task changed.\n- `deal.created`: a deal was created.\n- `deal.updated`: a deal changed.\n- `deal.approval`: a deal change is waiting for review.\n- `leadset.created`: a lead set was created.\n- `leadset.records.available`: new records are ready in a lead set.\n- `organization.daily_summary`: the workspace's daily briefing email. Sent only when its\n frequency is `daily`.\n- `scout.signal_detected`: a Scout found a signal. Always sent at once: a `daily` frequency\n is saved as `immediate`.\n- `integration.not_synced`: a connected integration stopped syncing. Always sent, even when\n notifications are off or this event is not in the list (see `notifyEmails`).\n" }, "frequency": { "type": "string", "enum": [ "immediate", "daily" ], "description": "- `immediate`: one email per event, sent when it happens.\n- `daily`: collected and sent together in the daily digest.\n" } } }, "NotificationSettings": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The settings document's id." }, "organizationId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "The workspace the settings belong to." }, "notifyEmails": { "type": "array", "description": "Every address notification emails go to. Notifications are sent only when this list has at least one address, with one exception: an `integration.not_synced` email goes to the person whose integration failed when the list is empty.", "items": { "type": "string", "format": "email" } }, "eventTypes": { "type": "array", "description": "The events that send notifications, each with its frequency. An event not listed sends nothing.", "items": { "$ref": "#/components/schemas/NotificationEventType" } }, "isActive": { "type": "boolean", "description": "The master switch. `false` stops every notification email except `integration.not_synced`. Events already collected for the daily digest are discarded if it is `false` when the digest goes out." }, "metadata": { "$ref": "#/components/schemas/AuditMetadata" } } }, "ObjectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "A 24-character hexadecimal id.", "example": "66f1a8c3e4b0a1b2c3d4e5f6" }, "Timestamp": { "type": "string", "format": "date-time", "description": "An ISO 8601 date-time in UTC.", "example": "2026-11-04T09:30:00.000Z" }, "AuditMetadata": { "type": "object", "description": "Who created and last changed the resource, and when.", "properties": { "created": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the user (or the API key's owner) who created it." } } }, "updated": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "by": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the user who last changed it." } } } } }, "RelationshipInput": { "type": "object", "description": "A link from this resource to a record (company, person, deal or custom object) or to a task or interaction in the same workspace.", "required": [ "objectId" ], "properties": { "objectId": { "allOf": [ { "$ref": "#/components/schemas/ObjectId" } ], "description": "Id of the linked record, task or interaction." }, "schemaId": { "type": "string", "nullable": true, "description": "Id of the linked record's object (its base schema). Recommended for records, so the link renders with the right object. Omit or send null for tasks and interactions." }, "objectType": { "type": "string", "nullable": true, "description": "What the link points at: `company`, `people`, `deals` or a custom object's type for records, `task` for a task, `interaction` or `meeting` for an email thread or meeting.", "example": "company" } } }, "Relationship": { "type": "object", "description": "A linked resource, hydrated with a short summary so it can be shown without another call.", "properties": { "objectId": { "$ref": "#/components/schemas/ObjectId" }, "schemaId": { "type": "string", "nullable": true, "description": "The linked record's object id, when the link points at a record." }, "objectType": { "type": "string", "nullable": true, "description": "`company`, `people`, `deals`, a custom object type, `task`, `interaction` or `meeting`." }, "data": { "type": "object", "additionalProperties": true, "description": "A summary of the linked resource. For a record, its field values (for example `company_name` and `logo`, or `people_name`). For a task, `title` and `status`. For an interaction, `subject` and `channelType`. Empty when the target no longer exists." }, "schema": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The linked record's object (`_id`, `name`, `objectType`, `fields`). Present on single-resource reads." } } }, "ListFilters": { "type": "string", "description": "A JSON-encoded object, URL-encoded into the query string. See [Filtering and sorting](/api-reference/filtering). Keys: `search` (text), `filters` (array of `{ field, operator, value }`), `sort` (array of `{ field, direction }`), `page` and `pageSize` (page-number paging, `pageSize` at most 200)." } } } }