Guides
API reference
MCP server
Changelog
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
string
required
Which object: “company”, “person”, “deal”, or “custom” (custom objects also need schema_id). One of
company, person, deal, custom.string
Object schema id. Required when object_type is “custom”; the error lists the available ones. A 24-character hex id.
string
Plain words matched across the record’s text fields. Symbols such as + ( ) [ ] * ? can cause an error. Up to 200 characters.
object[]
Field conditions, for example [{field:“stage”, operator:“equals”, value:“Won”}]. Joined by
match. Up to 20 items.string
default:"all"
“all” (default): a record must meet every filter condition. “any”: at least one condition. One of
all, any.object
Sort order. Omit for newest updated first. With a sort, next_cursor is a page cursor from this tool; pass it back unchanged.
integer
default:"20"
Records per page, 1 to 100. Default 20. From 1 to 100.
string
next_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.
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, plusstructuredContent with records, next_cursor.
API endpoints
- List records ·
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
string
required
record_id: a 24-character hex id. A 24-character hex id.
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, plusstructuredContent with record.
API endpoints
- Get a record ·
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
string
required
Which object: “company”, “person”, “deal”, or “custom” (custom objects also need schema_id). One of
company, person, deal, custom.string
Object schema id. Required when object_type is “custom”; the error lists the available ones. A 24-character hex id.
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, plusstructuredContent with record.
API endpoints
- Create a record ·
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
string
required
record_id: a 24-character hex id. A 24-character hex id.
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, plusstructuredContent with record.
API endpoints
- Get a record ·
GET /v1/platform/records/{id} - Update a record ·
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
string
required
Which object: “company”, “person”, “deal”, or “custom” (custom objects also need schema_id). One of
company, person, deal, custom.string
Object schema id. Required when object_type is “custom”; the error lists the available ones. A 24-character hex id.
string[]
required
Ids of the records to delete, 1 to 100. Up to 100 items.
Returns
A readable text summary, plusstructuredContent with deleted_count, record_ids.
API endpoints
- Delete records ·
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
string
required
Which object: “company”, “person”, “deal”, or “custom” (custom objects also need schema_id). One of
company, person, deal, custom.string
Object schema id. Required when object_type is “custom”; the error lists the available ones. A 24-character hex id.
string
required
Name or part of a name, for example “acme”. Up to 200 characters.
integer
default:"20"
Maximum matches to return, 1 to 100. Default 20. From 1 to 100.
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, plusstructuredContent with matches, total_matches, index_truncated.
API endpoints
- Get a record ·
GET /v1/platform/records/{id} - List record names ·
GET /v1/platform/base-schemas/{id}/records/lookup