Guides
API reference
MCP server
Changelogcurl --request PATCH \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/fields/{fieldId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"displayName": "Partner level"
}
'{
"meta": {
"message": "Schema attribute updated successfully"
},
"data": {
"id": "6730b1c4d3e5f6a7b8c9d0e1",
"organizationId": "66a0f1e2d3c4b5a697887766",
"name": "Partners",
"slug": "partners",
"description": "Resellers and referral partners.",
"type": "custom",
"objectType": "partners",
"icon": "PiHandshake",
"viewType": "table",
"kanbanConfig": {
"_id": "6730b1c4d3e5f6a7b8c9d0e2",
"lanes": []
},
"fields": [
{
"id": "6730b1c4d3e5f6a7b8c9d0e3",
"sequence": 1,
"name": "partners",
"displayName": "Partners",
"type": {
"type": "text",
"enum": [
"text",
"longText",
"richText"
],
"relationshipConfig": []
},
"isAIEnabled": false,
"isHiddenField": false,
"required": false,
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
}
},
{
"id": "6730c2d5e4f6a7b8c9d0e1f2",
"sequence": 4,
"name": "partner_tier",
"displayName": "Partner level",
"type": {
"type": "select",
"enum": [
"select"
],
"relationshipConfig": []
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"isAIEnabled": false,
"isHiddenField": false,
"required": false,
"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-05T10:12:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
],
"agents": [],
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
},
"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>"
}
}Update a field
Changes one field of an object (base schema). Send at least one property; properties you leave
out are kept. Each property you send replaces the stored one completely: settings, type,
permissions, validation, aiPrompt and default are not merged, so send the whole object.
The response is the whole object with all of its fields.
| Change | Effect on records |
|---|---|
displayName, description, icon, isHiddenField, unique | Display only. |
required, validation | Apply to later record writes. Stored values are not re-checked. |
settings.selectOptions | Replaces the options. Records holding a removed option keep it. On a board’s lane field, lanes are added and removed to match. |
settings (any key) | Replaces all settings: include the keys you want to keep. |
sequence | Moves the field to that position (starting at 1); the fields in between shift by one. |
isAIEnabled | Turns the AI column on or off and resets each record’s AI status. Stored values are kept. |
type | Refused with 400 while any record of the object holds a value for the field, including the empty value every record gets when a field is added. When accepted, stored values are not converted. |
name (the key) | Values are not moved. See the warning. |
permissions | Replaces who may view and edit the field. |
curl --request PATCH \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/fields/{fieldId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"displayName": "Partner level"
}
'{
"meta": {
"message": "Schema attribute updated successfully"
},
"data": {
"id": "6730b1c4d3e5f6a7b8c9d0e1",
"organizationId": "66a0f1e2d3c4b5a697887766",
"name": "Partners",
"slug": "partners",
"description": "Resellers and referral partners.",
"type": "custom",
"objectType": "partners",
"icon": "PiHandshake",
"viewType": "table",
"kanbanConfig": {
"_id": "6730b1c4d3e5f6a7b8c9d0e2",
"lanes": []
},
"fields": [
{
"id": "6730b1c4d3e5f6a7b8c9d0e3",
"sequence": 1,
"name": "partners",
"displayName": "Partners",
"type": {
"type": "text",
"enum": [
"text",
"longText",
"richText"
],
"relationshipConfig": []
},
"isAIEnabled": false,
"isHiddenField": false,
"required": false,
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
}
},
{
"id": "6730c2d5e4f6a7b8c9d0e1f2",
"sequence": 4,
"name": "partner_tier",
"displayName": "Partner level",
"type": {
"type": "select",
"enum": [
"select"
],
"relationshipConfig": []
},
"settings": {
"selectOptions": [
{
"value": "Gold",
"color": "amber"
},
{
"value": "Silver",
"color": "gray"
},
{
"value": "Registered",
"color": "blue"
}
]
},
"isAIEnabled": false,
"isHiddenField": false,
"required": false,
"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-05T10:12:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
],
"agents": [],
"permissions": {
"visibility": "organization",
"editableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
},
"viewableBy": {
"roles": [
"OWNER",
"ADMIN",
"MEMBER",
"STAFF",
"SUPPORT",
"SUPER_ADMIN"
],
"users": []
}
},
"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 changes the field’s key but leaves every record’s value under the old key,
where no field reads it, so the values stop showing. The API does not check that the new key is
free either. Treat the key as fixed and change displayName instead.heliyos_fields_update.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}$The field's id, from Get an object.
^[0-9a-fA-F]{24}$Body
A new key, 1 to 100 characters. Stored values are not moved (see the warning).
1 - 100A new type, replacing the current type object. Refused while records hold values for the field (see the table). Must be a type Heliyos knows, or the request fails with 400.
Show child attributes
Show child attributes
The label shown in the web app, for example Contract value. May be empty.
A new position, 1 or more. The field moves there and the fields in between shift by one. Less than 1 is refused with 400.
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. Records are not filled from it; use settings.defaultValue for that.
Show child attributes
Show child attributes
Replaces all of the field's settings. Include every key you want to keep, for example the current currencyOptions when you change abbreviateNumber.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
true starts a worker run now that fills this field on every record of the object, using credits for each record. It only runs when the field was already an AI column before this request; to turn on AI and run, send two requests. Default false.
Was this page helpful?