Workspace, objects and fields

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

​

Get the workspace

heliyos_organization_get · Read · Idempotent Returns the Heliyos workspace this API key belongs to: its id and name, billing status, active plan, member count, how many companies, people and deals it holds, and how many companies are watched out of the plan’s limit. Call it first to orient yourself. Use heliyos_objects_list for the objects and their schema ids, heliyos_usage_get for credit usage. Returns structuredContent {organization}. This tool takes no inputs.

​

Returns

A readable text summary, plus structuredContent with organization.

​

API endpoints

• Get the workspace · GET /v1/platform/organization

​

List objects

heliyos_objects_list · Read · Idempotent Lists the workspace’s objects (record types): companies, people, deals and any custom objects, with each one’s schema_id, object_type, record count and number of fields. Use it to learn which object_type and schema_id to pass to the heliyos_records_* tools (custom objects need schema_id), then heliyos_objects_get for an object’s field keys. Returns every object in one page (a workspace has a handful), as structuredContent {objects}.

​

Inputs

​

Returns

A readable text summary, plus structuredContent with objects.

​

API endpoints

• List objects · GET /v1/platform/base-schemas

​

Get an object’s fields

heliyos_objects_get · Read · Idempotent Returns one object’s fields: each field key (what heliyos_records_create, _update and _list filters take), its label and type, and which are required. “detailed” adds the allowed values of select fields, hidden and AI-filled flags, and the target object of relationship fields. Pick the object with object_type (company, person, deal, or custom with schema_id from heliyos_objects_list). Each field’s field_id feeds heliyos_fields_update and heliyos_fields_delete; heliyos_fields_create adds one. Returns structuredContent {object:{schema_id, name, fields:[{key, field_id, type, …}]}}.

​

Inputs

​

Returns

A readable text summary, plus structuredContent with object.

​

API endpoints

• Get an object · GET /v1/platform/base-schemas/{id}

​

Add a field to an object

heliyos_fields_create · Write Adds one field (column) to an object: companies, people, deals or a custom object (object_type, plus schema_id for custom). Give it a label and a type; select and multiSelect need options; ai_prompt makes it an AI column. The field key (what record fields and filters use) is derived from the label unless key is given, and must be new on the object. Relationship fields are created in the Heliyos web app. Calling this twice with the same key fails. Returns structuredContent {field:{field_id, key, label, type}}.

​

Inputs

​

Returns

A readable text summary, plus structuredContent with field.

​

API endpoints

• Get an object · GET /v1/platform/base-schemas/{id}
• Create a field · POST /v1/platform/base-schemas/{id}/fields

​

Change a field

heliyos_fields_update · Destructive · Idempotent Changes one field of an object by field_id (from heliyos_objects_get): its label, description, options, required or hidden flag, AI prompt, or type. What you leave out is kept. options REPLACES the allowed values, and records holding a removed value keep it as stale text. A type change is refused by the platform when existing values do not fit the new type. The field key never changes. Returns structuredContent {field}.

​

Inputs

​

Returns

A readable text summary, plus structuredContent with field.

​

API endpoints

• Get an object · GET /v1/platform/base-schemas/{id}
• Update a field · PATCH /v1/platform/base-schemas/{id}/fields/{fieldId}

​

Delete a field

heliyos_fields_delete · Destructive · Idempotent Permanently deletes one field of an object by field_id (from heliyos_objects_get) AND its value on every record. This cannot be undone: confirm with the user first, naming the field and the object. Built-in required fields (for example a company’s name) are refused by the platform. Returns structuredContent {field_id, key, deleted}.

​

Inputs

​

Returns

A readable text summary, plus structuredContent with field_id, key, deleted.

​

API endpoints

• Get an object · GET /v1/platform/base-schemas/{id}
• Delete a field · DELETE /v1/platform/base-schemas/{id}/fields/{fieldId}