API reference - Heliyos

Base URL

https://api-prod.heliyos.ai

Workspace data lives under /v1/platform. Team members, roles and the knowledge base live under /v1/auth. Both take the same API key.

Version

This reference documents Heliyos API v1.0.0. The major version is in every path (/v1/). New endpoints and new optional fields arrive without a new major version, and the Changelog lists each change. The MCP server @heliyos/mcp v1.0.0 calls this version.

Authentication

Send your workspace API key as a bearer token on every request. See Authentication.

-H "Authorization: Bearer $HELIYOS_API_KEY"

Requests

Bodies are JSON. Send Content-Type: application/json.
Ids are 24-character hexadecimal strings, such as 66f1a8c3e4b0a1b2c3d4e5f6.
Dates are ISO 8601 in UTC, such as 2026-11-04T09:30:00.000Z.
Unknown body and query keys are dropped before the request is handled.
PATCH changes only the fields you send. Each endpoint says when a field replaces a whole list.

Responses

Every success answers with the same envelope. data holds the resource or list. meta.message is a short human-readable summary. Lists add meta.pagination.

{
  "meta": {
    "message": "Notes fetched successfully.",
    "pagination": {
      "limit": 20,
      "next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2"
    }
  },
  "data": [
    {
      "_id": "6720b1f4c2a9e3d1f0a4b5c6",
      "title": "Pricing call follow-up"
    }
  ]
}

A few deletes answer 204 No Content with no body. Their pages say so. Errors use a separate envelope with a stable error.code. See Errors.

Paging, filtering and limits

Pagination

Cursor paging by default, page numbers when you sort or group.

Filtering and sorting

The filters JSON object most lists accept.

Rate limits

60 requests a minute per key, with headers to pace yourself.

Groups

Group	What it covers
Workspace	The workspace and its credit usage.
Schemas	Objects (companies, people, deals, custom objects) and their fields.
Records	The rows of an object: create, read, update, delete, look up, enrich.
Timeline	The AI-written timeline of a company, person or deal.
Activities	The change history of records and tasks: who changed what, and when.
Interactions	Synced email threads and meetings.
Notes	Free-text notes linked to records.
Tasks	Tasks for people and workers, and running workers on them.
Workers and runs	Workers, their triggers and actions, Ask Heliyos, and the runs they produce.
Reviews	Worker actions waiting for a person, and approving or rejecting them.
Scouts and Signals	What Scouts watch for and the signals they find.
Watchlist	Watchers on companies.
Knowledge base	The business context, fixed texts and custom entries your workers read.
Files	Knowledge base files and files attached to records.
Labels	Label groups that classify email.
Team	Members, invitations and roles.
Notification settings	Who gets workspace email notifications.

Every endpoint in this reference is also used by the Heliyos MCP server; each page names the tools that call it.

OpenAPI

The full OpenAPI 3.0 document behind this reference is at /api-reference/openapi.json. Use it to generate a client or import the API into Postman or Insomnia.

Last modified on November 5, 2026

​Base URL

​Version

​Authentication

​Requests

​Responses

​Paging, filtering and limits

Pagination

Filtering and sorting

Rate limits

​Groups

​OpenAPI

Base URL

Version

Authentication

Requests

Responses

Paging, filtering and limits

Groups

OpenAPI