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

# Records

> 6 tools: heliyos_records_list, heliyos_records_get, heliyos_records_create, heliyos_records_update, heliyos_records_delete, heliyos_records_lookup.

| Tool | What it does | Kind |
| - | - | - |
| [`heliyos_records_list`](#heliyos-records-list) | List records | Read |
| [`heliyos_records_get`](#heliyos-records-get) | Get a record | Read |
| [`heliyos_records_create`](#heliyos-records-create) | Create a record | Write |
| [`heliyos_records_update`](#heliyos-records-update) | Update a record | Write |
| [`heliyos_records_delete`](#heliyos-records-delete) | Delete records | Destructive |
| [`heliyos_records_lookup`](#heliyos-records-lookup) | Find records by name | Read |

Write and destructive tools change your workspace. Clients that support it ask before they run.

## List records

`heliyos_records_list` · **Read** · Idempotent

Lists records of one object (companies, people, deals, or a custom object) in the Heliyos workspace, newest first. Use it to browse or filter records; use heliyos\_records\_lookup to find a record by name and heliyos\_records\_get for one record. Filter with `search` (free text) and `filters` (field conditions joined by `match`); order with `sort`. Returns a table of id, name and key fields plus structuredContent \{records:\[\{id, object\_type, name, fields}], next\_cursor}. When next\_cursor is present, call again with `cursor` set to it for the next page. Record ids feed heliyos\_records\_get, \_update and \_delete.

### Inputs

**object\_type** `string` *required*

Which object: "company", "person", "deal", or "custom" (custom objects also need schema\_id). One of `company`, `person`, `deal`, `custom`.

**schema\_id** `string`

Object schema id. Required when object\_type is "custom"; the error lists the available ones. A 24-character hex id.

**search** `string`

Plain words matched across the record's text fields. Symbols such as + ( ) \[ ] \* ? can cause an error. Up to 200 characters.

**filters** `object[]`

Field conditions, for example \[\{field:"stage", operator:"equals", value:"Won"}]. Joined by `match`. Up to 20 items.

**item properties**

**field** `string` *required*

Field key, for example stage or domain. createdAt, updatedAt and isAgentAssigned also work. Up to 200 characters.

**operator** `string` *required*

How to compare: contains, notContains, startsWith, endsWith (text); equals, notEquals; empty, notEmpty (no value); greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual (numbers); after, before (dates). One of `contains`, `notContains`, `startsWith`, `endsWith`, `equals`, `notEquals`, `empty`, `notEmpty`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `after`, `before`.

**value** `string | number | boolean`

Value to compare with. Text operators (contains, notContains, startsWith, endsWith) need text; a comma in a contains value matches any of the parts. Omit for empty and notEmpty. Dates as ISO 8601.

**match** `string` (default: all)

"all" (default): a record must meet every filter condition. "any": at least one condition. One of `all`, `any`.

**sort** `object`

Sort order. Omit for newest updated first. With a sort, next\_cursor is a page cursor from this tool; pass it back unchanged.

**properties**

**field** `string` *required*

Field key to sort by (from heliyos\_objects\_get), or createdAt / updatedAt. Up to 200 characters.

**direction** `string` (default: desc)

"asc" or "desc" (default). One of `asc`, `desc`.

**limit** `integer` (default: 20)

Records per page, 1 to 100. Default 20. From 1 to 100.

**cursor** `string`

next\_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.

**response\_format** `string` (default: concise)

"concise" (default) returns the name and key fields; "detailed" returns every field and linked records. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `records`, `next_cursor`.

### API endpoints

* [List records](https://docs.heliyos.ai/api-reference/records/list-records.md) · `GET /v1/platform/base-schemas/{id}/records`

## Get a record

`heliyos_records_get` · **Read** · Idempotent

Fetches one record (a company, person, deal, or custom object row) by id. Use it after heliyos\_records\_list or heliyos\_records\_lookup gives you an id. "concise" returns the name, key fields and a count of linked records; "detailed" returns every field, the linked records (for example a person's company or a company's deals) with their ids, and created and updated times. Returns structuredContent \{record:\{id, object\_type, schema\_id, name, fields, relationships}}.

### Inputs

**record\_id** `string` *required*

record\_id: a 24-character hex id. A 24-character hex id.

**response\_format** `string` (default: concise)

"concise" (default) returns the name and key fields; "detailed" returns every field and linked records. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `record`.

### API endpoints

* [Get a record](https://docs.heliyos.ai/api-reference/records/get-a-record.md) · `GET /v1/platform/records/{id}`

## Create a record

`heliyos_records_create` · **Write**

Creates one record (a company, person, deal, or custom object row) with the given field values. Check first with heliyos\_records\_lookup that the record does not already exist; calling this twice creates two records. Creating a company can start automatic enrichment, which uses credits when automatic enrichment is on (Settings, Autopilot). Returns the new record's id and key fields as structuredContent \{record}.

### Inputs

**object\_type** `string` *required*

Which object: "company", "person", "deal", or "custom" (custom objects also need schema\_id). One of `company`, `person`, `deal`, `custom`.

**schema\_id** `string`

Object schema id. Required when object\_type is "custom"; the error lists the available ones. A 24-character hex id.

**fields** `object` *required*

Field values keyed by the object's field keys (for example company\_name, domain, people\_name, email, deal\_name, stage). Unknown keys are rejected with the list of valid keys. `relationships` takes an array of record ids to link to this record (for example a person's company); linking adds to the existing links, and updates never remove links.

### Returns

A readable text summary, plus `structuredContent` with `record`.

### API endpoints

* [Create a record](https://docs.heliyos.ai/api-reference/records/create-a-record.md) · `POST /v1/platform/base-schemas/{id}/records`

## Update a record

`heliyos_records_update` · **Write** · Idempotent

Updates some fields of one record by id; fields you leave out keep their values. Set a field to null to clear it. Field keys are checked against the record's object first, and unknown keys are rejected with the valid ones. `relationships` adds links and never removes existing ones. Get the id from heliyos\_records\_list or heliyos\_records\_lookup. Returns the changed fields and the record's key fields as structuredContent \{record}.

### Inputs

**record\_id** `string` *required*

record\_id: a 24-character hex id. A 24-character hex id.

**fields** `object` *required*

Field values keyed by the object's field keys (for example company\_name, domain, people\_name, email, deal\_name, stage). Unknown keys are rejected with the list of valid keys. `relationships` takes an array of record ids to link to this record (for example a person's company); linking adds to the existing links, and updates never remove links.

### Returns

A readable text summary, plus `structuredContent` with `record`.

### API endpoints

* [Get a record](https://docs.heliyos.ai/api-reference/records/get-a-record.md) · `GET /v1/platform/records/{id}`
* [Update a record](https://docs.heliyos.ai/api-reference/records/update-a-record.md) · `PATCH /v1/platform/records/{id}`

## Delete records

`heliyos_records_delete` · **Destructive** · Idempotent

Permanently deletes up to 100 records of one object by id. This cannot be undone: confirm with the user first. All ids must belong to the given object\_type; the API ignores ids from other objects and does not confirm a count. Returns structuredContent \{deleted\_count (ids sent), record\_ids}.

### Inputs

**object\_type** `string` *required*

Which object: "company", "person", "deal", or "custom" (custom objects also need schema\_id). One of `company`, `person`, `deal`, `custom`.

**schema\_id** `string`

Object schema id. Required when object\_type is "custom"; the error lists the available ones. A 24-character hex id.

**record\_ids** `string[]` *required*

Ids of the records to delete, 1 to 100. Up to 100 items.

### Returns

A readable text summary, plus `structuredContent` with `deleted_count`, `record_ids`.

### API endpoints

* [Delete records](https://docs.heliyos.ai/api-reference/records/delete-records.md) · `POST /v1/platform/base-schemas/{id}/records/bulk-delete`

## Find records by name

`heliyos_records_lookup` · **Read** · Idempotent

Finds records of one object whose name contains `query` (case-insensitive; exact and prefix matches rank first), or whose secondary value does (the first of domain, email, job title or stage that the object has). Use it to turn a name the user mentions into a record id. It searches the 2000 most recently updated records; for older ones use heliyos\_records\_list with search. Returns structuredContent \{matches:\[\{id, name, secondary}], total\_matches}.

### Inputs

**object\_type** `string` *required*

Which object: "company", "person", "deal", or "custom" (custom objects also need schema\_id). One of `company`, `person`, `deal`, `custom`.

**schema\_id** `string`

Object schema id. Required when object\_type is "custom"; the error lists the available ones. A 24-character hex id.

**query** `string` *required*

Name or part of a name, for example "acme". Up to 200 characters.

**limit** `integer` (default: 20)

Maximum matches to return, 1 to 100. Default 20. From 1 to 100.

**response\_format** `string` (default: concise)

"concise" (default) returns the name and key fields; "detailed" returns every field and linked records. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `matches`, `total_matches`, `index_truncated`.

### API endpoints

* [Get a record](https://docs.heliyos.ai/api-reference/records/get-a-record.md) · `GET /v1/platform/records/{id}`
* [List record names](https://docs.heliyos.ai/api-reference/records/list-record-names.md) · `GET /v1/platform/base-schemas/{id}/records/lookup`


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