Change a custom field
const url = 'https://beta-api.plune.ai/v1/custom-fields/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"showInFilter":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://beta-api.plune.ai/v1/custom-fields/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "showInFilter": true }'The project owner’s. Name, options (the whole list; ids keep an option under a new label), required, defaultValue and the two toggles. Type, multiple and entity are fixed (400). Cases that hold an option taken off the list keep it.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”Any of these; entity, type, multiple and role are refused (400) because they are fixed. An empty object is refused. A configuration group refuses required: true and a defaultValue (400).
object
The whole list as it should be. An option left out is taken off the list — except on a configuration group, where it is a 400: archive it instead.
object
An id the field already has — keeps the option under a new label or position. Leave it out for a new option.
#1251: true archives the option (the server sets archivedAt), false restores it; left out, the option stays as it is.
Example
{ "showInFilter": true}Responses
Section titled “ Responses ”The field as it is now
object
What the field is on: a case, a suite, a run, a plan or a step. Its values ride on that entity as custom (for a step, on the Steps Database row, not on the case that carries it). A step field cannot be required.
Unique among the fields of the entity in the project, case-insensitively, archived fields included.
Fixed after creation.
A list field that takes several options. Fixed after creation; only a list can be.
In the order a person set; null for a string or number field. An option taken off the list stays on the cases that hold it, shown as stale, and is refused only as a NEW value.
object
Never changes and is never reused: this is what a case stores. A rename changes label only.
Present while the option is archived (#1251), set by the server on archived: true: it is not taken as a new value, and an entity that holds it keeps it.
Checked when a case is created. On an existing case the server only refuses to clear the value; it does not demand one.
Independent of showInList (#1250 AC-07). A toggle for the screen, not for access.
Dense 0..n-1 among the live fields of the entity with the same role: the configuration groups have an order of their own (#1251).
Where the field came from (#1930): testrail - the TestRail import made it or carries values into it (the settings page shows “From TestRail”); null - a person made it. Set by the server only: a create or a patch that sends it does not set it, and it never changes once set.
configuration — a configuration group (#1251, ADR 0070): a run list of several values, which a launch multiplies into the run’s combinations. Fixed at creation. Its values are archived, never removed; it is neither required nor has a default; position, the limit of 50 and the name are counted among the groups apart from the fields. null — a field.
Set while the field is archived: it takes no new value and its old values stay.
Example
{ "id": "6f1c2b3a-0000-4000-8000-0000000000f4", "projectId": "u-shop::default", "entity": "case", "name": "Browser", "type": "list", "multiple": true, "options": [ { "id": "opt_chrome0001", "label": "Chrome" }, { "id": "opt_firefox001", "label": "Firefox" } ], "required": false, "defaultValue": null, "showInList": true, "showInFilter": true, "position": 0, "role": null, "archivedAt": null, "createdAt": "2026-09-16T09:12:04.151Z", "updatedAt": "2026-09-16T09:12:04.151Z"}Invalid body, a value the field does not take, or a rule broken
object
Example
{ "error": "validation failed — name: a field needs a name"}No / invalid token or session
You are in the project, but not as its owner
object
Example
{ "error": "project owner only"}No such field in your projects
object
Example generated
{ "error": "example"}A field of that name exists for the entity (an archived one counts)
object
Example
{ "error": "a field named 'Browser' already exists for this entity (an archived one counts)"}Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.
object
Example generated
{ "error": "example"}Headers
Section titled “Headers ”Seconds until the window rolls over