Quickstart

This guide takes about five minutes. You need a Heliyos workspace where you are an owner or admin.

Create an API key

In Heliyos, open Settings → API keys and click New key. Name it after where it will run, set an expiry if you want one, then click Create key and copy the key. It starts with heliyos_ and is shown once.

The New API key dialog with a name and an expiry — Settings → API keys → New key. Name it after where it will run.

Keep it in an environment variable rather than in code:

export HELIYOS_API_KEY="heliyos_..."

See Authentication for what a key can do and how to rotate it.

Check the key

Every request sends the key as a bearer token. Read your workspace:

curl https://api-prod.heliyos.ai/v1/platform/organization \
  -H "Authorization: Bearer $HELIYOS_API_KEY"

A 200 with your workspace’s name means the key works. A 401 means the key is wrong, expired or revoked.

Find the companies object

Records belong to an object (companies, people, deals or a custom object). List the objects and note the id of the one whose objectType is company:

curl https://api-prod.heliyos.ai/v1/platform/base-schemas \
  -H "Authorization: Bearer $HELIYOS_API_KEY"

Response (trimmed)

{
  "meta": {
    "message": "Schemas retrieved successfully"
  },
  "data": [
    {
      "id": "66a0f1e2d3c4b5a697880001",
      "name": "Company",
      "objectType": "company"
    },
    {
      "id": "66a0f1e2d3c4b5a697880002",
      "name": "People",
      "objectType": "people"
    },
    {
      "id": "66a0f1e2d3c4b5a697880003",
      "name": "Deals",
      "objectType": "deals"
    }
  ]
}

List companies

Use that id to list the first page of companies, newest first:

curl "https://api-prod.heliyos.ai/v1/platform/base-schemas/66a0f1e2d3c4b5a697880001/records?limit=10" \
  -H "Authorization: Bearer $HELIYOS_API_KEY"

When meta.pagination.next_cursor is present, send it back as cursor for the next page. See Pagination.

Write a note on a company

Take a company’s _id from the list and link a note to it. The note shows on the company’s timeline, and workers read it as customer memory.

curl https://api-prod.heliyos.ai/v1/platform/notes \
  -H "Authorization: Bearer $HELIYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Intro call",
    "content": "Interested in the Q1 pilot. Follow up with pricing.",
    "relationships": [
      {
        "objectId": "<company id>",
        "schemaId": "66a0f1e2d3c4b5a697880001",
        "objectType": "company"
      }
    ]
  }'

Next steps

Core concepts

How objects, records, fields, the timeline and workers fit together.

API reference

Every endpoint, parameter and response, with a playground.

Connect an AI agent

Use the same key with the Heliyos MCP server in Claude, Cursor or Codex.

Handle errors

Error codes, retries and rate limits.

Get started

Core concepts

Using the API

Recipes

Next steps

Core concepts

API reference

Connect an AI agent

Handle errors

​Next steps

Core concepts

API reference

Connect an AI agent

Handle errors

Next steps