Resources
Custom fields
Read-only discovery of the organization's task custom field definitions and their options.
Custom fields are your organization's own information fields on tasks (see the feature guide). Each field has a type and, for select fields, a list of options. This resource is read-only: it lets an external client discover the field definitions so it can fill or clear their values when creating or updating a task. Creating and editing the definitions themselves stays in the app (Settings → Custom fields).
Endpoints
| Method | Path | Notes |
|---|---|---|
GET | /api/v1/custom-fields | List definitions in display order. Offset pagination. |
GET | /api/v1/custom-fields/{id} | A single definition, or 404. |
CustomFieldDefinition model
{
"id": "cf1…",
"name": "Severity",
"type": "select",
"position": 0,
"options": [
{ "id": "opt1…", "label": "Low", "position": 0 },
{ "id": "opt2…", "label": "High", "position": 1 }
]
}| Field | Type | Notes |
|---|---|---|
id | uuid | The definitionId you send when writing a task's custom fields. |
name | string | The field's display name (unique per organization). |
type | enum | text · longText · number · date · select · boolean. |
position | int | Display order across the organization's fields. |
options | array | Non-empty only for select fields. Each option's id is the optionId a select value references. |
Listing definitions
GET /api/v1/custom-fields?limit=50&offset=0| Param | Type | Default | Range |
|---|---|---|---|
limit | int | 50 | 1–100 |
offset | int | 0 | ≥ 0 |
Returns { data, total }, ordered by position ascending.
Getting one definition
GET /api/v1/custom-fields/{id}Returns { data }. A missing id, or one belonging to another organization, returns 404.