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

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

> [!WARNING]
>
> Changing `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.

> [!NOTE]
>
> In the Heliyos MCP server: [`heliyos_fields_update`](https://docs.heliyos.ai/mcp/tools/workspace-objects-and-fields#heliyos-fields-update).


## OpenAPI

````yaml /api-reference/openapi.json patch /v1/platform/base-schemas/{id}/fields/{fieldId}
openapi: 3.0.3
info:
  title: Heliyos API
  version: 1.0.0
  description: >-
    The REST API for Heliyos, the AI operating system for revenue. Every request
    is scoped to the workspace that owns the API key. Responses are JSON in a `{
    meta, data }` envelope; errors use `{ message, error: { code, message,
    details } }`.
  contact:
    name: Heliyos support
    email: soham@heliyos.ai
    url: https://www.heliyos.ai
servers:
  - url: https://api-prod.heliyos.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Workspace
    description: >-
      The workspace your API key belongs to, and the log of credits it has used.
      Every other call in this API is scoped to this workspace.
  - name: Schemas
    description: >-
      Objects are your record types: companies, people, deal pipelines and any
      custom objects you add. Each object has fields, and a field's type decides
      what its records can hold.
  - name: Records
    description: >-
      Records are the rows of an object (base schema): companies, people, deals
      and custom objects. A record holds field values keyed by the object's
      field keys and links to other records.
  - name: Timeline
    description: >-
      The AI-written timeline of a company, person or deal: summary entries
      Heliyos writes on a schedule. For the exact change history see Activities,
      and for emails and meetings see Interactions.
  - name: Activities
    description: >-
      The change history of records and tasks: who created, changed or deleted
      what, and when. People, workers and the system each appear as the actor on
      the changes they make.
  - name: Interactions
    description: >-
      Email threads and meetings synced from connected mailboxes and calendars,
      linked to the people and companies they involve.
  - name: Notes
    description: >-
      Free-text notes, optionally linked to records, tasks and interactions.
      Notes show up on the timeline of every record they are linked to, and
      workers read them as customer memory.
  - name: Tasks
    description: >-
      Work items for people and workers, optionally linked to records. A task
      can be assigned to people, to workers, or both, and workers can be started
      on it directly.
  - name: Workers and runs
    description: >-
      Workers are the AI teammates of your workspace (the API calls them
      agents). Define what each one does and what starts it, ask Heliyos to do
      work, and follow every run, its steps and the reviews it waits on.
  - name: Reviews
    description: >-
      Reviews keep the team in control of consequential work. When a worker
      wants to send an email, change a deal, book a meeting, act in a connected
      app or needs a person's answer, the action waits as a review until someone
      approves or rejects it.
  - name: Scouts
    description: >-
      Scouts watch companies and the web for events such as funding rounds,
      product launches, leadership changes or press coverage, and record each
      finding as a signal. A workspace Scout defines what to look for; company
      Scouts are its copies running on individual companies.
  - name: Signals
    description: >-
      Signals are what Scouts find: one event, such as a funding round or a new
      executive, with a summary, its sources and the company it is about. New
      signals are unread until you mark them read.
  - name: Watchlist
    description: >-
      The watchlist is the set of companies your workers monitor. Each watched
      company uses one Watcher from your plan: the workers keep it enriched,
      pull in its emails and meetings, and run Scouts on it.
  - name: Knowledge base
    description: >-
      What your workers know about the business: the business context, four
      fixed texts (products, pain points, value proposition, qualification
      criteria) and any custom entries your team adds. Workers read it on their
      next run. Files your workers read live under Files, with kind
      `knowledge_base`.
  - name: Files
    description: >-
      Knowledge base files that workers read, and files attached to records,
      tasks and other resources. The API calls them attachments. Uploading takes
      three calls: get an upload URL, send the bytes to it, then create the
      file.
  - name: Labels
    description: >-
      Label groups that sort your email threads, for example Intent or Pricing
      questions. Heliyos files each classified thread under a group, and each
      group holds the more specific labels it brings together. The API calls
      them classification labels.
  - name: Team
    description: >-
      The people in your workspace and their roles: joined members and pending
      invitations. Inviting someone sends them an email.
  - name: Notification settings
    description: >-
      Which workspace events send notification emails, how often, and to whom.
      There is one settings document per workspace, shared by everyone in it.
paths:
  /v1/platform/base-schemas/{id}/fields/{fieldId}:
    patch:
      tags:
        - Schemas
      summary: Update a field
      description: >-
        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. |
      operationId: updateBaseSchemaField
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          description: The object's id.
          example: 6730b1c4d3e5f6a7b8c9d0e1
        - name: fieldId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          description: The field's `id`, from Get an object.
          example: 6730c2d5e4f6a7b8c9d0e1f2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: >-
                    A new key, 1 to 100 characters. Stored values are not moved
                    (see the warning).
                type:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - richText
                        - number
                        - currency
                        - rating
                        - checkbox
                        - date
                        - timestamp
                        - select
                        - multiSelect
                        - url
                        - email
                        - phone
                        - user
                        - image
                        - relationship
                      description: The field type. Any other value is refused with 400.
                    enum:
                      type: array
                      items:
                        type: string
                      description: >-
                        Related kinds for the web app's editors, for example
                        `["text", "richText"]` for `text`. Send the value in the
                        field types table.
                    relationshipSchemaId:
                      type: string
                      description: '`relationship` only: id of the object to link to.'
                    relationshipConfig:
                      type: array
                      description: >-
                        `relationship` only: how the link maps onto the other
                        object. Stored on this object only; the matching field
                        on the other object is not created or changed.
                      items:
                        type: object
                        required:
                          - targetSchema
                          - associatedField
                          - inverseName
                        additionalProperties: false
                        properties:
                          targetSchema:
                            type: string
                            description: Id of the linked object.
                          associatedField:
                            type: string
                            description: Key of the matching field on the linked object.
                          inverseName:
                            type: string
                            description: Key of this side of the link.
                          onDelete:
                            type: string
                            enum:
                              - cascade
                              - setNull
                              - restrict
                            description: >-
                              What the link should do when the linked record is
                              deleted. Defaults to `setNull`.
                  required:
                    - type
                  additionalProperties: false
                  description: >-
                    A 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.
                displayName:
                  type: string
                  description: >-
                    The label shown in the web app, for example `Contract
                    value`. May be empty.
                sequence:
                  type: number
                  format: float
                  description: >-
                    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.
                icon:
                  type: string
                  description: An icon name from the web app's icon set.
                description:
                  type: string
                  description: >-
                    What the field holds. Shown in the web app and read by
                    workers.
                isAIEnabled:
                  type: boolean
                  description: >-
                    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.
                isHiddenField:
                  type: boolean
                  description: >-
                    true hides the field from table views by default. Default
                    false.
                required:
                  type: boolean
                  description: >-
                    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.
                unique:
                  type: boolean
                  description: >-
                    Shown in the web app. The API does not enforce uniqueness on
                    record writes. Default false.
                aiPrompt:
                  type: object
                  properties:
                    prompt:
                      type: string
                      description: The instructions workers follow to fill the field.
                    variables:
                      type: array
                      items:
                        type: string
                      description: >-
                        Names of the fields the prompt mentions. Send `[]` when
                        it mentions none.
                  additionalProperties: false
                  description: The AI column's prompt.
                validation:
                  type: object
                  properties:
                    rules:
                      type: array
                      maxItems: 20
                      description: >
                        Up to 20 rules, each `{ "type", "value", "message" }`.
                        Rule types:

                        - `minLength`, `maxLength`: string length, `value` a
                        number.

                        - `pattern`: a regular expression the value must match,
                        `value` a string of at most 200
                          characters. A pattern that is invalid or could take exponential time (nested repetition
                          such as `(a+)+`) is refused with 400.
                        - `email`: the value must be an email address (`value`
                        is ignored).

                        - `min`, `max`: number bounds, `value` a number.


                        Other rule types are stored but not checked. Use string
                        rules on text-like types and `min`

                        and `max` on number types.
                      items:
                        type: object
                        required:
                          - type
                          - value
                          - message
                        additionalProperties: false
                        properties:
                          type:
                            type: string
                            description: >-
                              `minLength`, `maxLength`, `pattern`, `email`,
                              `min` or `max`.
                          value:
                            description: The rule's argument.
                          message:
                            type: string
                            description: A message for people editing the record.
                  additionalProperties: false
                  description: >-
                    Rules checked whenever a record writes this field. Values
                    already stored are not re-checked.
                default:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - static
                        - dynamic
                      description: '`static` or `dynamic`.'
                    value:
                      description: The default value.
                  required:
                    - type
                    - value
                  additionalProperties: false
                  description: >-
                    A default stored with the field. Records are not filled from
                    it; use `settings.defaultValue` for that.
                settings:
                  type: object
                  properties:
                    selectOptions:
                      type: array
                      description: >-
                        `select` and `multiSelect`: the choices, in order. Each
                        is `{ "value", "color" }` or a bare string. Colours are
                        label families: `red`, `orange`, `amber`, `olive`,
                        `green`, `teal`, `blue`, `purple`, `pink`, `gray`.
                        Values are stored as sent; keep them unique.
                      items:
                        oneOf:
                          - type: string
                          - type: object
                            required:
                              - value
                              - color
                            additionalProperties: false
                            properties:
                              value:
                                type: string
                                description: >-
                                  The option's text, which is what records
                                  store.
                              color:
                                type: string
                                description: A label colour family.
                    currencyOptions:
                      type: object
                      additionalProperties: false
                      description: '`currency`: how the web app formats amounts.'
                      properties:
                        currency:
                          type: string
                          description: >-
                            A two-letter country code whose currency is used,
                            for example `US` for US dollars.
                        display:
                          type: string
                          description: '`symbol`, `code` or `name`.'
                    defaultValue:
                      description: >-
                        The value a new record gets when it is created without
                        one (missing, null or an empty string). Must fit the
                        field's type, or record creation fails.
                    aiRunStatus:
                      type: string
                      enum:
                        - RUNNING
                        - PENDING
                        - FINISHED
                        - ERROR
                        - ''
                      description: >-
                        A display status for an AI column. The web app sends
                        `PENDING` when it saves an AI column without running it.
                    abbreviateNumber:
                      type: boolean
                      description: >-
                        `number` and `currency`: show large values as 1.2k, 3.4M
                        and so on.
                  additionalProperties: false
                  description: >-
                    Replaces all of the field's settings. Include every key you
                    want to keep, for example the current `currencyOptions` when
                    you change `abbreviateNumber`.
                permissions:
                  type: object
                  properties:
                    visibility:
                      type: string
                      enum:
                        - private
                        - organization
                      description: '`organization` or `private`.'
                    editableBy:
                      type: object
                      additionalProperties: false
                      description: Who may edit the field when it is private.
                      properties:
                        roles:
                          type: array
                          items:
                            type: string
                          description: >-
                            Role names: `OWNER`, `ADMIN`, `MEMBER`, `STAFF`,
                            `SUPPORT`, `SUPER_ADMIN`, `AGENCY`.
                        users:
                          type: array
                          items:
                            type: string
                          description: User ids.
                    viewableBy:
                      type: object
                      additionalProperties: false
                      description: Who may view the field when it is private.
                      properties:
                        roles:
                          type: array
                          items:
                            type: string
                          description: Role names, as in `editableBy`.
                        users:
                          type: array
                          items:
                            type: string
                          description: User ids.
                  required:
                    - visibility
                    - editableBy
                    - viewableBy
                  additionalProperties: false
                  description: >-
                    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.
                runImmediately:
                  type: boolean
                  description: >-
                    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.
              additionalProperties: false
              minProperties: 1
            examples:
              relabel:
                summary: Rename the label
                value:
                  displayName: Partner level
              options:
                summary: Replace the options
                value:
                  settings:
                    selectOptions:
                      - value: Gold
                        color: amber
                      - value: Silver
                        color: gray
                      - value: Bronze
                        color: orange
                      - value: Registered
                        color: blue
              move:
                summary: Move the field to position 2
                value:
                  sequence: 2
      responses:
        '200':
          description: The whole object, with the updated field.
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  meta:
                    type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                        description: A human-readable summary of the result.
                  data:
                    $ref: '#/components/schemas/SchemaObject'
              example:
                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
        '400':
          description: >-
            VALIDATION_FAILED: the body is empty or invalid, `sequence` is less
            than 1, the new type is unknown, records hold values for the field
            during a type change ("Cannot change field type"), or the field
            could not be updated. Nothing is written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: 'FORBIDDEN_ACTION: you may not edit this field.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: >-
            NOT_FOUND: no object with this id in the workspace, or no field with
            this id on it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    SchemaObject:
      type: object
      description: An object (base schema) and its fields.
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ObjectId'
          description: >-
            The object's id. Records name it as their `schemaId`. List, create
            and update return it as `id`; get returns it as `_id`.
        _id:
          allOf:
            - $ref: '#/components/schemas/ObjectId'
          description: The object's id, as returned by get.
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ObjectId'
          description: The workspace the object belongs to.
        name:
          type: string
          description: The display name, for example `Partners`. Unique in the workspace.
        slug:
          type: string
          description: >-
            A short URL-safe name, unique in the workspace, used in web app
            links.
        description:
          type: string
          description: What the object holds.
        type:
          type: string
          enum:
            - base
            - computed
            - custom
          description: >-
            The object's kind. `base` for the built-in objects (companies,
            people and deal pipelines), `custom` for objects you create.
            `computed` is accepted but not used by Heliyos.
        objectType:
          type: string
          description: >-
            The record type records of this object carry: `company`, `people`
            and `deals` for the built-in objects. For a custom object it is
            derived from the name when the object is created (lowercase, spaces
            replaced by underscores, plus a 4-digit suffix if it is already
            taken) and never changes afterwards.
          example: partners
        icon:
          type: string
          description: The icon name the web app shows for the object.
        iconColor:
          type: string
          description: A label colour family for the icon, for example `blue`.
        viewType:
          type: string
          enum:
            - table
            - kanban
          description: >-
            How the web app shows the object by default. Deal pipelines use
            `kanban`.
        kanbanConfig:
          $ref: '#/components/schemas/SchemaKanbanConfig'
        fields:
          type: array
          description: >-
            The object's fields that you may view, in storage order. Sort by
            `sequence` for display order. Fields whose permissions hide them
            from you are left out.
          items:
            $ref: '#/components/schemas/SchemaField'
        permissions:
          $ref: '#/components/schemas/SchemaPermissions'
        agents:
          type: array
          description: Reserved for internal use.
          items:
            type: object
            additionalProperties: true
        recordCount:
          type: integer
          description: >-
            How many records the object has. Only in a list sent with
            `isRecordCount=true`.
        created:
          type: object
          description: When the object was created, and by whom.
          properties:
            at:
              $ref: '#/components/schemas/Timestamp'
            by:
              type: string
              description: Id of the user who created it, or `system` for built-in objects.
        updated:
          type: object
          description: When the object was last changed, and by whom.
          properties:
            at:
              $ref: '#/components/schemas/Timestamp'
            by:
              type: string
              description: Id of the user who last changed it.
    ErrorEnvelope:
      type: object
      required:
        - message
        - error
      properties:
        message:
          type: string
          description: Same as error.message.
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - VALIDATION_FAILED
                - UNAUTHENTICATED
                - FORBIDDEN_ACTION
                - NOT_FOUND
                - RATE_LIMITED
                - CONFLICT
                - INTERNAL
            message:
              type: string
            details: {}
    ObjectId:
      type: string
      pattern: ^[0-9a-fA-F]{24}$
      description: A 24-character hexadecimal id.
      example: 66f1a8c3e4b0a1b2c3d4e5f6
    SchemaKanbanConfig:
      type: object
      description: >-
        The board layout. Each lane is one option of the lane field. Lanes are
        managed in the web app; changing the lane field's
        `settings.selectOptions` adds and removes lanes to match.
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        laneField:
          type: string
          description: >-
            The key of the select field whose options are the lanes, for example
            `stage`.
        lanes:
          type: array
          description: The board's lanes.
          items:
            type: object
            properties:
              _id:
                $ref: '#/components/schemas/ObjectId'
              name:
                type: string
                description: The lane's name, equal to one option of the lane field.
              order:
                type: number
                description: The lane's position on the board.
              color:
                type: string
                description: A label colour family, for example `green`.
              icon:
                type: string
                description: An optional icon name.
              isVisible:
                type: boolean
                description: false when the lane is hidden on the board.
    SchemaField:
      type: object
      description: One field of an object.
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: The field's id. Use it as `fieldId` to change or delete the field.
          example: 6730c2d5e4f6a7b8c9d0e1f2
        _id:
          type: string
          description: An internal id some responses include. Address the field by `id`.
        name:
          type: string
          description: >-
            The field's key, which records use in `data` and filters name, for
            example `contract_value`.
        displayName:
          type: string
          description: The label shown in the web app.
        description:
          type: string
          description: What the field holds. Shown in the web app and read by workers.
        icon:
          type: string
          description: The icon name the web app shows next to the label.
        sequence:
          type: number
          description: The field's position in the object, starting at 1.
        type:
          $ref: '#/components/schemas/SchemaFieldType'
        settings:
          $ref: '#/components/schemas/SchemaFieldSettings'
        isAIEnabled:
          type: boolean
          description: true when workers fill the field from `aiPrompt` (an AI column).
        aiPrompt:
          type: object
          nullable: true
          description: The AI column's prompt.
          properties:
            prompt:
              type: string
              description: The instructions workers follow to fill the field.
            variables:
              type: array
              items:
                type: string
              description: Names of the fields the prompt mentions.
        isHiddenField:
          type: boolean
          description: true when the field is hidden from table views by default.
        isVisibleOnlyInPage:
          type: boolean
          description: true when the field shows only on the record page, not in tables.
        isReadOnly:
          type: boolean
          description: >-
            true when the web app shows the field as read-only. The API does not
            enforce it.
        required:
          type: boolean
          description: true when creating a record without this key fails.
        unique:
          type: boolean
          description: >-
            Shown in the web app. The API does not enforce uniqueness on record
            writes.
        validation:
          type: object
          description: Rules checked when a record is written.
          properties:
            rules:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: The rule. See `validation` on Create a field.
                  value:
                    description: The rule's argument.
                  message:
                    type: string
                    description: A message for people editing the record.
        default:
          type: object
          description: >-
            A stored default. Records are not filled from it;
            `settings.defaultValue` does that.
          properties:
            type:
              type: string
              enum:
                - static
                - dynamic
            value:
              description: The default value.
        permissions:
          $ref: '#/components/schemas/SchemaPermissions'
        hasAccess:
          type: boolean
          description: >-
            Present in lists. Always true, because fields you may not view are
            left out.
        metadata:
          $ref: '#/components/schemas/AuditMetadata'
    SchemaPermissions:
      type: object
      description: >-
        Who may view and edit. With `organization`, every member may. With
        `private`, only the roles and users listed (and the creator). API keys
        act with the `ADMIN` role.
      properties:
        visibility:
          type: string
          description: >-
            `organization` or `private`. Objects also store `public`, which
            behaves like an allow list of roles and users.
        editableBy:
          type: object
          description: Who may edit when `visibility` is `private`.
          properties:
            roles:
              type: array
              items:
                type: string
              description: >-
                Role names: `OWNER`, `ADMIN`, `MEMBER`, `STAFF`, `SUPPORT`,
                `SUPER_ADMIN`, `AGENCY`.
            users:
              type: array
              items:
                $ref: '#/components/schemas/ObjectId'
              description: User ids.
        viewableBy:
          type: object
          description: Who may view when `visibility` is `private`.
          properties:
            roles:
              type: array
              items:
                type: string
              description: Role names, as in `editableBy`.
            users:
              type: array
              items:
                $ref: '#/components/schemas/ObjectId'
              description: User ids.
    Timestamp:
      type: string
      format: date-time
      description: An ISO 8601 date-time in UTC.
      example: '2026-11-04T09:30:00.000Z'
    SchemaFieldType:
      type: object
      description: The field's type. See the field types table on Create a field.
      properties:
        type:
          type: string
          enum:
            - text
            - richText
            - number
            - currency
            - rating
            - checkbox
            - date
            - timestamp
            - select
            - multiSelect
            - url
            - email
            - phone
            - user
            - image
            - relationship
            - file
          description: >-
            What the field holds. `file` exists on some fields but cannot be
            created through the API.
        enum:
          type: array
          items:
            type: string
          description: >-
            Related kinds the web app uses for the field's editors, for example
            `["text", "richText"]`. A list containing `multiSelect` or `array`
            makes CSV import split values on commas.
        relationshipSchemaId:
          type: string
          description: '`relationship` fields: id of the object the field links to.'
        relationshipConfig:
          type: array
          description: '`relationship` fields: how the link maps onto the other object.'
          items:
            type: object
            properties:
              targetSchema:
                type: string
                description: Id of the linked object.
              associatedField:
                type: string
                description: Key of the matching field on the linked object.
              inverseName:
                type: string
                description: Key of this side of the link.
              onDelete:
                type: string
                enum:
                  - cascade
                  - setNull
                  - restrict
                description: >-
                  What the link should do when the linked record is deleted.
                  Defaults to `setNull`.
    SchemaFieldSettings:
      type: object
      description: Type-specific configuration.
      properties:
        selectOptions:
          type: array
          description: >-
            `select` and `multiSelect`: the choices, in order. Each is `{
            "value", "color" }` (a label colour family) or a bare string.
          items:
            oneOf:
              - type: string
              - type: object
                properties:
                  value:
                    type: string
                    description: The option's text, which is what records store.
                  color:
                    type: string
                    description: >-
                      A label colour family: `red`, `orange`, `amber`, `olive`,
                      `green`, `teal`, `blue`, `purple`, `pink` or `gray`.
        currencyOptions:
          type: object
          description: '`currency`: how the web app formats amounts.'
          properties:
            currency:
              type: string
              description: >-
                A two-letter country code whose currency is used, for example
                `US` for US dollars or `DE` for euros.
            display:
              type: string
              description: >-
                `symbol` ($1,200), `code` (USD 1,200) or `name` (1,200 US
                Dollar).
        abbreviateNumber:
          type: boolean
          description: '`number` and `currency`: show large values as 1.2k, 3.4M and so on.'
        defaultValue:
          description: >-
            The value a new record gets when it is created without one (missing,
            null or an empty string). Must fit the field's type.
        aiRunStatus:
          type: string
          enum:
            - RUNNING
            - PENDING
            - FINISHED
            - ERROR
            - ''
          description: >-
            A display status for an AI column, set by the web app. Heliyos does
            not update it.
    AuditMetadata:
      type: object
      description: Who created and last changed the resource, and when.
      properties:
        created:
          type: object
          properties:
            at:
              $ref: '#/components/schemas/Timestamp'
            by:
              allOf:
                - $ref: '#/components/schemas/ObjectId'
              description: Id of the user (or the API key's owner) who created it.
        updated:
          type: object
          properties:
            at:
              $ref: '#/components/schemas/Timestamp'
            by:
              allOf:
                - $ref: '#/components/schemas/ObjectId'
              description: Id of the user who last changed it.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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.

````

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