> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Conventions shared by every endpoint: base URL, authentication, the response envelope, ids, paging and errors.

## Base URL

```text theme={"dark"}
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](https://docs.heliyos.ai/changelog.md) 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](https://docs.heliyos.ai/authentication.md).

```bash theme={"dark"}
-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`.

```json theme={"dark"}
{
  "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](https://docs.heliyos.ai/api-reference/errors.md).

## Paging, filtering and limits

> [card] [Pagination](https://docs.heliyos.ai/api-reference/pagination.md)
>
> Cursor paging by default, page numbers when you sort or group.

> [card] [Filtering and sorting](https://docs.heliyos.ai/api-reference/filtering.md)
>
> The `filters` JSON object most lists accept.

> [card] [Rate limits](https://docs.heliyos.ai/api-reference/rate-limits.md)
>
> 60 requests a minute per key, with headers to pace yourself.

## Groups

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

> [!NOTE]
>
> Every endpoint in this reference is also used by the [Heliyos MCP server](https://docs.heliyos.ai/mcp/overview.md); each page names the tools that call it.

## OpenAPI

The full OpenAPI 3.0 document behind this reference is at [`/api-reference/openapi.json`](https://docs.heliyos.ai/api-reference/openapi.json). Use it to generate a client or import the API into Postman or Insomnia.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.