Custom Fields

Overview

Custom fields let you attach structured data to every task on a board, beyond the built-in properties like priority, size, and due date. Each board defines its own set of fields, and every task on that board gets a value slot for each one.

Five field types are supported:

Type	Use for
Number	Ratings, scores, estimates — anything you sort numerically
Text	Free-form notes that need their own column
Select	A fixed list of options
Date	A date separate from due date
Checkbox	A yes/no flag

The flagship use case is an ICE rating (a Number field for Impact/Confidence/Ease scoring) used to rank a backlog. The ICE ranking recipe below walks through setting one up end to end.

Creating a field

Press <kbd>Ctrl+K</kbd> and search for “Create custom field”.
Enter a name for the field.
Pick a type: Number, Text, Select, Date, or Checkbox.
Press <kbd>Enter</kbd> to create it.

The field is created on the current board and is visible by default — no separate step to turn it on.

Setting values

Open a task and the field appears as a property row in the right rail, alongside priority, size, and due date. Click it, type or pick a value, and press <kbd>Enter</kbd> to save.

Table view: columns and sorting

Every custom field on a board shows up as a column in table view:

Sorting: click a custom field’s column header to sort by it. Number and Date fields sort numerically/chronologically; empty values always sort to the bottom regardless of sort direction.
Columns picker: open “Configure table columns” to toggle any custom field’s visibility or drag it to reorder, the same as built-in columns. “Reset to default” restores the original set.

Views

A saved view captures the table’s current sort, so a view sorted by a custom field stays sorted every time it’s opened. This is what makes an ICE ranking view sharable: save it once, and everyone who opens the view sees the backlog in ICE order.

ICE ranking recipe

Create a Number field named ICE on the board (see Creating a field above).
Open each task and set its ICE score in the right rail.
Switch to table view, add the ICE column if it’s hidden, and click the header to sort descending.
Save the sorted table as a view named “ICE ranking”.

Anyone who opens the “ICE ranking” view sees the board pre-sorted by score, no re-sorting required.

For agents & API

Custom fields are managed through the same Bearer htk_... REST API used elsewhere in Hypertask (authentication). Task detail responses include a customFieldValues array for every task on a board with custom fields defined.

Create a field

Endpoint: POST /api/mcp/custom-fields

Creating a field is idempotent on name — calling create again with a name that already exists on the board returns the existing field instead of erroring.

curl -s -X POST \
  -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 123, "name": "ICE", "type": "number"}' \
  "https://app.hypertask.ai/api/mcp/custom-fields"

Response example:

{
  "fieldId": 789,
  "name": "ICE",
  "type": "number"
}

Set a value

Endpoint: POST /api/mcp/custom-fields/value

Accepts either field_id or field_name. The recommended surface is to first create the field via POST /api/mcp/custom-fields, obtaining field_id, then assign values. Values are strictly validated against the field’s type — for example, a non-numeric value sent to a Number field is rejected with a 400 response.

Set value by field_id

curl -s -X POST \
  -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id": 789, "field_id": 789, "value": 42}' \
  "https://app.hypertask.ai/api/mcp/custom-fields/value"

Switch to field_name (auto-creates the field first)

curl -s -X POST \
  -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id": 789, "field_name": "ICE", "value": 42}' \
  "https://app.hypertask.ai/api/mcp/custom-fields/value"

Tips:

Use field_id in named endpoints after retrieval for clarity.
Typed values must match the field’s declared type.
Empty or unset values are represented as null unless overridden.

Delete a field

Endpoint: DELETE /api/mcp/custom-fields/{fieldId}

curl -s -X DELETE \
  -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/mcp/custom-fields/456"

Deleting a field removes every task’s value for it. This can’t be undone.