> ## 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.

# Quickstart

> Create an API key, find your companies object and make your first three calls.

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

**1. 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](https://mintcdn.com/heliyos/j131RqihzUCqTT55/images/screenshots/api-keys-new.png?fit=max\&auto=format\&n=j131RqihzUCqTT55\&q=85\&s=8f4bc6bf5480241c850048e5cff5d783)

Settings → API keys → New key. Name it after where it will run.

Keep it in an environment variable rather than in code:

```bash theme={"dark"}
export HELIYOS_API_KEY="heliyos_..."
```

See [Authentication](https://docs.heliyos.ai/authentication.md) for what a key can do and how to rotate it.

**2. Check the key**

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

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

**3. 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`:

```bash theme={"dark"}
curl https://api-prod.heliyos.ai/v1/platform/base-schemas \
  -H "Authorization: Bearer $HELIYOS_API_KEY"
```

```json Response (trimmed) theme={"dark"}
{
  "meta": {
    "message": "Schemas retrieved successfully"
  },
  "data": [
    {
      "id": "66a0f1e2d3c4b5a697880001",
      "name": "Company",
      "objectType": "company"
    },
    {
      "id": "66a0f1e2d3c4b5a697880002",
      "name": "People",
      "objectType": "people"
    },
    {
      "id": "66a0f1e2d3c4b5a697880003",
      "name": "Deals",
      "objectType": "deals"
    }
  ]
}
```

**4. List companies**

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

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

**5. 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.

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

> [card] [Core concepts](https://docs.heliyos.ai/concepts/workspace-and-objects.md)
>
> How objects, records, fields, the timeline and workers fit together.

> [card] [API reference](https://docs.heliyos.ai/api-reference/introduction.md)
>
> Every endpoint, parameter and response, with a playground.

> [card] [Connect an AI agent](https://docs.heliyos.ai/mcp/install.md)
>
> Use the same key with the Heliyos MCP server in Claude, Cursor or Codex.

> [card] [Handle errors](https://docs.heliyos.ai/api-reference/errors.md)
>
> Error codes, retries and rate limits.


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