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

# Workspace, objects and fields

> 6 tools: heliyos_organization_get, heliyos_objects_list, heliyos_objects_get, heliyos_fields_create, heliyos_fields_update, heliyos_fields_delete.

| Tool | What it does | Kind |
| - | - | - |
| [`heliyos_organization_get`](#heliyos-organization-get) | Get the workspace | Read |
| [`heliyos_objects_list`](#heliyos-objects-list) | List objects | Read |
| [`heliyos_objects_get`](#heliyos-objects-get) | Get an object's fields | Read |
| [`heliyos_fields_create`](#heliyos-fields-create) | Add a field to an object | Write |
| [`heliyos_fields_update`](#heliyos-fields-update) | Change a field | Destructive |
| [`heliyos_fields_delete`](#heliyos-fields-delete) | Delete a field | Destructive |

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](https://docs.heliyos.ai/api-reference/workspace/get-the-workspace.md) · `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

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

"concise" (default) returns one line per object; "detailed" returns each object's field keys too. One of `concise`, `detailed`.

### Returns

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

### API endpoints

* [List objects](https://docs.heliyos.ai/api-reference/schemas/list-objects.md) · `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

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

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

"concise" (default) returns each field's key, label and type; "detailed" returns select options and field flags too. One of `concise`, `detailed`.

### Returns

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

### API endpoints

* [Get an object](https://docs.heliyos.ai/api-reference/schemas/get-an-object.md) · `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

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

**label** `string` *required*

Display name, for example "Contract value". Up to 100 characters.

**key** `string`

Field key, for example contract\_value. Derived from the label when omitted.

**type** `string` *required*

One of text, richText, number, currency, rating, checkbox, date, timestamp, select, multiSelect, url, email, phone, user, image, file. One of `text`, `richText`, `number`, `currency`, `rating`, `checkbox`, `date`, `timestamp`, `select`, `multiSelect`, `url`, `email`, `phone`, `user`, `image`, `file`.

**description** `string`

What the field holds; shown in the web app and read by the workers. Up to 1000 characters.

**options** `string[]`

Allowed values of a select or multiSelect field, unique. Up to 200 items.

**required** `boolean`

Records must have a value. Default false.

**hidden** `boolean`

Hidden from the web app's tables by default. Default false.

**visibility** `string` (default: organization)

"organization" (default): every member sees it; "private": only owners and admins. One of `organization`, `private`.

**ai\_prompt** `string`

Makes this an AI column: the workers fill it from this prompt (text, richText, number, date, select, multiSelect or checkbox only). Filling existing records is started from the Heliyos web app and uses credits. Up to 5000 characters.

### Returns

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

### API endpoints

* [Get an object](https://docs.heliyos.ai/api-reference/schemas/get-an-object.md) · `GET /v1/platform/base-schemas/{id}`
* [Create a field](https://docs.heliyos.ai/api-reference/schemas/create-a-field.md) · `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

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

**field\_id** `string` *required*

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

**label** `string`

Display name, for example "Contract value". Up to 100 characters.

**description** `string`

What the field holds; shown in the web app and read by the workers. Up to 1000 characters.

**type** `string`

New type; values must fit it. One of `text`, `richText`, `number`, `currency`, `rating`, `checkbox`, `date`, `timestamp`, `select`, `multiSelect`, `url`, `email`, `phone`, `user`, `image`, `file`.

**options** `string[]`

Allowed values of a select or multiSelect field, unique. Up to 200 items.

**required** `boolean`

true: records must have a value.

**hidden** `boolean`

true: hidden from the web app's tables by default.

**ai\_prompt** `string`

Makes this an AI column: the workers fill it from this prompt (text, richText, number, date, select, multiSelect or checkbox only). Filling existing records is started from the Heliyos web app and uses credits. Up to 5000 characters.

### Returns

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

### API endpoints

* [Get an object](https://docs.heliyos.ai/api-reference/schemas/get-an-object.md) · `GET /v1/platform/base-schemas/{id}`
* [Update a field](https://docs.heliyos.ai/api-reference/schemas/update-a-field.md) · `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

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

**field\_id** `string` *required*

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

### Returns

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

### API endpoints

* [Get an object](https://docs.heliyos.ai/api-reference/schemas/get-an-object.md) · `GET /v1/platform/base-schemas/{id}`
* [Delete a field](https://docs.heliyos.ai/api-reference/schemas/delete-a-field.md) · `DELETE /v1/platform/base-schemas/{id}/fields/{fieldId}`


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