Workspace work item properties overview

A workspace work item property is a custom field, such as Severity, Customer impact, or Rollout date, that you define once for the whole workspace instead of redefining it in each project. It is the workspace-level counterpart to project work item properties.

/api/v2/workspaces/{slug}/work-item-properties/

Defining a property is not the same as applying it

Creating a property here adds it to the workspace catalog. It does not put it on any work item. A property reaches work items through a context, which binds it to projects and work item types. A workspace property with no context is defined but not yet applied anywhere. See Property contexts.

Writes require workspace mode

A workspace manages work item types in exactly one mode: project-level or workspace-level. Creating, updating, or deleting on this route while the workspace is in project mode returns 409 with the code work_item_types_managed_at_project. In that mode, properties are managed on the project surface. Reads are unaffected by mode. See Work item type modes.

The property object

Attributes

• id string (uuid)

  Unique identifier for the property. This is the id you use in a context's payload and when attaching the property to a workspace work item type.

• name string

  Read-only companion to display_name. You never set it directly.

• display_name string

  The label shown wherever the property is rendered. This is the field you write. Maximum 255 characters.

• description string

  Free-form explanation of what the property captures. May be null.

• property_type string

  What kind of value the property holds. One of TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE, or FORMULA. Choose it carefully, because it determines what the other fields mean.

• relation_type string

  For a RELATION property, what the property points at. One of ISSUE, USER, RELEASE, or RICH_TEXT. null for every other property type.

• is_required boolean

  Whether a value must be supplied for this property.

• is_multi boolean

  Whether the property accepts more than one value.

• is_active boolean

  Whether the property is in use. Set it to false to retire a property without deleting it.

• default_value array of string

  The value applied when none is supplied. Always an array, even when is_multi is false.

• options array of any

  The choices for an OPTION property. Read-only on this object. Manage the list through Property options, or seed it at create time with the write-only options body field.

• settings any

  Type-specific configuration. Its shape depends on property_type.

• validation_rules any

  Type-specific validation configuration.

• logo_props any

  Presentation data for the property's icon.

• external_id , external_source string

  Correlation fields for sync and import. Together they let you map a property to a field in another system and find it again later. Either may be null.

• created_at string (date-time)

  When the property was created.

• updated_at string (date-time)

  When the property was last updated.

• updated_by_id string (uuid) or null

  The user who last updated the property. null until someone updates it.

Response200

{
  "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
  "name": "severity",
  "display_name": "Severity",
  "description": "How badly the customer is affected",
  "property_type": "OPTION",
  "relation_type": null,
  "is_required": true,
  "is_multi": false,
  "is_active": true,
  "default_value": ["Major"],
  "options": [
    {
      "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
      "name": "Critical",
      "description": "Production is down",
      "parent_id": null,
      "is_default": false,
      "is_active": true,
      "sort_order": 10000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    },
    {
      "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
      "name": "Major",
      "description": "A core workflow is broken",
      "parent_id": null,
      "is_default": true,
      "is_active": true,
      "sort_order": 20000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    }
  ],
  "settings": {},
  "validation_rules": {},
  "logo_props": {},
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/work-item-properties/	List workspace work item properties
GET	/api/v2/workspaces/{slug}/work-item-properties/{pk}/	Get a workspace work item property
POST	/api/v2/workspaces/{slug}/work-item-properties/	Create a workspace work item property
PATCH	/api/v2/workspaces/{slug}/work-item-properties/{pk}/	Update a workspace work item property
DELETE	/api/v2/workspaces/{slug}/work-item-properties/{pk}/	Delete a workspace work item property

Property types

property_type decides how the value is captured and which of the other fields matter.

property_type	What it holds
TEXT	Free-form text
DATETIME	A date and time
DECIMAL	A number
BOOLEAN	True or false
OPTION	A choice from a defined list. See Property options
RELATION	A pointer to another record. Pair it with relation_type
URL	A link
EMAIL	An email address
FILE	A file
FORMULA	A formula-backed value

relation_type is only meaningful for RELATION, and takes ISSUE, USER, RELEASE, or RICH_TEXT. On every other property type it is null.

Contexts decide where a property applies

The catalog lists which properties exist in the workspace. A context sets where each one shows up. Each context binds the property to a set of projects and work item types, either listed in project_ids and issue_type_ids or opened up with applies_to_all_projects and applies_to_all_work_item_types. Each context also carries its own is_required, is_multi, default_value, options, and sort_order.

The usual sequence is:

1. POST /work-item-properties/: define the property once.
2. POST /work-item-properties/{property_id}/contexts/: say where it applies.

If you skip step 2, the property exists but appears nowhere. For full details, see Property contexts.

Related resources

• Property options: the choices behind an OPTION property.
• Workspace type properties: attach an existing property to a workspace-level work item type.
• Work item type modes: which surface your workspace writes to.