Guides
API reference
MCP server
Changelogcurl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/fields \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "partner_tier",
"displayName": "Partner tier",
"description": "Commercial tier agreed in the partner contract.",
"sequence": 4,
"type": {
"type": "select",
"enum": [
"select"
]
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
}
}
'{
"meta": {
"message": "Schema attribute added successfully"
},
"data": {
"id": "6730c2d5e4f6a7b8c9d0e1f2",
"sequence": 4,
"name": "partner_tier",
"displayName": "Partner tier",
"description": "Commercial tier agreed in the partner contract.",
"icon": "PiMedal",
"type": {
"type": "select",
"enum": [
"select"
],
"relationshipConfig": []
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"isAIEnabled": false,
"isHiddenField": false,
"isReadOnly": false,
"isVisibleOnlyInPage": false,
"required": false,
"unique": false,
"validation": {
"rules": []
},
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
},
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Create a field
Adds a field to an object (base schema). Every existing record gets an empty value for the new field. The response is the new field, not the whole object.
type.type decides what records can store. Send the type object shown, as the web app does.
Every type also accepts "" or null as no value.
type.type | Records store | Send as type | Extra configuration |
|---|---|---|---|
text | A string, trimmed. | {"type":"text","enum":["text","richText"]} | None |
richText | A string of formatted text. | {"type":"richText","enum":["richText","text"]} | None |
number | A number. | {"type":"number","enum":["number"]} | settings.abbreviateNumber |
currency | A number, the amount. | {"type":"currency","enum":["number"]} | settings.currencyOptions, settings.abbreviateNumber |
rating | A number. The web app shows 1 to 5 stars; the API does not limit it. | {"type":"rating","enum":["number"]} | None |
checkbox | true or false. | {"type":"checkbox","enum":["boolean"]} | None |
date | A date, sent as an ISO 8601 string. | {"type":"date","enum":["date","timestamp"]} | None |
timestamp | A date and time, sent as an ISO 8601 string. | {"type":"timestamp","enum":["timestamp","date"]} | None |
select | One string. | {"type":"select","enum":["select"]} | settings.selectOptions |
multiSelect | An array of strings. | {"type":"multiSelect","enum":["multiSelect"]} | settings.selectOptions |
url | A URL. Must parse as a URI. | {"type":"url","enum":["text"]} | None |
email | An email address. Must be valid. | {"type":"email","enum":["text"]} | None |
phone | A string. The format is not checked. | {"type":"phone","enum":["text"]} | None |
user | An array of workspace members. The web app stores { "id", "name", "email" } per member, id being the user id. | {"type":"user","enum":["user"]} | None |
image | An object. | {"type":"image","enum":["text"]} | None |
relationship | Links to records of another object. | {"type":"relationship","enum":["relationship"], ...} | type.relationshipSchemaId, type.relationshipConfig |
Record writes check a select value is a string and a multiSelect value is an array; they do
not check them against settings.selectOptions. Relationship fields are best created in the web
app, which sets up both sides of the link; this endpoint stores the configuration on this object
only. file fields cannot be created through the API.
With isAIEnabled: true and an aiPrompt, workers fill the field. Send runImmediately: true
to start filling every record of the object straight away. That run uses credits for each
record it processes.
See Update a field for what can change after creation and what each change does to stored values.
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/fields \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "partner_tier",
"displayName": "Partner tier",
"description": "Commercial tier agreed in the partner contract.",
"sequence": 4,
"type": {
"type": "select",
"enum": [
"select"
]
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
}
}
'{
"meta": {
"message": "Schema attribute added successfully"
},
"data": {
"id": "6730c2d5e4f6a7b8c9d0e1f2",
"sequence": 4,
"name": "partner_tier",
"displayName": "Partner tier",
"description": "Commercial tier agreed in the partner contract.",
"icon": "PiMedal",
"type": {
"type": "select",
"enum": [
"select"
],
"relationshipConfig": []
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"isAIEnabled": false,
"isHiddenField": false,
"isReadOnly": false,
"isVisibleOnlyInPage": false,
"required": false,
"unique": false,
"validation": {
"rules": []
},
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
},
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}name) the object does not already use. The API does not refuse a duplicate key:
the request succeeds without adding a field, and the existing field’s value is cleared to an
empty string on every record. Read the object’s fields first.heliyos_fields_create.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Path Parameters
The object's id.
^[0-9a-fA-F]{24}$Body
The field's key: what records use in data and filters name. 1 to 100 characters. Use lowercase letters, digits and underscores, starting with a letter, for example partner_tier. The API does not check the format yet, but keys with dots or $ do not work in filters and updates, so avoid them. Must be new on the object (see the warning).
1 - 100"partner_tier"
The field's type. type.type is required; send the rest as the web app does (see the field types table).
Show child attributes
Show child attributes
Required. Who may view and edit the field. With organization, every member who can see the object may. With private, only the listed roles and users. Send both roles and users in each list. The web app's default lists every role.
Show child attributes
Show child attributes
The label shown in the web app, for example Contract value. May be empty.
The field's position, starting at 1. To append, send the highest sequence on the object plus 1, as the web app does. Stored as sent.
4
An icon name from the web app's icon set.
What the field holds. Shown in the web app and read by workers.
true makes the field an AI column that workers fill from aiPrompt. The web app offers it for text, richText, number, date, select, multiSelect and checkbox. Turning it on or off resets each record's AI status for the field; stored values are kept.
true hides the field from table views by default. Default false.
true makes creating a record without this key fail with 400. An empty string or null still counts as a value, and record updates are not checked. Default false.
Shown in the web app. The API does not enforce uniqueness on record writes. Default false.
The AI column's prompt.
Show child attributes
Show child attributes
Rules checked whenever a record writes this field. Values already stored are not re-checked.
Show child attributes
Show child attributes
A default stored with the field. value must fit the field's type, or the request fails with 400. Records are not filled from it; use settings.defaultValue for that.
Show child attributes
Show child attributes
Type-specific configuration. See the field types table for which keys apply.
Show child attributes
Show child attributes
With isAIEnabled: true, starts a worker run now that fills this field on every record of the object. It uses credits for each record processed. Default false.
Was this page helpful?