> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List custom fields

> Returns all custom fields in a workspace that are visible to the API key user.

<Info>
  Requires the `tasks:read` scope. You must be a member of the workspace.
  Fields with a restricted **allowed users** list are filtered to the API key
  user only when their user ID is included in that list.
</Info>

## Path parameters

<ParamField path="id" type="string" required>
  The numeric workspace ID.
</ParamField>

## Response

Returns an array of custom field objects ordered by `position` ascending.

<ResponseField name="id" type="number" required>
  Custom field identifier.
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name of the custom field (e.g., `"Customer Tier"`).
</ResponseField>

<ResponseField name="type" type="string" required>
  Field type. One of `text`, `number`, `date`, `checkbox`, `rating`, `dropdown`, `money`, or `people`.
</ResponseField>

<ResponseField name="config" type="object | null">
  Type-specific configuration object. `null` for types with no configuration.

  <Expandable title="Config by type">
    **`rating`** — `{ "iconName": "star-filled", "color": "yellow" }`

    **`dropdown`** — `{ "options": ["Option A", "Option B"] }`

    **`money`** — `{ "currency": "USD", "decimals": 2 }`

    All other types return `null`.
  </Expandable>
</ResponseField>

<ResponseField name="position" type="number" required>
  Sort position within the workspace (ascending).
</ResponseField>

<ResponseField name="is_scope_restricted" type="boolean" required>
  When `false`, the field is available on all lists in the workspace. When `true`, the field is only available on lists covered by `granted_folder_ids` and `list_overrides`.
</ResponseField>

<ResponseField name="granted_folder_ids" type="number[]" required>
  Folder IDs where this field applies when `is_scope_restricted` is `true`. All lists inside a granted folder inherit the field unless overridden.
</ResponseField>

<ResponseField name="list_overrides" type="array" required>
  Explicit list-level overrides when `is_scope_restricted` is `true`. Each entry has `list_id` (number) and `access` (`granted` or `denied`). A `denied` entry hides the field on that list even if its folder is granted.

  <Expandable title="Override object">
    **`list_id`** — numeric list ID

    **`access`** — `granted` makes the field available on that list; `denied` hides it
  </Expandable>
</ResponseField>

<Note>
  Task responses (`GET /tasks/:id`, list tasks, etc.) only include custom fields that apply to the task's list. Values for inapplicable fields are not returned, and writes to those fields are ignored.
</Note>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": 1,
      "name": "Customer Tier",
      "type": "dropdown",
      "config": { "options": ["Free", "Starter", "Pro"] },
      "position": 1,
      "is_scope_restricted": false,
      "granted_folder_ids": [],
      "list_overrides": []
    },
    {
      "id": 2,
      "name": "Story Points",
      "type": "number",
      "config": null,
      "position": 2,
      "is_scope_restricted": true,
      "granted_folder_ids": [4],
      "list_overrides": []
    },
    {
      "id": 3,
      "name": "Satisfaction",
      "type": "rating",
      "config": { "iconName": "star-filled", "color": "yellow" },
      "position": 3,
      "is_scope_restricted": true,
      "granted_folder_ids": [],
      "list_overrides": [{ "list_id": 12, "access": "granted" }]
    }
  ]
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Scope 'tasks:read' is required for this endpoint"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Workspace not found"
  }
  ```
</ResponseExample>