", …]}` and appends those properties to the type. The response is `201` with a
+`properties` array.
+
+- Only properties belonging to the **same project** can be attached. An id from another project is a
+ `400 invalid_request` that names the offending ids, never a silent skip — one bad id rejects the whole call.
+- Re-attaching a property the type already exposes is harmless. The call still returns `201` and the type is not left
+ with a duplicate, so a replayed request is safe.
+
+## Detaching
+
+`DELETE .../properties/{pk}/` removes the link and returns `204`.
+
+::: warning Detaching clears stored values
+The property definition survives — it stays in the project and stays attached to every other type that uses it, ready
+to re-attach. What does not survive is the data: the values already recorded for that property on work items **of this
+type** are removed with the link, and re-attaching does not bring them back.
+
+Deleting the definition outright is a different call —
+[Delete a work item property](/api-reference/v2/work-item-properties/delete-work-item-property).
+:::
+
+## Mode matters for writes, not reads
+
+Attaching and detaching are **project-mode** writes. If the workspace manages work item types at the workspace level,
+both return `409 work_item_types_managed_at_workspace` — the capability exists, it just lives on the other surface. Use
+[Attach a property to a workspace type](/api-reference/v2/workspace-work-item-type-properties/attach-workspace-type-property)
+instead.
+
+Reads are unaffected: listing and retrieving a type's properties works in either mode.
+
+See [Work item type modes](/api-reference/v2/work-item-type-modes) for how to tell which mode a workspace is in.
+
+## Changed from v1
+
+- In v1 a property was created **inside** a type, at
+ `POST /api/v1/workspaces/{slug}/projects/{project_id}/work-item-types/{type_id}/work-item-properties/`, so it belonged
+ to that one type.
+- In v2 the definition moved up to the project (`/work-item-properties/`) and this path became a link:
+ `POST` attaches existing properties, `DELETE` detaches one. There is no create and no update here.
+- One property can now be attached to several types.
+
+See [Migrating from v1](/api-reference/v2/migrating-from-v1) for the full list.
diff --git a/docs/api-reference/v2/work-item-types/create-work-item-type.md b/docs/api-reference/v2/work-item-types/create-work-item-type.md
new file mode 100644
index 00000000..aa1fdf3d
--- /dev/null
+++ b/docs/api-reference/v2/work-item-types/create-work-item-type.md
@@ -0,0 +1,242 @@
+---
+title: Create a work item type
+description: Create a project-level work item type in Plane with the v2 REST API. Body parameters, project mode requirements, OAuth scopes, error codes, and code examples.
+keywords: plane api v2, create work item type, issue type, project mode, external_id, POST work item types
+---
+
+# Create a work item type
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/
+
+
+
+
+
+Add a work item type to a project — `Bug`, `Spike`, `Chore`, whatever your team actually tracks. The new type is immediately selectable on work items, and becomes the target you attach custom properties to.
+
+Call [Enable work item types](/api-reference/v2/work-item-types/enable-work-item-types) first. Creating a type in a project where the feature has never been turned on leaves you with a type nobody can pick.
+
+Keep the `id` from the response. Every later step — attaching properties, reading the schema, creating a work item of this type — is keyed on it.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Create the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/create-workspace-work-item-type) instead, then [import it into the project](/api-reference/v2/work-item-types/import-work-item-types). See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to add the type to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name for the type, for example `Bug`. Maximum 255 characters.
+
+
+
+
+
+What this type is for. This is not decoration: it is returned as `type_description` by the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema), which is how an integration or agent decides between `Bug` and `Task` without a human in the loop.
+
+
+
+
+
+Whether the type can be assigned to new work items. Create it inactive if you are staging a configuration and want to attach its properties before anyone can select it.
+
+
+
+
+
+Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+::: info is_default, is_epic, level and logo_props are not accepted here
+`is_default` moves through [mark-default](/api-reference/v2/work-item-types/mark-default-work-item-type). `is_epic` and `level` are read-only. `logo_props` is generated by Plane when the type is created — the response tells you what it picked.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | Missing `name`, or a field over its 255-character limit. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't create work item types. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A type in this project already uses this `external_id` and `external_source` pair. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": True,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Bug",
+ description: "Something is broken and needs a fix",
+ is_active: true,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_workspace",
+ "detail": "Work item types are managed at the workspace level for this workspace."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Remove a work item type from a project. A successful delete returns `204` with an empty body.
+
+Deletion is guarded. A type that is the project default, or that still has work items on it, is rejected with `409 conflict` rather than cascading — the API will not silently untype existing work.
+
+If your goal is to stop people picking a type, [set `is_active` to `false`](/api-reference/v2/work-item-types/update-work-item-type) instead. That works regardless of how many work items already use the type, and it is reversible.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Delete the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/delete-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to delete.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed as sent. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't delete work item types. |
+| `404` | `not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The type is the project default, or work items still use it. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "conflict",
+ "detail": "A work item type with existing work items cannot be deleted."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/enable/
+
+
+
+
+
+Turn the work item types feature on for a project. **This is the first call in the project-mode lifecycle** — until it succeeds the project has no types, so there is nothing to create properties against and nothing for a work item's `type_id` to point at.
+
+Enabling also provisions a default type, normally named `Task`, and returns it. That returned `id` is the type new work items land on when no `type_id` is supplied, and it is a valid target for [attaching properties](/api-reference/v2/work-item-type-properties/attach-type-property) straight away.
+
+There is **no request body**. The path carries everything the call needs.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. In that mode there is nothing to enable per project — the workspace already owns the types, and you [import them into the project](/api-reference/v2/work-item-types/import-work-item-types) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to turn work item types on for.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. Send the request without a body.
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed as sent. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't configure this project's work item types. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The workspace manages types at the workspace level. Import instead of enabling. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+default_type = response.json()
+print(default_type["id"], default_type["name"])
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/enable/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const defaultType = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_workspace",
+ "detail": "Work item types are managed at the workspace level for this workspace."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/schema/
+
+
+
+
+
+Ask the API what a work item of this type accepts. The response describes the **standard fields** every work item has — with the project's actual states, priorities, and estimate points inlined as valid options — plus the **custom properties** attached to this type, including which ones are required and what values they allow.
+
+This is the discovery endpoint. A client that is about to create a work item calls this first, then builds its request body from the answer instead of hardcoding a field list. That matters most for two callers:
+
+- **Integrations**, which must adapt when an admin adds a required property to a type. Reading the schema each time means a new required field surfaces as a field to fill, not as a `400` in production.
+- **AI agents and generated tooling**, which need a machine-readable contract. `fields` and `custom_fields` are shaped to be handed straight to a function-calling schema: every entry carries a type, a required flag, and its allowed options.
+
+Reads are unaffected by [work item type mode](/api-reference/v2/work-item-type-modes) — the schema resolves the type's properties whether they are owned by the project or by the workspace.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to. The schema is project-specific: states, labels, members, and estimate points all come from this project.
+
+
+
+
+
+The id of the work item type whose schema you want.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated extra option lists to inline. Two values are recognized:
+
+- `members` — inlines the project's active members as the options for `assignee_ids`, and for any custom property that is a user relation
+- `labels` — inlines the project's labels as the options for `label_ids`
+
+Omit it and those fields still appear, they just describe themselves without an option list. These lists can be large in a big workspace, so ask for them only when you are actually rendering a picker — for example `?include=members,labels`.
+
+
+
+
+
+
+
+
+### Response Fields
+
+
+
+
+
+The type this schema describes. Send it as `type_id` on the work item you create. Nullable.
+
+
+
+
+
+The type's display name, for example `Bug`. Nullable.
+
+
+
+
+
+The type's description. This is the text a human or an agent reads to decide whether this is the right type for the work at hand, which is why filling it in on [create](/api-reference/v2/work-item-types/create-work-item-type) is worth the effort. Nullable.
+
+
+
+
+
+The icon and background color rendered next to the type. Nullable.
+
+
+
+
+
+The standard work item fields, keyed by the body parameter name you would send — `name`, `description_html`, `priority`, `state_id`, `assignee_ids`, `label_ids`, `start_date`, `target_date`, `parent_id`. Each entry carries a `type`, a `required` flag, and where it applies an `is_multi` flag, a `default`, a `max_length`, a `format`, or an `options` array.
+
+`state_id` and `priority` always arrive with their options inlined, because those are the two fields a client cannot guess. `estimate_point_id` appears only when the project has an estimate system configured.
+
+
+
+
+
+The custom properties attached to this type, keyed by property name. Each entry carries the property `id`, its `type`, `name`, `display_name`, `description`, a `required` flag, and an `is_multi` flag.
+
+- `OPTION` properties also carry an `options` array of `{ id, name, logo_props }`, narrowed to the options this type allows.
+- `RELATION` properties also carry a `relation_type`.
+
+Empty when the type has no properties attached, or when custom properties are not available for the workspace.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/?include=members,labels" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"include": "members,labels"},
+)
+schema = response.json()
+
+required = [name for name, field in schema["custom_fields"].items() if field["required"]]
+print(schema["type_name"], "requires:", required)
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ include: "members,labels" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const schema = await response.json();
+
+const required = Object.entries(schema.custom_fields)
+ .filter(([, field]) => field.required)
+ .map(([name]) => name);
+```
+
+
+
+
+
+
+```json
+{
+ "type_id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "type_name": "Bug",
+ "type_description": "Something is broken and needs a fix",
+ "type_logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "fields": {
+ "name": {
+ "type": "string",
+ "required": true,
+ "max_length": 255
+ },
+ "description_html": {
+ "type": "string",
+ "required": false
+ },
+ "priority": {
+ "type": "option",
+ "required": false,
+ "default": "none",
+ "options": [
+ { "value": "urgent", "label": "Urgent" },
+ { "value": "high", "label": "High" },
+ { "value": "medium", "label": "Medium" },
+ { "value": "low", "label": "Low" },
+ { "value": "none", "label": "None" }
+ ]
+ },
+ "state_id": {
+ "type": "uuid",
+ "required": false,
+ "options": [
+ {
+ "id": "2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48",
+ "name": "Backlog",
+ "color": "#8b8d98",
+ "group": "backlog"
+ },
+ {
+ "id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "name": "In Progress",
+ "color": "#3f76ff",
+ "group": "started"
+ },
+ {
+ "id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
+ "name": "Done",
+ "color": "#26a05f",
+ "group": "completed"
+ }
+ ]
+ },
+ "assignee_ids": {
+ "type": "uuid",
+ "is_multi": true,
+ "required": false,
+ "options": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "rin",
+ "email": "rin@my-team.dev"
+ }
+ ]
+ },
+ "label_ids": {
+ "type": "uuid",
+ "is_multi": true,
+ "required": false,
+ "options": [
+ {
+ "id": "5e0c7b93-1a24-4d68-8f31-9b7e2c05a4d7",
+ "name": "regression",
+ "color": "#f5a623"
+ }
+ ]
+ },
+ "start_date": {
+ "type": "date",
+ "required": false,
+ "format": "YYYY-MM-DD"
+ },
+ "target_date": {
+ "type": "date",
+ "required": false,
+ "format": "YYYY-MM-DD"
+ },
+ "parent_id": {
+ "type": "uuid",
+ "required": false
+ }
+ },
+ "custom_fields": {
+ "severity": {
+ "id": "a8b31d67-5e42-4c09-9f78-2d6b41e0c395",
+ "type": "OPTION",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly this breaks the product",
+ "required": true,
+ "is_multi": false,
+ "options": [
+ {
+ "id": "3f8c2a71-6d90-4e15-b243-0c9e7a5b16f8",
+ "name": "S1",
+ "logo_props": {}
+ },
+ {
+ "id": "b47e0d29-8153-4a6c-9e70-2f1d5c83a904",
+ "name": "S2",
+ "logo_props": {}
+ }
+ ]
+ },
+ "found_by": {
+ "id": "c0a95f38-7b1e-4d62-8305-6e4a9b27fd51",
+ "type": "RELATION",
+ "name": "found_by",
+ "display_name": "Found by",
+ "description": "",
+ "required": false,
+ "is_multi": false,
+ "relation_type": "USER",
+ "options": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "rin",
+ "email": "rin@my-team.dev"
+ }
+ ]
+ }
+ }
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Retrieve one work item type by id. Use it to confirm a type still exists and is still active before you write a work item against it, or to refresh a cached name after someone renamed the type in the app.
+
+This returns the type's own attributes only. It does **not** tell you which fields or custom properties a work item of this type accepts — that is [Get a work item type schema](/api-reference/v2/work-item-types/get-work-item-type-schema).
+
+Reads work in either [work item type mode](/api-reference/v2/work-item-type-modes), so this call never needs to branch on how the workspace is configured.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to retrieve.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No work item type matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/import/
+
+
+
+
+
+Make a set of **workspace-level** work item types available inside one project. Import does not create anything: the types already exist on the workspace, and this call adds them to a project's roster so work items there can use them.
+
+This is the workspace-mode way to answer "which types does this project use". Reach for it when a workspace defines `Bug`, `Task`, and `Incident` centrally and a new project should offer `Bug` and `Task` but not `Incident`. List the candidates with [List workspace work item types](/api-reference/v2/workspace-work-item-types/list-workspace-work-item-types), then send the ids you want.
+
+After a successful import, the imported types show up in [List work item types](/api-reference/v2/work-item-types/list-work-item-types) for the project and each one's [schema](/api-reference/v2/work-item-types/get-work-item-type-schema) resolves against this project's states, labels, and members.
+
+::: warning This is the one write here that requires workspace mode
+Every other write in this group requires project mode. Import is the opposite: the types it moves are workspace-owned, so it only makes sense when the workspace manages types at the workspace level.
+
+Calling it while the workspace runs in **project** mode returns `409 work_item_types_managed_at_project` — in that mode a project authors its own types with [Create a work item type](/api-reference/v2/work-item-types/create-work-item-type) and there is nothing to import. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to import the types into.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The ids of the workspace work item types to make available in this project. Send them in one request rather than looping — the import is applied as a batch.
+
+An id that does not resolve to a work item type on this workspace is rejected with `400 invalid_request`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | `work_item_types` missing, or an entry that isn't a UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't configure this project's work item types. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The workspace manages types per project. Create the type in the project instead. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/import/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "work_item_types": [
+ "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240"
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/import/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "work_item_types": [
+ "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ ]
+ },
+)
+print(response.status_code) # 200
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/import/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ work_item_types: ["9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693", "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240"],
+ }),
+ }
+);
+console.log(response.status); // 200
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "Work item types are managed at the project level for this workspace."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/
+
+
+
+
+
+Return the work item types available in a project as a paginated list. This is how you resolve a type name such as `Bug` to the `type_id` you send when creating a work item, and how you build a type picker that stays in sync with the project's configuration.
+
+Reading types is unaffected by [work item type mode](/api-reference/v2/work-item-type-modes). A project in workspace mode still lists the types imported into it here, so a read integration never has to branch on mode.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project whose work item types you want to list.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+Neither `order_by` nor `paginate` is validated — check your spelling, because both fail silently. An unrecognized `order_by` value falls back to the default ordering, and anything other than `paginate=cursor` uses offset pagination. A typo surfaces as an unexpected sort order or envelope, not as an error.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `level` , `-level` — the type hierarchy level
+- `name` , `-name` — alphabetical
+- `created_at` , `-created_at` — when each type was added
+- `id` , `-id`
+
+Order by `level` when you are rendering types to a user; it is the order the project itself uses.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most projects define a handful of types, so one page is usually the whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return on each row. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/?order_by=level&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "level", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "level", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 2,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/mark-default/
+
+
+
+
+
+Promote a type to the project's default — the type new work items get when the request supplies no `type_id`.
+
+**Exactly one type per project is the default.** Marking a new one clears the flag on the type that held it, so promotion is a single request rather than a demote-then-promote pair. There is no way to have zero defaults, and no way to have two.
+
+There is **no request body**. The type is identified by `{pk}` in the path, and the response is the updated type.
+
+`is_default` is deliberately not writable through [create](/api-reference/v2/work-item-types/create-work-item-type) or [update](/api-reference/v2/work-item-types/update-work-item-type). Moving the flag has a side effect on another row, so it gets its own endpoint instead of hiding inside a `PATCH`.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Promote the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to make the default.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. Send the request without a body.
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed as sent. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't update work item types. |
+| `404` | `not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The workspace manages types at the workspace level. Use the workspace surface. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["is_default"]) # True
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_workspace",
+ "detail": "Work item types are managed at the workspace level for this workspace."
+}
+```
+
+
+
+
+
+
+
+## The work item type object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the type. This is the value you send as `type_id` when creating a work item, and the `{type_id}` in the type-properties paths.
+
+- `name` _string_
+
+ Display name, for example `Bug`. Maximum 255 characters.
+
+- `description` _string_
+
+ Free-form explanation of when this type should be used. Worth filling in — an integration or agent reading the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema) sees this text as `type_description` and uses it to choose between types.
+
+- `is_active` _boolean_
+
+ Whether the type can be assigned to new work items. Deactivating a type hides it from pickers without deleting it or touching the work items that already use it.
+
+- `is_default` _boolean_
+
+ Whether new work items land on this type when no `type_id` is supplied. Exactly one type per project holds the flag. It is not writable through create or update — move it with [Mark a work item type as default](/api-reference/v2/work-item-types/mark-default-work-item-type).
+
+- `is_epic` _boolean_
+
+ Whether this is the project's epic type. Read-only — epics are provisioned by Plane, not authored through this endpoint.
+
+- `level` _number_
+
+ Hierarchy level for the type. Read-only, and the value to sort on when you want the order the project itself uses — see [List work item types](/api-reference/v2/work-item-types/list-work-item-types).
+
+- `logo_props` _any_
+
+ The icon and background color rendered next to the type. Generated by Plane when the type is created, so it is read-only here.
+
+- `created_at` _string (date-time)_
+
+ When the type was created.
+
+::: info external_id is write-only
+`external_id` and `external_source` are accepted on create and update as correlation fields for sync and import, but they are **not returned** in the read shape. Neither is `updated_at`. To find a type you previously synced, keep your own mapping from `external_id` to the returned `id`.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Rename a type, rewrite its description, retire it from pickers, or correct its sync correlation fields. Work items already using the type are untouched — you are editing the type, not retyping anything.
+
+`PATCH` is partial. Send only the fields you want to change; anything you omit keeps its current value. Omitting a field is not the same as sending `null`.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Edit the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/update-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to update.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional — send the subset you are changing.
+
+
+
+
+
+New display name for the type. Maximum 255 characters. Renaming is safe: work items reference the type by `type_id`, not by name.
+
+
+
+
+
+What this type is for. It is returned as `type_description` by the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema), so this is the field to edit when integrations are choosing the wrong type.
+
+
+
+
+
+Whether the type can be assigned to new work items. Setting it to `false` retires the type from pickers without deleting it — existing work items keep the type and stay readable. This is the safe alternative to [delete](/api-reference/v2/work-item-types/delete-work-item-type), which a type in use rejects.
+
+
+
+
+
+Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+::: info is_default, is_epic and level are not accepted here
+`is_default` moves through [mark-default](/api-reference/v2/work-item-types/mark-default-work-item-type), which is a dedicated request precisely because promoting one type demotes another. `is_epic` and `level` are read-only, as is `logo_props`.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ---------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | A field over its 255-character limit, or `"is_active": false` on the default type. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't update work item types. |
+| `404` | `not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | Another type in this project already uses this `external_id` and `external_source` pair. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Defect",
+ description: "A verified regression in shipped behavior",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "invalid_request",
+ "code": "invalid_request",
+ "detail": "The default work item type cannot be deactivated.",
+ "errors": []
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/worklogs/
+
+
+
+
+
+Worklogs record time spent on a work item. Create a worklog.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The work item the resource hangs off. Accepts the work item UUID or its `PROJ-123` identifier.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Time logged, in minutes.
+
+
+
+
+
+Free-form description.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `duration`, `id`, `logged_by_id`, `updated_at`, `work_item_id`.
+
+
+
+
+
+Comma-separated relations to embed: `logged_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items.worklogs:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "duration": 90,
+ "description": "What this is for."
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "duration": 90,
+ "description": "What this is for."
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ duration: 90,
+ description: "What this is for.",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/worklogs/{pk}/
+
+
+
+
+
+Worklogs record time spent on a work item. Delete a worklog. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The work item the resource hangs off. Accepts the work item UUID or its `PROJ-123` identifier.
+
+
+
+
+
+The worklog id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `duration`, `id`, `logged_by_id`, `updated_at`, `work_item_id`.
+
+
+
+
+
+Comma-separated relations to embed: `logged_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items.worklogs:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No worklog matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/worklogs/summary/
+
+
+
+
+
+Worklogs record time spent on a work item.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+
+
+
+### Scopes
+
+This endpoint is exempt from fine-grained scope checks.
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/worklogs/summary/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/worklogs/summary/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/worklogs/summary/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+[
+ {
+ "duration": 90,
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+]
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/worklogs/{pk}/
+
+
+
+
+
+Worklogs record time spent on a work item. Read a single worklog by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The work item the resource hangs off. Accepts the work item UUID or its `PROJ-123` identifier.
+
+
+
+
+
+The worklog id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `duration`, `id`, `logged_by_id`, `updated_at`, `work_item_id`.
+
+
+
+
+
+Comma-separated relations to embed: `logged_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items.worklogs:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No worklog matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/worklogs/
+
+
+
+
+
+Worklogs record time spent on a work item. List the worklogs you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The work item the resource hangs off. Accepts the work item UUID or its `PROJ-123` identifier.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `duration__gte`.
+
+
+
+
+
+Filter by `duration__lte`.
+
+
+
+
+
+Filter by `logged_by_id`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `duration`, `id`, `logged_by_id`, `updated_at`, `work_item_id`.
+
+
+
+
+
+Comma-separated relations to embed: `logged_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items.worklogs:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+ {
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The worklog object
+
+### Attributes
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `description` _string_
+
+ Free-form description.
+
+- `duration` _integer_
+
+ Time logged, in minutes.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `logged_by_id` _string (uuid)_
+
+ The related logged by.
+
+- `updated_at` _string (date-time)_
+
+ When the record last changed.
+
+- `work_item_id` _string (uuid)_
+
+ The related work item.
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/worklogs/{pk}/
+
+
+
+
+
+Worklogs record time spent on a work item. Update a worklog. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The work item the resource hangs off. Accepts the work item UUID or its `PROJ-123` identifier.
+
+
+
+
+
+The worklog id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Free-form description.
+
+
+
+
+
+Time logged, in minutes.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `duration`, `id`, `logged_by_id`, `updated_at`, `work_item_id`.
+
+
+
+
+
+Comma-separated relations to embed: `logged_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items.worklogs:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "description": "What this is for.",
+ "duration": 90
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "description": "What this is for.",
+ "duration": 90
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/worklogs/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ description: "What this is for.",
+ duration: 90,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "duration": 90,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "logged_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "work_item_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No worklog matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/archive/
+
+
+
+
+
+Archive a work item: stamp `archived_at` with the current time and take it out of the active work item set.
+
+This is a **bodyless** `POST` — send no JSON at all. The response is the full work item in its usual read shape, with
+`archived_at` now populated, so you can confirm the change without a follow-up read.
+
+Archiving is reversible with [Unarchive a work item](/api-reference/v2/work-items/unarchive-work-item), and it is
+entirely separate from [deleting](/api-reference/v2/work-items/delete-work-item) — an archived work item still exists.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The endpoint takes no request body; anything you send is ignored.
+
+
+
+::: warning Archiving twice returns 404
+Once archived, a work item is outside the default query set, so a second `archive` call on the same work item can't
+resolve it and returns `404 not_found` — not a `409`, and not a silent success. If you're re-running a job,
+treat a `404` here as "already archived" rather than an error worth retrying.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't archive this work item. |
+| `404` | `not_found` | No such work item, it's outside your project or tenant, or it is already archived. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The write collides with a protected-resource constraint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["archived_at"])
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/",
+ {
+ method: "POST",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": "2026-02-03T11:47:19.204518Z",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "Severity": {
+ "id": "5e2a7c81-4f39-4b60-a1d8-0c6b3e9f2d74",
+ "value": ["Sev-2"],
+ "value_detail": [{ "id": "c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03", "name": "Sev-2" }]
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/bulk/
+
+
+
+
+
+Work items are the issues, tasks and epics in a project. Write up to 100 work items in one request, with a per-row result for each.
+
+- Send `{"items": [...]}`, at most 100 per request. Add `"upsert": true` to match existing rows on `(external_source, external_id)` instead of always creating.
+- The response is always `200`. Each row reports its own outcome, so a partial failure is reported rather than silently dropped — read `succeeded`/`failed` and the per-row `status`.
+- Rows are written on independent savepoints: a failing row rolls back only itself.
+- `?fields=` does not apply here — the bulk response is a per-row result envelope, not a resource body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The items.
+
+
+
+
+
+Reconcile each row on (external_source, external_id) instead of creating it.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/bulk/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "items": [
+ {
+ "assignee_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "assignees": [
+ "ana@example.com"
+ ],
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description_html": "Details go here.
",
+ "estimate": "example",
+ "estimate_point_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "external_id": null,
+ "external_source": null,
+ "label_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "labels": [
+ "example"
+ ],
+ "module_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "name": "Example name",
+ "parent": "example",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "priority": "high",
+ "start_date": "2026-01-12",
+ "state": "example",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_date": "2026-01-20",
+ "type": "example",
+ "type_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "upsert": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/bulk/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "items": [
+ {
+ "assignee_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "assignees": [
+ "ana@example.com"
+ ],
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description_html": "Details go here.
",
+ "estimate": "example",
+ "estimate_point_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "external_id": None,
+ "external_source": None,
+ "label_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "labels": [
+ "example"
+ ],
+ "module_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "name": "Example name",
+ "parent": "example",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "priority": "high",
+ "start_date": "2026-01-12",
+ "state": "example",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_date": "2026-01-20",
+ "type": "example",
+ "type_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "upsert": False
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/bulk/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ items: [
+ {
+ assignee_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ assignees: ["ana@example.com"],
+ cycle_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ description_html: "Details go here.
",
+ estimate: "example",
+ estimate_point_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ external_id: null,
+ external_source: null,
+ label_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ labels: ["example"],
+ module_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ name: "Example name",
+ parent: "example",
+ parent_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ priority: "high",
+ start_date: "2026-01-12",
+ state: "example",
+ state_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ target_date: "2026-01-20",
+ type: "example",
+ type_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ },
+ ],
+ upsert: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "failed": 1,
+ "results": [null],
+ "succeeded": 1
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/
+
+
+
+
+
+Create a work item in a project. Only `name` is required — everything else falls back to the project's defaults, so the
+smallest useful create is one field.
+
+Each relation accepts either its id field or a **write-only human-readable parallel**: `state` instead of `state_id`,
+`assignees` (emails) instead of `assignee_ids`, `labels` (names) instead of `label_ids`, and so on. Send one or the
+other, never both. This is what lets an importer or an agent write a fully-populated work item without first resolving
+six UUIDs.
+
+The response is the standard sparse read shape, with `custom_fields` populated.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to create the work item in.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Title of the work item. Maximum 255 characters. The only required field.
+
+
+
+
+
+Rich-text body as HTML, for example `Steps to reproduce…
`. The HTML is sanitized on the way in; content that
+can't be sanitized is rejected with a `400`.
+
+`description_html` is **not** part of the read shape, so it will not appear in the response.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`. Defaults to `none`.
+
+
+
+
+
+The workflow state to create the work item in. Must be a state of this project. Omit it and the work item lands in the
+project's default state.
+
+
+
+
+
+The state's **name** instead of its id, for example `In Progress`. Matched case-insensitively within the project.
+Write-only.
+
+Unknown name or a name that matches more than one state is a `400`. Sending both `state` and `state_id` is a `400`.
+
+
+
+
+
+The work item type. Accepts a type owned by the project and a workspace-level type imported into it. Requires work item
+types to be enabled.
+
+
+
+
+
+The type's **name** instead of its id, for example `Bug`. Matched case-insensitively among the project's non-epic
+types. Write-only.
+
+
+
+
+
+The parent work item. The parent must be in the same workspace, but it may live in a different project.
+
+
+
+
+
+The parent's **identifier** instead of its id, for example `PROJ-118`. Resolved within the workspace. Write-only.
+
+
+
+
+
+User ids to assign. Each must be an active, assignable member of the project.
+
+Leave it out and the project's default assignee is applied, if one is configured. Send `[]` to create the work item
+with no assignee at all.
+
+
+
+
+
+Member **email addresses** instead of ids, for example `["ana@example.com"]`. Every address must belong to an active,
+assignable project member — any that don't are named in the `400`. Write-only.
+
+
+
+
+
+Label ids to apply. Each must be a label of this project, or a workspace-level label available to it.
+
+
+
+
+
+Label **names** instead of ids, for example `["regression", "auth"]`. Matched case-insensitively against the project's
+labels and the workspace-level labels available to it. A name that exists at both levels is ambiguous and returns a
+`400` telling you to use `label_ids`. Write-only.
+
+
+
+
+
+The estimate point to assign, from the project's active estimate system.
+
+
+
+
+
+The estimate point's **value** instead of its id, for example `5` or `L`. Resolved against the project's active
+estimate. Write-only.
+
+
+
+
+
+Planned start, for example `2026-01-12`. Must not be after `target_date`.
+
+
+
+
+
+Planned due date, for example `2026-01-20`.
+
+
+
+
+
+Your system's identifier for this work item, for sync and import correlation. Maximum 255 characters.
+
+Stored and filterable on [List work items](/api-reference/v2/work-items/list-work-items), but not returned on reads.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+
+::: info Setting custom property values
+Work item type custom properties are written through a separate `custom_fields` object on the request body, keyed by
+property name, and are validated against the type you selected. Its shape depends on the type you chose, so it is not
+declared in the OpenAPI schema — read it from
+[the type's schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema). It requires custom
+properties to be enabled for the workspace — sending it otherwise is a `400`. Properties you omit are filled from the
+type's defaults. See [work item properties](/api-reference/v2/work-item-properties/list-work-item-properties).
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | Missing `name`; a bad `priority`; `start_date` after `target_date`; an unresolvable or ambiguous `state`/`type`/`parent`/`assignees`/`labels`/`estimate`; both a name and its `*_id`; or an id from another project or workspace. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | A workflow rule forbids creating a work item in the requested state. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The write collides with a uniqueness or protected-resource constraint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Fix login redirect loop",
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "target_date": "2026-01-20"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Fix login redirect loop",
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "target_date": "2026-01-20",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Fix login redirect loop",
+ priority: "high",
+ state_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ assignee_ids: ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ target_date: "2026-01-20",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": null,
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": [],
+ "parent_id": null,
+ "start_date": null,
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {}
+}
+```
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Fix login redirect loop",
+ "state": "In Progress",
+ "type": "Bug",
+ "parent": "PROJ-118",
+ "assignees": ["ana@example.com"],
+ "labels": ["regression", "auth"],
+ "estimate": "5"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Fix login redirect loop",
+ "state": "In Progress",
+ "type": "Bug",
+ "parent": "PROJ-118",
+ "assignees": ["ana@example.com"],
+ "labels": ["regression", "auth"],
+ "estimate": "5",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Fix login redirect loop",
+ state: "In Progress",
+ type: "Bug",
+ parent: "PROJ-118",
+ assignees: ["ana@example.com"],
+ labels: ["regression", "auth"],
+ estimate: "5",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "type": "invalid_request",
+ "code": "invalid_request",
+ "detail": "The request body failed validation.",
+ "errors": [
+ {
+ "field": "state",
+ "code": "invalid",
+ "message": "No state named 'In Reviewing' in this project."
+ }
+ ]
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Delete a work item. The delete is a soft delete — the row is retained internally — but it is gone from every API
+surface, and there is no endpoint to bring it back.
+
+A successful delete returns `204` with an empty body. Deleting a work item that is already gone returns `404`, so the
+call is not idempotent from the client's point of view.
+
+If you want the work item out of the way but recoverable, use
+[Archive a work item](/api-reference/v2/work-items/archive-work-item) instead.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+::: warning Deleting is not reversible through the API
+There is no undelete endpoint. Confirm with the user before wiring this into an automation, and prefer archiving for
+anything you might want back.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't delete this work item. |
+| `404` | `not_found` | No such work item, or it's outside your project or tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The delete collides with a protected-resource constraint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+No content.
+```
+
+
+
+
+
+```json
+{
+ "type": "forbidden",
+ "code": "forbidden",
+ "detail": "You do not have permission to delete this work item."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-items/{identifier}/
+
+
+
+
+
+Retrieve a work item by its human key — `PROJ-142` — anywhere in the workspace.
+
+This route exists for callers that **don't know the project UUID**. A `PROJ-142` in a commit message, a chat command, a
+support ticket, or an LLM prompt carries no project id, and making the caller first list projects, find the one whose
+identifier is `PROJ`, and then call the project-scoped route would be three requests to answer one question. Here it is
+one request against the workspace.
+
+The route is read-only. Creates, updates, deletes, and archiving all go through the project-scoped UUID routes.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The work item's human key: the project identifier, a hyphen, and the work item's number — `PROJ-142`.
+
+The project part must start with a letter, and it is upper-cased before lookup, so `proj-142` resolves the same work
+item as `PROJ-142`. A project identifier is unique within a workspace, which is what makes this key unambiguous.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+::: info Everything unresolvable is a 404
+A malformed key (`PROJ_142`, `142`, `-142`), a key from a project you can't see, a key in another workspace, and a key
+that resolves to nothing all return the same `404`. That is deliberate: the response never reveals whether a work item
+exists, only whether _you_ can read it. Archived work items are not served from this route either.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | --------------------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your token scope can't read work items. |
+| `404` | `not_found` | Malformed identifier, no such work item, it's outside your tenant or visibility, or archived. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/", {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Retrieve one work item by its UUID. This is the endpoint to use after a list call, or any time you already hold the
+work item's `id`.
+
+Unlike the list endpoint, this response populates `custom_fields` — the work item type's custom property values, keyed
+by property name. If you only have a `PROJ-142`-style key and not the project UUID, use
+[Get a work item by identifier](/api-reference/v2/work-items/get-work-item-by-identifier) instead.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+::: warning Archived work items are not returned
+An archived work item sits outside the default query set, so a read of one returns `404` — the same response as a work
+item that never existed. [Unarchive](/api-reference/v2/work-items/unarchive-work-item) it first if you need to read it
+again. See [Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read work items in this project. |
+| `404` | `not_found` | No such work item, it belongs to another project or tenant, or it's archived. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {},
+ "state": {
+ "id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "name": "In Progress",
+ "color": "#3f76ff",
+ "group": "started"
+ },
+ "assignees": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "ana",
+ "avatar_url": "https://assets.plane.so/avatars/ana.png",
+ "email": "ana@example.com"
+ }
+ ]
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/
+
+
+
+
+
+List the work items in a project. This is the endpoint you build reports, syncs, and board views on: it takes a wide
+set of filters, orders by stored columns or by meaning, and paginates by offset or by cursor.
+
+Results are always scoped to the project in the path and to what your token is allowed to see. Filters can only narrow
+that set — they never widen it.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to list work items from.
+
+
+
+
+
+
+
+
+### Filters
+
+Every filter is optional, and filters combine with AND. Each concept below has a base parameter plus the `__in` and
+`__isnull` variants noted in its description.
+
+
+
+
+
+Match work items in a specific state. Use `state_id__in` with a comma-separated list to match any of several states.
+
+
+
+
+
+Match by the state's workflow group instead of a specific state — stable across projects that name their states
+differently. One of `backlog`, `unstarted`, `started`, `completed`, `cancelled`, `triage`.
+
+Use `state_group__in` for several groups, for example `?state_group__in=started,completed`.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`. Use `priority__in` for several, for example
+`?priority__in=urgent,high`.
+
+
+
+
+
+Match work items assigned to a user. `assignee_id__in` matches any of several users; `assignee_id__isnull=true`
+returns only unassigned work items.
+
+
+
+
+
+Match work items carrying a label. `label_id__in` matches any of several labels; `label_id__isnull=true` returns only
+unlabeled work items.
+
+
+
+
+
+Match work items of a given work item type. `type_id__in` accepts a comma-separated list.
+
+
+
+
+
+Match the children of a work item. `parent_id__in` accepts several parents; `parent_id__isnull=true` returns only
+top-level work items.
+
+
+
+
+
+Match work items in a cycle. `cycle_id__in` accepts several cycles; `cycle_id__isnull=true` returns the backlog of
+work items in no cycle at all.
+
+
+
+
+
+Match work items in a module. `module_id__in` accepts several modules; `module_id__isnull=true` returns work items in
+no module.
+
+
+
+
+
+Match the single work item with this number within the project — the `142` of `PROJ-142`.
+
+
+
+
+
+Filter drafts in or out. Drafts are work items still being composed in the Plane app.
+
+
+
+
+
+Correlation filters for sync and import. `external_source` is the system a record came from and `external_id` is its
+key there, so the pair is how you find the Plane work item that mirrors a row in your own database.
+
+These values are not returned on reads — the lookup is one-way.
+
+
+
+
+
+Bound the creation timestamp. Pass an ISO 8601 datetime, for example `2026-01-01T00:00:00Z`. Use both for a window.
+
+
+
+
+
+Bound the last-modified timestamp. This is the pair to use for incremental sync — poll with
+`?updated_at__gte=&order_by=updated_at`.
+
+`updated_at` is filterable and orderable but is not part of the read shape, so it does not come back in the response
+body.
+
+
+
+
+
+Bound the planned start date, for example `2026-01-01`.
+
+
+
+
+
+Bound the planned due date. `?target_date__lte=2026-01-31&state_group__in=backlog,unstarted,started` is the "what is
+about to slip" query.
+
+
+
+
+
+
+
+
+### Search and ordering
+
+
+
+
+
+Free-text search over the work item name.
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending. Defaults to `-created_at`.
+
+- `created_at`, `-created_at`
+- `updated_at`, `-updated_at`
+- `sequence_id`, `-sequence_id`
+- `id`, `-id`
+- `sort_order`, `-sort_order` — the manual board ordering
+- `priority`, `-priority` — semantic: `urgent` → `high` → `medium` → `low` → `none`, not alphabetical
+- `state_group`, `-state_group` — semantic: workflow order, not alphabetical
+
+`priority` and `state_group` sort by meaning, which is what you want for a board but is not cursor-eligible. Pair
+either with `?paginate=cursor` and you get `400 ordering_not_cursor_eligible`; use the default offset pages instead.
+
+
+
+
+
+
+
+
+### Pagination
+
+Offset is the default. Cursor is opt-in per request.
+
+
+
+
+
+Page size. Defaults to 50, maximum 200.
+
+
+
+
+
+Rows to skip from the start of the result set. Maximum 10000 — past that, switch to cursor pagination.
+
+
+
+
+
+Defaults to `true`. Pass `?count=false` to skip the `COUNT(*)` and omit `total_count` from the envelope. Worth doing on
+large projects when you only need the rows.
+
+
+
+
+
+Set to `cursor` to opt into keyset pagination. The envelope changes to `next_cursor` / `has_more` and drops
+`total_count`. Use it for deep or long-running traversals where offset pages would drift as rows are inserted. Follow
+the returned `next_cursor` as described in [Pagination](/api-reference/v2/pagination).
+
+
+
+
+
+
+
+
+### Expansion
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+::: warning Bad filter values fail loudly, bad `order_by` does not
+The enum-backed _filters_ (`priority`, `priority__in`, `state_group`, `state_group__in`) are validated against their
+allowed values. A typo returns `400 invalid_request` naming the parameter — it does not silently return an empty page.
+Treat an empty `data` array as a genuine "no matches".
+
+`order_by` and `paginate` are the exception: neither is validated. An unrecognized `order_by` silently falls back to the
+default ordering, and anything other than `paginate=cursor` silently uses offset pagination — so check your spelling
+there, because a typo shows up as an unexpected sort order or envelope rather than an error.
+:::
+
+::: info Archived work items are excluded
+The list returns active work items only — anything with `archived_at` set is filtered out, so archiving a work item
+takes it off every page of this list. See [Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return on each row. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+Naming `custom_fields` here is a `400` — it is only available on single-object responses.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read work items in this project. |
+| `404` | `not_found` | No such workspace or project, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/?state_group__in=started,unstarted&priority=high&per_page=50&order_by=-created_at" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={
+ "state_group__in": "started,unstarted",
+ "priority": "high",
+ "per_page": 50,
+ "order_by": "-created_at",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({
+ state_group__in: "started,unstarted",
+ priority: "high",
+ per_page: "50",
+ order_by: "-created_at",
+});
+
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/?${params}`,
+ {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ },
+ {
+ "id": "3b7d9e40-1c62-4a85-b0f3-9d5c2e6a8471",
+ "name": "Rate limit the invite endpoint",
+ "identifier": "PROJ-141",
+ "sequence_id": 141,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": null,
+ "assignee_ids": [],
+ "label_ids": [],
+ "parent_id": "a7e51d24-3b98-4c6d-9f10-7d2c8e4b5a61",
+ "start_date": null,
+ "target_date": null,
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ }
+ ],
+ "next": 50,
+ "previous": null,
+ "total_count": 327,
+ "pagination": { "style": "offset" }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ }
+ ],
+ "next_cursor": "b3A9MTcxJmxpbWl0PTUw",
+ "has_more": true,
+ "pagination": { "style": "cursor" }
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-items/
+
+
+
+
+
+Work items are the issues, tasks and epics in a project. List the workspace work items you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Filter by `assignee_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `assignee_id__isnull`.
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `created_at__gte`.
+
+
+
+
+
+Filter by `created_at__lte`.
+
+
+
+
+
+Filter by `cycle_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `cycle_id__isnull`.
+
+
+
+
+
+Filter by `external_id`.
+
+
+
+
+
+Filter by `external_source`.
+
+
+
+
+
+Filter by `is_draft`.
+
+
+
+
+
+Filter by `label_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `label_id__isnull`.
+
+
+
+
+
+Filter by `module_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `module_id__isnull`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Filter by `parent_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `parent_id__isnull`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+- `urgent` - Urgent
+- `high` - High
+- `medium` - Medium
+- `low` - Low
+- `none` - None
+
+One of `high`, `low`, `medium`, `none`, `urgent`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+- `urgent` - Urgent
+- `high` - High
+- `medium` - Medium
+- `low` - Low
+- `none` - None
+
+
+
+
+
+Filter by `project_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+A search term.
+
+
+
+
+
+Filter by `sequence_id`.
+
+
+
+
+
+Filter by `start_date__gte`.
+
+
+
+
+
+Filter by `start_date__lte`.
+
+
+
+
+
+- `backlog` - Backlog
+- `unstarted` - Unstarted
+- `started` - Started
+- `completed` - Completed
+- `cancelled` - Cancelled
+- `triage` - Triage
+
+One of `backlog`, `cancelled`, `completed`, `started`, `triage`, `unstarted`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+- `backlog` - Backlog
+- `unstarted` - Unstarted
+- `started` - Started
+- `completed` - Completed
+- `cancelled` - Cancelled
+- `triage` - Triage
+
+
+
+
+
+Filter by `state_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `target_date__gte`.
+
+
+
+
+
+Filter by `target_date__lte`.
+
+
+
+
+
+Filter by `type_id`.
+
+
+
+
+
+Multiple values may be separated by commas.
+
+
+
+
+
+Filter by `updated_at__gte`.
+
+
+
+
+
+Filter by `updated_at__lte`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+
+
+
+
+Comma-separated relations to embed: `assignees`, `cycle`, `labels`, `modules`, `parent`, `state`, `type`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-items/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "archived_at": null,
+ "assignee_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {},
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "identifier": "PROJ",
+ "is_draft": false,
+ "label_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "module_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "name": "Example name",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "priority": "high",
+ "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
+ "sequence_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "start_date": "2026-01-12",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_date": "2026-01-20",
+ "type_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The work item object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the work item. This is the `{pk}` on every project-scoped detail route.
+
+- `name` _string_
+
+ Title of the work item. Maximum 255 characters.
+
+- `identifier` _string_
+
+ The human key, for example `PROJ-142`. It is the project's identifier joined to `sequence_id`, and it is what people
+ paste into chat and commit messages. Use it with
+ [Get a work item by identifier](/api-reference/v2/work-items/get-work-item-by-identifier) when you don't have the
+ project UUID.
+
+- `sequence_id` _integer_
+
+ The work item's number within its project. Assigned by Plane and never reused.
+
+- `priority` _string_
+
+ One of `urgent`, `high`, `medium`, `low`, or `none`. Never null — an unprioritized work item reads `none`.
+
+- `state_id` _string (uuid)_
+
+ The workflow state the work item is currently in.
+
+- `type_id` _string (uuid)_
+
+ The work item type. `null` when the project has no types enabled or the item is untyped.
+
+- `assignee_ids` _array of string_
+
+ User ids assigned to the work item. Empty array when unassigned.
+
+- `label_ids` _array of string_
+
+ Label ids applied to the work item. Empty array when unlabeled.
+
+- `parent_id` _string (uuid)_
+
+ The parent work item, or `null` for a top-level item. A parent may live in another project of the same workspace.
+
+- `start_date` _string (date)_
+
+ Planned start, or `null`.
+
+- `target_date` _string (date)_
+
+ Planned due date, or `null`.
+
+- `is_draft` _boolean_
+
+ Whether the work item is still a draft. Drafts are created in the Plane app and are excluded from most boards.
+
+- `archived_at` _string (date-time)_
+
+ When the work item was archived, or `null` if it is active. See [Archiving](#archiving-and-deleting).
+
+- `created_at` _string (date-time)_
+
+ When the work item was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the work item. `null` for items created by an automation with no acting user.
+
+- `custom_fields` _object_
+
+ Values of the work item type's custom properties, keyed by property name. **Populated only on single-item
+ responses** — it is always `null` on the list endpoint. See [Custom fields](#custom-fields).
+
+::: info The read shape is sparse and fixed
+`description_html`, `external_id`, `external_source`, and `estimate_point_id` are accepted on writes but are **not**
+part of the read shape — they will not come back on any response. There is also no `updated_at`, no `project_id`, and
+no `workspace_id`: you already know the project from the path.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ },
+ "root_cause": {
+ "id": "9e3b6c21-7f45-4d80-a1e9-5c8b2d7f4a36",
+ "value": "Stale session cookie",
+ "value_detail": null
+ }
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/unarchive/
+
+
+
+
+
+Restore an archived work item: clear `archived_at` and put it back into the active set, where it shows up in lists and
+plain detail reads again.
+
+This is a **bodyless** `POST` — send no JSON at all. The response is the full work item in its usual read shape with
+`archived_at` back to `null`.
+
+Unlike most detail routes, this one deliberately looks past the archive filter to find the work item — that is the
+whole point. It also means the call is safe to repeat: unarchiving a work item that isn't archived succeeds and changes
+nothing.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The endpoint takes no request body; anything you send is ignored.
+
+
+
+::: tip Safe to retry
+Unarchive resolves archived and active work items alike, so a repeat call is a no-op that returns `200` with
+`archived_at: null`. Archive is the asymmetric one — see
+[Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't archive or unarchive this work item. |
+| `404` | `not_found` | No such work item, or it's outside your project or tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The write collides with a protected-resource constraint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["archived_at"]) # None
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/",
+ {
+ method: "POST",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "Severity": {
+ "id": "5e2a7c81-4f39-4b60-a1d8-0c6b3e9f2d74",
+ "value": ["Sev-2"],
+ "value_detail": [{ "id": "c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03", "name": "Sev-2" }]
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Update a work item. Every field is optional and the update is partial — send only what changes, and everything you
+leave out stays exactly as it was.
+
+Omitting a field is not the same as sending `null`. Omit `target_date` and the existing due date is preserved; send
+`"target_date": null` and it is cleared.
+
+There is no `PUT` in v2. A `PUT` to this path returns `405 method_not_allowed`.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+New title. Maximum 255 characters.
+
+
+
+
+
+Replacement rich-text body as HTML. Sanitized on the way in; content that can't be sanitized is rejected with a `400`.
+Not part of the read shape, so it won't appear in the response.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`.
+
+
+
+
+
+Move the work item to another state of the same project. This is the field workflow rules police — see
+[Workflow rules](#workflow-rules-can-reject-a-transition).
+
+
+
+
+
+The target state's **name** instead of its id, for example `Done`. Matched case-insensitively within the project.
+Write-only. Sending both `state` and `state_id` is a `400`.
+
+
+
+
+
+Change the work item type. Send `null` to make the work item untyped.
+
+
+
+
+
+The type's **name** instead of its id, for example `Bug`. Write-only.
+
+
+
+
+
+Re-parent the work item. The parent must be in the same workspace and may be in a different project. Send `null` to
+detach it and make it top-level.
+
+
+
+
+
+The parent's **identifier** instead of its id, for example `PROJ-118`. Write-only.
+
+
+
+
+
+**Replaces** the whole assignee set — it is not additive. Send the complete list you want, `[]` to unassign everyone,
+or omit the field to leave assignees untouched.
+
+
+
+
+
+Member **email addresses** instead of ids. Same replace-the-set semantics. Every address must belong to an active,
+assignable project member. Write-only.
+
+
+
+
+
+**Replaces** the whole label set. Send `[]` to strip all labels, or omit the field to leave them untouched.
+
+
+
+
+
+Label **names** instead of ids. Same replace-the-set semantics. A name that exists at both project and workspace level
+is ambiguous and returns a `400` telling you to use `label_ids`. Write-only.
+
+
+
+
+
+Change the estimate point, from the project's active estimate system. Send `null` to clear the estimate.
+
+
+
+
+
+The estimate point's **value** instead of its id, for example `5`. Write-only.
+
+
+
+
+
+Planned start, or `null` to clear it. Must not be after `target_date`.
+
+
+
+
+
+Planned due date, or `null` to clear it.
+
+
+
+
+
+Your system's identifier for this work item. Maximum 255 characters. Filterable on
+[List work items](/api-reference/v2/work-items/list-work-items), but not returned on reads.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+
+::: info Fields you cannot patch
+`id`, `identifier`, `sequence_id`, `is_draft`, `archived_at`, `created_at`, and `created_by_id` are read-only — sending
+them has no effect. In particular, archiving is not a `PATCH` on `archived_at`; use
+[Archive a work item](/api-reference/v2/work-items/archive-work-item).
+
+Custom property values go through a separate `custom_fields` object on the request body, keyed by property name — its
+shape follows the work item's type, so it is not declared in the OpenAPI schema. See
+[the type's schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema). On a `PATCH` only the
+properties you submit are replaced; untouched properties keep their values and are never required-checked.
+:::
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `assignees` (the assigned users), `cycle` (the cycle it belongs to), `labels` (the applied labels), `modules` (the modules it belongs to), `parent` (its parent work item), `state` (the work item's state object), `type` (its work item type).
+
+Expansion is separate-key: `?expand=state` keeps `state_id` and adds a `state` object next to it, so an id is never replaced by an object. An unknown value is a `400`.
+
+`?fields=` and `?expand=` are independent namespaces. Relation names are not valid `?fields=` tokens (and vice versa), and an expanded object survives field filtering — `?fields=id,name&expand=state` returns `id`, `name` and `state`. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | A bad `priority`; `start_date` after `target_date`; an unresolvable or ambiguous `state`/`type`/`parent`/`assignees`/`labels`/`estimate`; both a name and its `*_id`; or an id from another project or workspace. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | A workflow rule forbids the requested state transition. |
+| `404` | `not_found` | No such work item, or it's outside your project or tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The write collides with a uniqueness or protected-resource constraint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "priority": "urgent",
+ "state": "In Review",
+ "assignees": ["ana@example.com", "rk@example.com"],
+ "target_date": null
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "priority": "urgent",
+ "state": "In Review",
+ "assignees": ["ana@example.com", "rk@example.com"],
+ "target_date": None,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ priority: "urgent",
+ state: "In Review",
+ assignees: ["ana@example.com", "rk@example.com"],
+ target_date: null,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "urgent",
+ "state_id": "5d2a91b7-64c0-4f38-b9e2-0a3f7c6d8149",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430", "9b7f4c53-2d18-4a6e-8c05-1f3e7d9a2b64"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": null,
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "forbidden",
+ "code": "workflow_transition_denied",
+ "detail": "State transition is not allowed."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/upsert/
+
+
+
+
+
+Work items are the issues, tasks and epics in a project. Create a work item, or update the existing one that carries the same `(external_source, external_id)` pair.
+
+- Both `external_source` and `external_id` are required — without them there is nothing to match on and the request is a `400`.
+- A created record answers `201` with `X-Plane-Upsert: created`; an updated one answers `200` with `X-Plane-Upsert: updated`. Branch on the header rather than guessing from the status.
+- Upsert is safe for **sequential** importers. Two simultaneous upserts of the same key can each miss and each create, so serialize your writes per key.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+Ids of the assignees to associate. Replaces the current set.
+
+
+
+
+
+The assignees.
+
+
+
+
+
+Id of the related cycle.
+
+Nullable.
+
+
+
+
+
+Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+Nullable.
+
+
+
+
+
+The estimate.
+
+Nullable.
+
+
+
+
+
+Id of the related estimate point.
+
+Nullable.
+
+
+
+
+
+Your system's identifier for this record, for sync and import correlation.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+Ids of the labels to associate. Replaces the current set.
+
+
+
+
+
+The labels.
+
+
+
+
+
+Ids of the modules to associate. Replaces the current set.
+
+
+
+
+
+The parent.
+
+Nullable.
+
+
+
+
+
+Id of the related parent.
+
+Nullable.
+
+
+
+
+
+- `none` - None
+- `low` - Low
+- `medium` - Medium
+- `high` - High
+- `urgent` - Urgent
+
+One of `none`, `low`, `medium`, `high`, `urgent`.
+
+
+
+
+
+Planned start date, as `YYYY-MM-DD`.
+
+Nullable.
+
+
+
+
+
+The state.
+
+Nullable.
+
+
+
+
+
+Id of the related state.
+
+Nullable.
+
+
+
+
+
+Planned due date, as `YYYY-MM-DD`.
+
+Nullable.
+
+
+
+
+
+The type.
+
+Nullable.
+
+
+
+
+
+Id of the related type.
+
+Nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `archived_at`, `assignee_ids`, `created_at`, `created_by_id`, `custom_fields`, `cycle_id`, `id`, `identifier`, `is_draft`, `label_ids`, `module_ids`, `name`, `parent_id`, `priority`, `project_id`, `sequence_id`, `start_date`, `state_id`, `target_date`, `type_id`.
+
+
+
+
+
+Comma-separated relations to embed: `assignees`, `cycle`, `labels`, `modules`, `parent`, `state`, `type`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "assignee_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "assignees": [
+ "ana@example.com"
+ ],
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "assignee_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "assignees": [
+ "ana@example.com"
+ ],
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ assignee_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ assignees: ["ana@example.com"],
+ cycle_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "archived_at": null,
+ "assignee_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {},
+ "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "identifier": "PROJ",
+ "is_draft": false,
+ "label_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "module_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "name": "Example name",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "priority": "high",
+ "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
+ "sequence_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "start_date": "2026-01-12",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_date": "2026-01-20",
+ "type_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/
+
+
+
+
+
+Workflow states are the states attached to a project workflow. Create a workflow state.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Whether allow issue creation.
+
+
+
+
+
+Make this the default for its parent. Setting it clears the flag on the previous default.
+
+
+
+
+
+The type.
+
+Maximum 255 characters.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `allow_issue_creation`, `created_at`, `created_by_id`, `id`, `is_default`, `state_id`, `type`, `workflow_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "allow_issue_creation": false,
+ "is_default": false,
+ "type": "example"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "allow_issue_creation": False,
+ "is_default": False,
+ "type": "example"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ allow_issue_creation: false,
+ is_default: false,
+ type: "example",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "allow_issue_creation": false,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/
+
+
+
+
+
+Workflow states are the states attached to a project workflow. Delete a workflow state. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow state id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `allow_issue_creation`, `created_at`, `created_by_id`, `id`, `is_default`, `state_id`, `type`, `workflow_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow state matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/
+
+
+
+
+
+Workflow states are the states attached to a project workflow. Read a single workflow state by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow state id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `allow_issue_creation`, `created_at`, `created_by_id`, `id`, `is_default`, `state_id`, `type`, `workflow_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "allow_issue_creation": false,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow state matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/
+
+
+
+
+
+Workflow states are the states attached to a project workflow. List the workflow states you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `allow_issue_creation`, `created_at`, `created_by_id`, `id`, `is_default`, `state_id`, `type`, `workflow_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "allow_issue_creation": false,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+ {
+ "allow_issue_creation": false,
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workflow state object
+
+### Attributes
+
+- `allow_issue_creation` _boolean_
+
+ Whether allow issue creation.
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_default` _boolean_
+
+ Make this the default for its parent. Setting it clears the flag on the previous default.
+
+- `state_id` _string (uuid)_
+
+ The related state.
+
+- `type` _string_
+
+ The type.
+
+- `workflow_id` _string (uuid)_
+
+ The related workflow.
+
+
+
+
+
+
+```json
+{
+ "allow_issue_creation": false,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/
+
+
+
+
+
+Workflow states are the states attached to a project workflow. Update a workflow state. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow state id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Whether allow issue creation.
+
+
+
+
+
+Make this the default for its parent. Setting it clears the flag on the previous default.
+
+
+
+
+
+The type.
+
+Maximum 255 characters.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `allow_issue_creation`, `created_at`, `created_by_id`, `id`, `is_default`, `state_id`, `type`, `workflow_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "allow_issue_creation": false,
+ "is_default": false,
+ "type": "example"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "allow_issue_creation": False,
+ "is_default": False,
+ "type": "example"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/states/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ allow_issue_creation: false,
+ is_default: false,
+ type: "example",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "allow_issue_creation": false,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_default": false,
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type": "example",
+ "workflow_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow state matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/
+
+
+
+
+
+Workflow transitions define the legal moves between workflow states, and who may approve them. Create a workflow transition.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Ids of the members to associate. Replaces the current set.
+
+
+
+
+
+Id of the related rejection state.
+
+Nullable.
+
+
+
+
+
+How many approvals a transition needs before it may run.
+
+Nullable.
+
+
+
+
+
+Id of the related state.
+
+
+
+
+
+Id of the related transition state.
+
+Nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `id`, `member_ids`, `rejection_state_id`, `required_approvals`, `transition_state_id`, `workflow_state_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "member_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "member_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ member_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ rejection_state_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ required_approvals: 1,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/
+
+
+
+
+
+Workflow transitions define the legal moves between workflow states, and who may approve them. Delete a workflow transition. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow transition id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `id`, `member_ids`, `rejection_state_id`, `required_approvals`, `transition_state_id`, `workflow_state_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow transition matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/
+
+
+
+
+
+Workflow transitions define the legal moves between workflow states, and who may approve them. Read a single workflow transition by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow transition id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `id`, `member_ids`, `rejection_state_id`, `required_approvals`, `transition_state_id`, `workflow_state_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow transition matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/
+
+
+
+
+
+Workflow transitions define the legal moves between workflow states, and who may approve them. List the workflow transitions you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `id`, `member_ids`, `rejection_state_id`, `required_approvals`, `transition_state_id`, `workflow_state_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+ {
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workflow transition object
+
+### Attributes
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `member_ids` _array of string_
+
+ Ids of the associated members.
+
+- `rejection_state_id` _string (uuid)_
+
+ The related rejection state.
+
+- `required_approvals` _integer_
+
+ How many approvals a transition needs before it may run.
+
+- `transition_state_id` _string (uuid)_
+
+ The related transition state.
+
+- `workflow_state_id` _string (uuid)_
+
+ The related workflow state.
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/
+
+
+
+
+
+Workflow transitions define the legal moves between workflow states, and who may approve them. Update a workflow transition. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow the resource belongs to.
+
+
+
+
+
+The workflow transition id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Ids of the members to associate. Replaces the current set.
+
+
+
+
+
+Id of the related rejection state.
+
+Nullable.
+
+
+
+
+
+How many approvals a transition needs before it may run.
+
+Nullable.
+
+
+
+
+
+Id of the related state.
+
+
+
+
+
+Id of the related transition state.
+
+Nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `id`, `member_ids`, `rejection_state_id`, `required_approvals`, `transition_state_id`, `workflow_state_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "member_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "member_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/state-transitions/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ member_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ rejection_state_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ required_approvals: 1,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "member_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "required_approvals": 1,
+ "transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "workflow_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow transition matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/
+
+
+
+
+
+Workflows constrain how work items move between states in a project. Create a workflow.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+Free-form description.
+
+Nullable.
+
+
+
+
+
+Whether the record is active.
+
+
+
+
+
+Ids of the work item types to associate. Replaces the current set.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `id`, `is_active`, `is_default`, `name`, `work_item_type_ids`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "description": "What this is for.",
+ "is_active": true,
+ "work_item_type_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "description": "What this is for.",
+ "is_active": True,
+ "work_item_type_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ description: "What this is for.",
+ is_active: true,
+ work_item_type_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_active": true,
+ "is_default": false,
+ "name": "Example name",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/
+
+
+
+
+
+Workflows constrain how work items move between states in a project. Delete a workflow. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `id`, `is_active`, `is_default`, `name`, `work_item_type_ids`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/
+
+
+
+
+
+Workflows constrain how work items move between states in a project. Read a single workflow by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `id`, `is_active`, `is_default`, `name`, `work_item_type_ids`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_active": true,
+ "is_default": false,
+ "name": "Example name",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/
+
+
+
+
+
+Workflows constrain how work items move between states in a project. List the workflows you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `id`, `is_active`, `is_default`, `name`, `work_item_type_ids`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_active": true,
+ "is_default": false,
+ "name": "Example name",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+ },
+ {
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "is_active": true,
+ "is_default": false,
+ "name": "Another example",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workflow object
+
+### Attributes
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `description` _string_
+
+ Free-form description.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_active` _boolean_
+
+ Whether the record is active.
+
+- `is_default` _boolean_
+
+ Make this the default for its parent. Setting it clears the flag on the previous default.
+
+- `name` _string_
+
+ Display name.
+
+- `work_item_type_ids` _array of string_
+
+ Ids of the associated work item types.
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_active": true,
+ "is_default": false,
+ "name": "Example name",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/
+
+
+
+
+
+Workflows constrain how work items move between states in a project. Update a workflow. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the resource belongs to. Accepts the project UUID or its bare identifier, for example `ENG`.
+
+
+
+
+
+The workflow id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Free-form description.
+
+Nullable.
+
+
+
+
+
+Whether the record is active.
+
+
+
+
+
+Display name.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+Ids of the work item types to associate. Replaces the current set.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description`, `id`, `is_active`, `is_default`, `name`, `work_item_type_ids`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.workflows:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "description": "What this is for.",
+ "is_active": true,
+ "name": "Example name"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "description": "What this is for.",
+ "is_active": True,
+ "name": "Example name"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ description: "What this is for.",
+ is_active: true,
+ name: "Example name",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_active": true,
+ "is_default": false,
+ "name": "Example name",
+ "work_item_type_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]]
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workflow matches the given query."
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/assets/{pk}/
+
+
+
+
+
+Workspace assets are files uploaded against a workspace. Update a asset. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The asset id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `asset_url`, `attributes`, `content_type`, `created_at`, `created_by_id`, `entity_type`, `external_id`, `external_source`, `id`, `is_uploaded`, `name`, `size`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`assets:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_uploaded": false,
+ "name": "Example name",
+ "size": 1
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No asset matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/assets/
+
+
+
+
+
+Workspace assets are files uploaded against a workspace. Create a asset.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+
+
+
+
+The size.
+
+
+
+
+
+The entity type.
+
+
+
+
+
+The type.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `asset_url`, `attributes`, `content_type`, `created_at`, `created_by_id`, `entity_type`, `external_id`, `external_source`, `id`, `is_uploaded`, `name`, `size`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`assets:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "size": 1,
+ "entity_type": "example",
+ "type": "example"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "size": 1,
+ "entity_type": "example",
+ "type": "example"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/assets/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ size: 1,
+ entity_type: "example",
+ type: "example",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_uploaded": false,
+ "name": "Example name",
+ "size": 1
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/assets/{pk}/
+
+
+
+
+
+Workspace assets are files uploaded against a workspace. Delete a asset. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The asset id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `asset_url`, `attributes`, `content_type`, `created_at`, `created_by_id`, `entity_type`, `external_id`, `external_source`, `id`, `is_uploaded`, `name`, `size`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`assets:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No asset matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/assets/{pk}/
+
+
+
+
+
+Workspace assets are files uploaded against a workspace. Read a single asset by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The asset id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `asset_url`, `attributes`, `content_type`, `created_at`, `created_by_id`, `entity_type`, `external_id`, `external_source`, `id`, `is_uploaded`, `name`, `size`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`assets:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_uploaded": false,
+ "name": "Example name",
+ "size": 1
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No asset matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/assets/
+
+
+
+
+
+Workspace assets are files uploaded against a workspace. List the workspace assets you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `asset_url`, `attributes`, `content_type`, `created_at`, `created_by_id`, `entity_type`, `external_id`, `external_source`, `id`, `is_uploaded`, `name`, `size`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`assets:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/assets/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/assets/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_uploaded": false,
+ "name": "Example name",
+ "size": 1
+ },
+ {
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "is_uploaded": false,
+ "name": "Another example",
+ "size": 1
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workspace asset object
+
+### Attributes
+
+- `asset_url` _string_
+
+ The asset url.
+
+- `attributes` _string_
+
+ The attributes.
+
+- `content_type` _string_
+
+ The content type.
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `entity_type` _string_
+
+ The entity type.
+
+- `external_id` _string_
+
+ Your system's identifier for this record, for sync and import correlation.
+
+- `external_source` _string_
+
+ The system `external_id` came from, for example `github` or `jira`.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_uploaded` _boolean_
+
+ Whether is uploaded.
+
+- `name` _string_
+
+ Display name.
+
+- `size` _number_
+
+ The size.
+
+
+
+
+
+
+```json
+{
+ "asset_url": "https://example.com",
+ "attributes": null,
+ "content_type": "example",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "entity_type": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_uploaded": false,
+ "name": "Example name",
+ "size": 1
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/automations/{automation_id}/edges/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Create a automation edge.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Id of the related source node.
+
+
+
+
+
+Id of the related target node.
+
+
+
+
+
+Order for evaluation when multiple edges from same node
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `execution_order`, `id`, `source_node_id`, `target_node_id`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "execution_order": 1
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "execution_order": 1
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ source_node_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ target_node_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ execution_order: 1,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "execution_order": 1,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Create a automation node.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Name of the handler class (e.g., 'record_created', 'send_email')
+
+Maximum 100 characters.
+
+
+
+
+
+Display name for the node
+
+Maximum 255 characters.
+
+
+
+
+
+Type of node: trigger, action, or condition
+
+- `trigger` - Trigger
+- `action` - Action
+- `condition` - Condition
+
+One of `trigger`, `action`, `condition`.
+
+
+
+
+
+Node-specific configuration and parameters
+
+
+
+
+
+Whether the rule is switched on.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `config`, `created_at`, `created_by_id`, `handler_name`, `id`, `is_enabled`, `last_triggered_at`, `name`, `next_scheduled_at`, `node_type`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "handler_name": "example",
+ "name": "Example name",
+ "node_type": "trigger",
+ "config": null,
+ "is_enabled": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "handler_name": "example",
+ "name": "Example name",
+ "node_type": "trigger",
+ "config": None,
+ "is_enabled": False
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ handler_name: "example",
+ name: "Example name",
+ node_type: "trigger",
+ config: null,
+ is_enabled: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "config": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "handler_name": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "last_triggered_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "next_scheduled_at": "2026-01-14T09:22:41.478363Z",
+ "node_type": null,
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/automations/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Create a workspace automation.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Human-readable automation name
+
+Maximum 255 characters.
+
+
+
+
+
+The scope defines on what entity this automation runs on (e.g., WorkItem, Cycle, Module)
+
+Maximum 50 characters.
+
+
+
+
+
+Automation description
+
+
+
+
+
+Ids of the projects to associate. Replaces the current set.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `bot_user_id`, `created_at`, `created_by_id`, `current_version_id`, `description`, `id`, `is_enabled`, `is_global`, `last_run_at`, `name`, `project_ids`, `run_count`, `scope`, `status`, `updated_at`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "scope": "example",
+ "description": "What this is for.",
+ "project_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "scope": "example",
+ "description": "What this is for.",
+ "project_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/automations/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ scope: "example",
+ description: "What this is for.",
+ project_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "bot_user_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "current_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "is_global": false,
+ "last_run_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "project_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "run_count": 3,
+ "scope": "example",
+ "status": "draft",
+ "updated_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/automations/{automation_id}/edges/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Delete a automation edge. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation edge id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `execution_order`, `id`, `source_node_id`, `target_node_id`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation edge matches the given query."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Delete a automation node. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation node id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `config`, `created_at`, `created_by_id`, `handler_name`, `id`, `is_enabled`, `last_triggered_at`, `name`, `next_scheduled_at`, `node_type`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation node matches the given query."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/automations/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Delete a workspace automation. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace automation id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `bot_user_id`, `created_at`, `created_by_id`, `current_version_id`, `description`, `id`, `is_enabled`, `is_global`, `last_run_at`, `name`, `project_ids`, `run_count`, `scope`, `status`, `updated_at`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace automation matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/activities/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Read a single automation activity by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation activity id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `actor_id`, `automation_edge_id`, `automation_id`, `automation_node_id`, `automation_run_id`, `automation_scope`, `automation_version_id`, `created_at`, `epoch`, `field`, `id`, `new_identifier`, `new_value`, `node_execution_id`, `old_identifier`, `old_value`, `verb`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "actor_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_edge_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_run_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_scope": "example",
+ "automation_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "epoch": 1,
+ "field": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "new_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "new_value": "example",
+ "node_execution_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_value": "example",
+ "verb": "example"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation activity matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/edges/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Read a single automation edge by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation edge id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `execution_order`, `id`, `source_node_id`, `target_node_id`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "execution_order": 1,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation edge matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Read a single automation node by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation node id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `config`, `created_at`, `created_by_id`, `handler_name`, `id`, `is_enabled`, `last_triggered_at`, `name`, `next_scheduled_at`, `node_type`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "config": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "handler_name": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "last_triggered_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "next_scheduled_at": "2026-01-14T09:22:41.478363Z",
+ "node_type": null,
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation node matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Read a single workspace automation by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace automation id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `bot_user_id`, `created_at`, `created_by_id`, `current_version_id`, `description`, `id`, `is_enabled`, `is_global`, `last_run_at`, `name`, `project_ids`, `run_count`, `scope`, `status`, `updated_at`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "bot_user_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "current_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "is_global": false,
+ "last_run_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "project_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "run_count": 3,
+ "scope": "example",
+ "status": "draft",
+ "updated_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace automation matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/activities/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. List the automation activities you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `created_at__gt`.
+
+
+
+
+
+Filter by `field`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+Filter by `verb`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `actor_id`, `automation_edge_id`, `automation_id`, `automation_node_id`, `automation_run_id`, `automation_scope`, `automation_version_id`, `created_at`, `epoch`, `field`, `id`, `new_identifier`, `new_value`, `node_execution_id`, `old_identifier`, `old_value`, `verb`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/activities/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "actor_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_edge_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_run_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_scope": "example",
+ "automation_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "epoch": 1,
+ "field": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "new_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "new_value": "example",
+ "node_execution_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_value": "example",
+ "verb": "example"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/edges/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. List the automation edges you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+Filter by `source_node_id`.
+
+
+
+
+
+Filter by `target_node_id`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `execution_order`, `id`, `source_node_id`, `target_node_id`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "execution_order": 1,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+ {
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "execution_order": 1,
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. List the automation nodes you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `handler_name`.
+
+
+
+
+
+Filter by `is_enabled`.
+
+
+
+
+
+Filter by `name`.
+
+
+
+
+
+Filter by `node_type`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `config`, `created_at`, `created_by_id`, `handler_name`, `id`, `is_enabled`, `last_triggered_at`, `name`, `next_scheduled_at`, `node_type`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "config": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "handler_name": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "last_triggered_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "next_scheduled_at": "2026-01-14T09:22:41.478363Z",
+ "node_type": null,
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+ {
+ "config": null,
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "handler_name": "example",
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "is_enabled": false,
+ "last_triggered_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Another example",
+ "next_scheduled_at": "2026-01-14T09:22:41.478363Z",
+ "node_type": null,
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/automations/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. List the workspace automations you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `is_enabled`.
+
+
+
+
+
+Filter by `is_global`.
+
+
+
+
+
+Filter by `name`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+Filter by `scope`.
+
+
+
+
+
+A search term.
+
+
+
+
+
+Filter by `status`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `bot_user_id`, `created_at`, `created_by_id`, `current_version_id`, `description`, `id`, `is_enabled`, `is_global`, `last_run_at`, `name`, `project_ids`, `run_count`, `scope`, `status`, `updated_at`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/automations/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "bot_user_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "current_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "is_global": false,
+ "last_run_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "project_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "run_count": 3,
+ "scope": "example",
+ "status": "draft",
+ "updated_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workspace automation object
+
+### Attributes
+
+- `actor_id` _string (uuid)_
+
+ The related actor.
+
+- `automation_edge_id` _string (uuid)_
+
+ The related automation edge.
+
+- `automation_id` _string (uuid)_
+
+ The related automation.
+
+- `automation_node_id` _string (uuid)_
+
+ The related automation node.
+
+- `automation_run_id` _string (uuid)_
+
+ The related automation run.
+
+- `automation_scope` _string_
+
+ The automation scope.
+
+- `automation_version_id` _string (uuid)_
+
+ The related automation version.
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `epoch` _number_
+
+ The epoch.
+
+- `field` _string_
+
+ The field.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `new_identifier` _string (uuid)_
+
+ The new identifier.
+
+- `new_value` _string_
+
+ The new value.
+
+- `node_execution_id` _string (uuid)_
+
+ The related node execution.
+
+- `old_identifier` _string (uuid)_
+
+ The old identifier.
+
+- `old_value` _string_
+
+ The old value.
+
+- `verb` _string_
+
+ The verb.
+
+
+
+
+
+
+```json
+{
+ "actor_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_edge_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_run_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "automation_scope": "example",
+ "automation_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "epoch": 1,
+ "field": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "new_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "new_value": "example",
+ "node_execution_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_identifier": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "old_value": "example",
+ "verb": "example"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/{pk}/regenerate-webhook-secret/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation node id.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/regenerate-webhook-secret/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/regenerate-webhook-secret/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/regenerate-webhook-secret/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "secret": "example"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/automations/{pk}/status/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace automation id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Whether the rule is switched on.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/status/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "is_enabled": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/status/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "is_enabled": False
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/status/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ is_enabled: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/automations/{automation_id}/edges/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Update a automation edge. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation edge id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Order for evaluation when multiple edges from same node
+
+
+
+
+
+Id of the related source node.
+
+
+
+
+
+Id of the related target node.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `execution_order`, `id`, `source_node_id`, `target_node_id`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "execution_order": 1,
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "execution_order": 1,
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/edges/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ execution_order: 1,
+ source_node_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ target_node_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "execution_order": 1,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "source_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "target_node_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation edge matches the given query."
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/automations/{automation_id}/nodes/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Update a automation node. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The automation the resource belongs to.
+
+
+
+
+
+The automation node id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Node-specific configuration and parameters
+
+
+
+
+
+Name of the handler class (e.g., 'record_created', 'send_email')
+
+Maximum 100 characters.
+
+
+
+
+
+Whether the rule is switched on.
+
+
+
+
+
+Display name for the node
+
+Maximum 255 characters.
+
+
+
+
+
+Type of node: trigger, action, or condition
+
+- `trigger` - Trigger
+- `action` - Action
+- `condition` - Condition
+
+One of `trigger`, `action`, `condition`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `config`, `created_at`, `created_by_id`, `handler_name`, `id`, `is_enabled`, `last_triggered_at`, `name`, `next_scheduled_at`, `node_type`, `updated_at`, `version_id`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "config": null,
+ "handler_name": "example",
+ "is_enabled": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "config": None,
+ "handler_name": "example",
+ "is_enabled": False
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/nodes/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ config: null,
+ handler_name: "example",
+ is_enabled: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "config": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "handler_name": "example",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "last_triggered_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "next_scheduled_at": "2026-01-14T09:22:41.478363Z",
+ "node_type": null,
+ "updated_at": "2026-01-14T09:22:41.478363Z",
+ "version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No automation node matches the given query."
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/automations/{pk}/
+
+
+
+
+
+Workspace automations are rule graphs that run across a workspace. Update a workspace automation. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace automation id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Automation description
+
+
+
+
+
+Human-readable automation name
+
+Maximum 255 characters.
+
+
+
+
+
+Ids of the projects to associate. Replaces the current set.
+
+
+
+
+
+The scope defines on what entity this automation runs on (e.g., WorkItem, Cycle, Module)
+
+Maximum 50 characters.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `bot_user_id`, `created_at`, `created_by_id`, `current_version_id`, `description`, `id`, `is_enabled`, `is_global`, `last_run_at`, `name`, `project_ids`, `run_count`, `scope`, `status`, `updated_at`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`automations:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "description": "What this is for.",
+ "name": "Example name",
+ "project_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "description": "What this is for.",
+ "name": "Example name",
+ "project_ids": [
+ [
+ "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
+ ]
+ ]
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/automations/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ description: "What this is for.",
+ name: "Example name",
+ project_ids: [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "bot_user_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "current_version_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "description": "What this is for.",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_enabled": false,
+ "is_global": false,
+ "last_run_at": "2026-01-14T09:22:41.478363Z",
+ "name": "Example name",
+ "project_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
+ "run_count": 3,
+ "scope": "example",
+ "status": "draft",
+ "updated_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace automation matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/features/
+
+
+
+
+
+Read the workspace's feature flags. There is one feature record per workspace, so this returns a single object rather than a list.
+
+Call it during client start-up. `is_work_item_types_enabled` tells you which surface accepts work item type and property writes, and the remaining flags tell you which parts of your UI or sync are worth showing at all.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+None. This endpoint takes no filters, no pagination, and no `?expand=` — passing one is not a supported way to widen the response.
+
+
+
+
+
+### Scopes
+
+`workspaces.features:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's features. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: tip This is the mode check
+`is_work_item_types_enabled: true` means the workspace manages work item types at the **workspace** level; `false` means each **project** does. Writes sent to the other surface return `409`, with `work_item_types_managed_at_workspace` or `work_item_types_managed_at_project`. Reads are unaffected. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+::: info Cache it, but not forever
+The flags change rarely, so caching the response for the life of a request batch is reasonable. Re-read it whenever a write returns `409 work_item_types_managed_at_workspace` or `work_item_types_managed_at_project` — that code means your cached mode is stale.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/features/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/features/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+features = response.json()
+
+if features["is_work_item_types_enabled"]:
+ base = "https://api.plane.so/api/v2/workspaces/my-team" # workspace mode
+else:
+ base = "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/features/", {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const features = await response.json();
+const workspaceMode = features.is_work_item_types_enabled;
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": false,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No Workspace matches the given query."
+}
+```
+
+
+
+
+
+
+
+## The workspace feature object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the workspace's feature record.
+
+- `is_work_item_types_enabled` _boolean_
+
+ Whether work item types are managed at the **workspace** level. `true` means workspace mode — types and properties are defined once for the workspace and imported into projects. `false` means project mode — each project owns its own types. This is the field to read before any type or property write. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+- `work_item_type_default_level` _integer_
+
+ The default level applied to work item types in this workspace. The schema constrains it to an integer and declares no enum, so treat any value as legal and leave it as returned unless you are deliberately changing type levels.
+
+- `is_workitem_hierarchy_enabled` _boolean_
+
+ Whether work items can be nested into a parent and child hierarchy in this workspace.
+
+- `is_project_grouping_enabled` _boolean_
+
+ Whether projects can be organized into groups in the workspace.
+
+- `is_teams_enabled` _boolean_
+
+ Whether teamspaces are available. Teamspaces have their own endpoints under the `teamspaces:*` scopes.
+
+- `is_wiki_enabled` _boolean_
+
+ Whether the workspace-level wiki is available, behind the `wiki.pages:*` scopes.
+
+- `is_initiative_enabled` _boolean_
+
+ Whether initiatives — the layer that groups projects and epics toward a larger outcome — are available.
+
+- `is_customer_enabled` _boolean_
+
+ Whether customers and customer requests are available, behind the `customers:*` scopes.
+
+- `is_release_enabled` _boolean_
+
+ Whether releases are available, behind the `releases:*` scopes.
+
+- `is_state_duration_enabled` _boolean_
+
+ Whether Plane records how long work items spend in each state.
+
+- `is_pi_enabled` _boolean_
+
+ Whether Pi, Plane's AI assistant, is available in the workspace.
+
+- `created_at` _string (date-time)_
+
+ When the feature record was created.
+
+::: warning Watch the spelling of the hierarchy flag
+It is `is_workitem_hierarchy_enabled` — no underscore between `work` and `item` — while its neighbor is `is_work_item_types_enabled`. Unknown keys in a `PATCH` body do not toggle anything, so a misspelling looks like a silent no-op. Read the response back and confirm the flag actually moved.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": false,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/features/
+
+
+
+
+
+Turn workspace features on or off. The update is partial — send only the flags you want to change, and every field you omit keeps its current value. Omitting a field is not the same as sending `null`.
+
+The response is the full feature object after the change, so you never need a follow-up `GET` to confirm what happened.
+
+::: warning Toggling `is_work_item_types_enabled` moves the write surface
+This flag decides whether work item types are managed at the workspace or the project level. Flipping it changes which endpoints accept type and property writes **for every client in the workspace**, and in-flight integrations start getting `409` from the surface they were using. Treat it as an administrative action, not a runtime decision. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. `id` and `created_at` are read-only — sending them has no effect.
+
+
+
+
+
+Manage work item types at the workspace level (`true`) or per project (`false`). This is the work item type mode switch — read [Work item type modes](/api-reference/v2/work-item-type-modes) before changing it.
+
+
+
+
+
+The default level applied to work item types in this workspace. The schema declares no enum and no bounds, so it accepts any integer.
+
+
+
+
+
+Allow work items to be nested into a parent and child hierarchy. Note the spelling — no underscore between `work` and `item`.
+
+
+
+
+
+Allow projects to be organized into groups in the workspace.
+
+
+
+
+
+Enable teamspaces for the workspace.
+
+
+
+
+
+Enable the workspace-level wiki.
+
+
+
+
+
+Enable initiatives, the layer that groups projects and epics toward a larger outcome.
+
+
+
+
+
+Enable customers and customer requests.
+
+
+
+
+
+Enable releases.
+
+
+
+
+
+Record how long work items spend in each state.
+
+
+
+
+
+Enable Pi, Plane's AI assistant, in the workspace.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.features:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | A flag was sent with a non-boolean value, or `work_item_type_default_level` was not an integer. Includes an `errors[]` array naming the field. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't change this workspace's features. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The requested toggle conflicts with the workspace's current state and was not applied. Re-read the object before retrying. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info Unknown keys are not toggles
+A body key that is not one of the fields above is not a flag and does not change anything. Always compare the response object against what you sent rather than assuming a `200` means your flag moved; `is_workitem_hierarchy_enabled` in particular is easy to mistype as `is_work_item_hierarchy_enabled`.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/features/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "is_work_item_types_enabled": true,
+ "is_state_duration_enabled": true
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/features/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "is_work_item_types_enabled": True,
+ "is_state_duration_enabled": True,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/features/", {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ is_work_item_types_enabled: true,
+ is_state_duration_enabled: true,
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": true,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "invalid_request",
+ "code": "invalid_request",
+ "detail": "Invalid input.",
+ "errors": [
+ {
+ "field": "is_teams_enabled",
+ "code": "invalid",
+ "message": "Must be a valid boolean."
+ }
+ ]
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/pages/
+
+
+
+
+
+Workspace pages are the wiki documents that live outside any project. Create a workspace page.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+
+
+
+
+Who can see this.
+
+
+
+
+
+The archived at.
+
+Nullable.
+
+
+
+
+
+Id of the related collection.
+
+Nullable.
+
+
+
+
+
+Hex color used wherever this is rendered, for example `#3f76ff`.
+
+Maximum 255 characters.
+
+
+
+
+
+Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+
+
+
+
+Your system's identifier for this record, for sync and import correlation.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+Prevents further edits to the content.
+
+
+
+
+
+Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+
+
+
+
+Id of the related parent.
+
+Nullable.
+
+
+
+
+
+Manual ordering weight. Lower sorts first.
+
+
+
+
+
+Editor-owned layout descriptor. Pass back what you read.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `collection_id`, `color`, `created_at`, `created_by_id`, `description_html`, `description_stripped`, `external_id`, `external_source`, `id`, `is_global`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `parent_id`, `sort_order`, `view_props`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`, `parent`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`wiki.pages:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "access": null,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "access": None,
+ "archived_at": None,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/pages/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ access: null,
+ archived_at: null,
+ collection_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "color": "#3f76ff",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "description_stripped": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_global": false,
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "sort_order": 65535,
+ "view_props": null
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/pages/{pk}/
+
+
+
+
+
+Workspace pages are the wiki documents that live outside any project. Delete a workspace page. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace page id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `collection_id`, `color`, `created_at`, `created_by_id`, `description_html`, `description_stripped`, `external_id`, `external_source`, `id`, `is_global`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `parent_id`, `sort_order`, `view_props`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`, `parent`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`wiki.pages:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace page matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/pages/{pk}/
+
+
+
+
+
+Workspace pages are the wiki documents that live outside any project. Read a single workspace page by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace page id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `collection_id`, `color`, `created_at`, `created_by_id`, `description_html`, `description_stripped`, `external_id`, `external_source`, `id`, `is_global`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `parent_id`, `sort_order`, `view_props`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`, `parent`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`wiki.pages:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "color": "#3f76ff",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "description_stripped": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_global": false,
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "sort_order": 65535,
+ "view_props": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace page matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/pages/
+
+
+
+
+
+Workspace pages are the wiki documents that live outside any project. List the workspace pages you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+- `0` - Public
+- `1` - Private
+
+One of `0`, `1`.
+
+
+
+
+
+Filter by `collection_id`.
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `external_id`.
+
+
+
+
+
+Filter by `external_source`.
+
+
+
+
+
+Filter by `is_global`.
+
+
+
+
+
+Filter by `is_locked`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Filter by `owned_by_id`.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Filter by `parent_id`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+- `all` - All
+- `public` - Public
+- `private` - Private
+- `shared` - Shared
+- `archived` - Archived
+
+One of `all`, `archived`, `private`, `public`, `shared`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `collection_id`, `color`, `created_at`, `created_by_id`, `description_html`, `description_stripped`, `external_id`, `external_source`, `id`, `is_global`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `parent_id`, `sort_order`, `view_props`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`, `parent`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`wiki.pages:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/pages/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "access": 0,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "color": "#3f76ff",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "description_stripped": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_global": false,
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "sort_order": 65535,
+ "view_props": null
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workspace page object
+
+### Attributes
+
+- `access` _integer_
+
+ Who can see this.
+
+- `archived_at` _string (date-time)_
+
+ When the record was archived, or `null` if it is active.
+
+- `collection_id` _string_
+
+ The related collection.
+
+- `color` _string_
+
+ Hex color used wherever this is rendered, for example `#3f76ff`.
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `description_html` _string_
+
+ Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+- `description_stripped` _string_
+
+ The description stripped.
+
+- `external_id` _string_
+
+ Your system's identifier for this record, for sync and import correlation.
+
+- `external_source` _string_
+
+ The system `external_id` came from, for example `github` or `jira`.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_global` _boolean_
+
+ Whether this lives at the workspace level rather than inside a project.
+
+- `is_locked` _boolean_
+
+ Prevents further edits to the content.
+
+- `logo_props` _string_
+
+ Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+- `name` _string_
+
+ Display name.
+
+- `owned_by_id` _string (uuid)_
+
+ The related owned by.
+
+- `parent_id` _string (uuid)_
+
+ The related parent.
+
+- `sort_order` _number_
+
+ Manual ordering weight. Lower sorts first.
+
+- `view_props` _string_
+
+ Editor-owned layout descriptor. Pass back what you read.
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "color": "#3f76ff",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "description_stripped": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_global": false,
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "sort_order": 65535,
+ "view_props": null
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/pages/{pk}/
+
+
+
+
+
+Workspace pages are the wiki documents that live outside any project. Update a workspace page. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace page id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Who can see this.
+
+
+
+
+
+The archived at.
+
+Nullable.
+
+
+
+
+
+Id of the related collection.
+
+Nullable.
+
+
+
+
+
+Hex color used wherever this is rendered, for example `#3f76ff`.
+
+Maximum 255 characters.
+
+
+
+
+
+Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+
+
+
+
+Your system's identifier for this record, for sync and import correlation.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`.
+
+Maximum 255 characters. Nullable.
+
+
+
+
+
+Prevents further edits to the content.
+
+
+
+
+
+Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+
+
+
+
+Display name.
+
+
+
+
+
+Id of the related parent.
+
+Nullable.
+
+
+
+
+
+Manual ordering weight. Lower sorts first.
+
+
+
+
+
+Editor-owned layout descriptor. Pass back what you read.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `collection_id`, `color`, `created_at`, `created_by_id`, `description_html`, `description_stripped`, `external_id`, `external_source`, `id`, `is_global`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `parent_id`, `sort_order`, `view_props`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`, `parent`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`wiki.pages:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "access": null,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "access": None,
+ "archived_at": None,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/pages/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ access: null,
+ archived_at: null,
+ collection_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "collection_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "color": "#3f76ff",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "description_stripped": "example",
+ "external_id": null,
+ "external_source": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_global": false,
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "sort_order": 65535,
+ "view_props": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace page matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/views/
+
+
+
+
+
+Workspace views are saved filter-and-layout combinations across a workspace. Create a workspace view.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+Who can see this.
+
+
+
+
+
+Free-form description.
+
+
+
+
+
+Saved display options — grouping, ordering and layout.
+
+
+
+
+
+The display properties.
+
+
+
+
+
+Saved filter set, in the same shape the list endpoints accept.
+
+
+
+
+
+Prevents further edits to the content.
+
+
+
+
+
+Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+
+
+
+
+The pql filters.
+
+
+
+
+
+Manual ordering weight. Lower sorts first.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `created_at`, `created_by_id`, `description`, `display_filters`, `display_properties`, `filters`, `id`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `pql_filters`, `query`, `sort_order`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.views:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/views/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "access": null,
+ "description": "What this is for.",
+ "display_filters": null
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "access": None,
+ "description": "What this is for.",
+ "display_filters": None
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/views/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ access: null,
+ description: "What this is for.",
+ display_filters: null,
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "display_filters": null,
+ "display_properties": null,
+ "filters": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "pql_filters": null,
+ "query": null,
+ "sort_order": 65535
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/views/{pk}/
+
+
+
+
+
+Workspace views are saved filter-and-layout combinations across a workspace. Delete a workspace view. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace view id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `created_at`, `created_by_id`, `description`, `display_filters`, `display_properties`, `filters`, `id`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `pql_filters`, `query`, `sort_order`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.views:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace view matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/views/{pk}/
+
+
+
+
+
+Workspace views are saved filter-and-layout combinations across a workspace. Read a single workspace view by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace view id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `created_at`, `created_by_id`, `description`, `display_filters`, `display_properties`, `filters`, `id`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `pql_filters`, `query`, `sort_order`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.views:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "display_filters": null,
+ "display_properties": null,
+ "filters": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "pql_filters": null,
+ "query": null,
+ "sort_order": 65535
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace view matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/views/
+
+
+
+
+
+Workspace views are saved filter-and-layout combinations across a workspace. List the workspace views you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+- `0` - Private
+- `1` - Public
+
+One of `0`, `1`.
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `is_locked`.
+
+
+
+
+
+Filter by `name`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Filter by `owned_by_id`.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `created_at`, `created_by_id`, `description`, `display_filters`, `display_properties`, `filters`, `id`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `pql_filters`, `query`, `sort_order`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.views:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/views/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/views/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "access": 0,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "display_filters": null,
+ "display_properties": null,
+ "filters": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "pql_filters": null,
+ "query": null,
+ "sort_order": 65535
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workspace view object
+
+### Attributes
+
+- `access` _integer_
+
+ Who can see this.
+
+- `archived_at` _string (date-time)_
+
+ When the record was archived, or `null` if it is active.
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `description` _string_
+
+ Free-form description.
+
+- `display_filters` _string_
+
+ Saved display options — grouping, ordering and layout.
+
+- `display_properties` _string_
+
+ The display properties.
+
+- `filters` _string_
+
+ Saved filter set, in the same shape the list endpoints accept.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_locked` _boolean_
+
+ Prevents further edits to the content.
+
+- `logo_props` _string_
+
+ Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+- `name` _string_
+
+ Display name.
+
+- `owned_by_id` _string (uuid)_
+
+ The related owned by.
+
+- `pql_filters` _string_
+
+ The pql filters.
+
+- `query` _string_
+
+ The query.
+
+- `sort_order` _number_
+
+ Manual ordering weight. Lower sorts first.
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "display_filters": null,
+ "display_properties": null,
+ "filters": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "pql_filters": null,
+ "query": null,
+ "sort_order": 65535
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/views/{pk}/
+
+
+
+
+
+Workspace views are saved filter-and-layout combinations across a workspace. Update a workspace view. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace view id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Who can see this.
+
+
+
+
+
+Free-form description.
+
+
+
+
+
+Saved display options — grouping, ordering and layout.
+
+
+
+
+
+The display properties.
+
+
+
+
+
+Saved filter set, in the same shape the list endpoints accept.
+
+
+
+
+
+Prevents further edits to the content.
+
+
+
+
+
+Editor-owned logo descriptor. Pass back what you read rather than composing it by hand.
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+The pql filters.
+
+
+
+
+
+Manual ordering weight. Lower sorts first.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `access`, `archived_at`, `created_at`, `created_by_id`, `description`, `display_filters`, `display_properties`, `filters`, `id`, `is_locked`, `logo_props`, `name`, `owned_by_id`, `pql_filters`, `query`, `sort_order`.
+
+
+
+
+
+Comma-separated relations to embed: `owned_by`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. `?fields=` and `?expand=` are independent: naming a relation in `?fields=` is a `400`, and expanded objects survive field filtering. See [Expanding relations](/api-reference/v2/expanding-relations).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.views:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "access": null,
+ "description": "What this is for.",
+ "display_filters": null
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "access": None,
+ "description": "What this is for.",
+ "display_filters": None
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/views/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ access: null,
+ description: "What this is for.",
+ display_filters: null,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "access": 0,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description": "What this is for.",
+ "display_filters": null,
+ "display_properties": null,
+ "filters": null,
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_locked": false,
+ "logo_props": null,
+ "name": "Example name",
+ "owned_by_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "pql_filters": null,
+ "query": null,
+ "sort_order": 65535
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace view matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-properties/
+
+
+
+
+
+Define a custom property once for the whole workspace. `display_name` and `property_type` are the only
+required fields; everything else refines how the value is captured.
+
+::: warning A new property is not live yet
+Creating a property adds it to the workspace catalog. It appears on work items only once a **context** binds
+it to projects and work item types. Follow this call with
+[Create a property context](/api-reference/v2/work-item-property-contexts/create-property-context), or the
+property will sit in the catalog unused.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Create the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The label shown wherever the property is rendered. Maximum 255 characters.
+
+
+
+
+
+What kind of value the property holds. Choose carefully — it governs what `relation_type`, `options`,
+`settings`, and `validation_rules` mean.
+
+- `TEXT` — free-form text
+- `DATETIME` — a date and time
+- `DECIMAL` — a number
+- `BOOLEAN` — true or false
+- `OPTION` — a choice from a defined list
+- `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
+
+A value outside this list is a `400 invalid_request`.
+
+
+
+
+
+For a `RELATION` property, what it points at. One of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`. Leave it out
+— or send `null` — for every other property type.
+
+
+
+
+
+Free-form explanation of what the property captures. Nullable.
+
+
+
+
+
+Whether a value must be supplied for this property.
+
+
+
+
+
+Whether the property accepts more than one value.
+
+
+
+
+
+Whether the property is in use. Send `false` to define a property without putting it into circulation yet.
+
+
+
+
+
+The value applied when none is supplied. Send an array even for a single value.
+
+
+
+
+
+Seed the choices for an `OPTION` property in the same call. Write-only: the created options come back on the
+read-only `options` array of the response, and are managed afterwards through
+[Property options](/api-reference/v2/workspace-work-item-property-options/overview), which is also where the
+fields an option accepts are documented.
+
+
+
+
+
+Type-specific configuration. Its shape depends on `property_type`.
+
+
+
+
+
+Type-specific validation configuration.
+
+
+
+
+
+Your system's identifier for this property, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | Missing `display_name`/`property_type`, or an enum value outside the allowed set. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "display_name": "Severity",
+ "property_type": "OPTION",
+ "description": "How badly the customer is affected",
+ "is_required": true,
+ "is_multi": false,
+ "options": [
+ { "name": "Critical", "description": "Production is down" },
+ { "name": "Major", "description": "A core workflow is broken", "is_default": true }
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "display_name": "Severity",
+ "property_type": "OPTION",
+ "description": "How badly the customer is affected",
+ "is_required": True,
+ "is_multi": False,
+ "options": [
+ {"name": "Critical", "description": "Production is down"},
+ {"name": "Major", "description": "A core workflow is broken", "is_default": True},
+ ],
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ display_name: "Severity",
+ property_type: "OPTION",
+ description: "How badly the customer is affected",
+ is_required: true,
+ is_multi: false,
+ options: [
+ { name: "Critical", description: "Production is down" },
+ { name: "Major", description: "A core workflow is broken", is_default: true },
+ ],
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "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": [],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "invalid_request",
+ "code": "invalid_request",
+ "detail": "The request body failed validation.",
+ "errors": [
+ {
+ "field": "property_type",
+ "code": "invalid_choice",
+ "message": "\"SELECT\" is not a valid choice."
+ }
+ ]
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Remove a property from the workspace catalog. The delete is soft and the response is `204` with an empty body.
+
+This is the wide blast radius option: the property leaves every project and work item type it reached, unlike
+[detaching it from a single type](/api-reference/v2/workspace-work-item-type-properties/detach-workspace-type-property),
+which only affects that one type.
+
+::: tip Retire before you delete
+If the property has been collecting values, `PATCH` it with `is_active: false` first. The definition stays
+addressable while you migrate, and you can reverse the decision with a single field. Deleting is the move for
+a property created by mistake.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Delete the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request failed validation — most often a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `not_found` | No such workspace or property, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Retrieve a single workspace property by id. Use it to read a property's full configuration — its
+`property_type`, whether it is required or multi-valued, and the `options` behind an `OPTION` property —
+before rendering a field or before sending a `PATCH`.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes). A property outside your tenant returns `404`,
+never `403` — existence is never leaked.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item properties. |
+| `404` | `not_found` | No such workspace or property, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No work item property with this id exists in this workspace."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/
+
+
+
+
+
+Return the workspace's custom property catalog as a paginated list. This is how you resolve a property name to
+the `id` you need when creating a context or attaching the property to a work item type, and how you build a
+picker that stays in sync with what the workspace has defined.
+
+The list is the catalog, not what is live: it includes properties that have no
+[context](/api-reference/v2/work-item-property-contexts/overview) yet and therefore do not appear on any work
+item. Reads here are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This list takes no filters or search term — the whole catalog is returned, page by page. Check your spelling on
+`order_by` and `paginate`: neither is validated, so an unrecognized `order_by` silently falls back to the default
+ordering and anything other than `paginate=cursor` silently uses offset pagination.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the display order Plane uses for the property list. This is the order you
+ want when rendering a form; note that `sort_order` itself is not returned on the property object.
+- `created_at` , `-created_at` — when each property was created
+- `id` , `-id`
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the
+response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead
+of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from
+the response.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return on each row. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item properties. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(`https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/?${params}`, {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "c58b2e94-71a3-4d0f-9e62-4a1c7f38b5d2",
+ "name": "reviewer",
+ "display_name": "Reviewer",
+ "description": "Who signs off before release",
+ "property_type": "RELATION",
+ "relation_type": "USER",
+ "is_required": false,
+ "is_multi": true,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:23:12.904551Z"
+ },
+ {
+ "id": "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ "name": "rollout_date",
+ "display_name": "Rollout date",
+ "description": "When the fix reaches customers",
+ "property_type": "DATETIME",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:24:03.112884Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "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": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## 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`. This is the one decision worth getting right up front —
+ 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](/api-reference/v2/workspace-work-item-property-options/overview), 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.
+
+
+
+
+
+
+```json
+{
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Change a workspace property in place. `PATCH` is partial: send only the fields you want to change, and
+everything you omit is left untouched. Omitting a field is not the same as sending `null` — `null` clears a
+nullable field, omission changes nothing.
+
+There is no `PUT` on this resource; sending one returns `405 method_not_allowed`.
+
+Every project and work item type the property reaches sees the change — that is the point of defining it at
+the workspace level.
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Update the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. The body itself is optional too, though an empty `PATCH` does nothing useful.
+
+
+
+
+
+The label shown wherever the property is rendered. Maximum 255 characters. Renaming is safe for integrations
+that key on `id`.
+
+
+
+
+
+One of `TEXT`, `DATETIME`, `DECIMAL`, `BOOLEAN`, `OPTION`, `RELATION`, `URL`, `EMAIL`, `FILE`, or `FORMULA`.
+Changing the type of a property that is already collecting values reinterprets what those values mean —
+prefer retiring the old property with `is_active: false` and creating a new one.
+
+
+
+
+
+For a `RELATION` property, what it points at. One of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`. Nullable.
+
+
+
+
+
+Free-form explanation of what the property captures. Nullable — send `null` to clear it.
+
+
+
+
+
+Whether a value must be supplied for this property.
+
+
+
+
+
+Whether the property accepts more than one value.
+
+
+
+
+
+Set to `false` to retire the property without deleting it, and back to `true` to bring it into circulation
+again.
+
+
+
+
+
+The value applied when none is supplied. Always an array. Send `[]` to clear it.
+
+
+
+
+
+Write-only. For day-to-day option management — adding one choice, renaming another — use
+[Property options](/api-reference/v2/workspace-work-item-property-options/overview), which addresses each
+option by id.
+
+
+
+
+
+Type-specific configuration. Its shape depends on `property_type`.
+
+
+
+
+
+Type-specific validation configuration.
+
+
+
+
+
+Your system's identifier for this property. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from. Maximum 255 characters, nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | An enum value outside the allowed set, or a field over its length limit. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `not_found` | No such workspace or property, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "display_name": "Customer severity",
+ "is_required": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "display_name": "Customer severity",
+ "is_required": False,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ display_name: "Customer severity",
+ is_required: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Customer severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/
+
+
+
+
+
+Add a choice to a workspace-level `OPTION` property. The new option is appended to the end of the property's list and becomes immediately selectable on work items across the workspace.
+
+The property must have `property_type: "OPTION"`. Posting an option to a property of any other type returns `400 invalid_request` — the option list is meaningless for a `TEXT` or `DECIMAL` property.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — add the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level `OPTION` property to add the choice to. A project-scoped property id is a `404` here — this path never crosses into a project. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The choice as it is displayed. Maximum 255 characters.
+
+
+
+
+
+Free-form text explaining when to pick this choice.
+
+
+
+
+
+Make this the property's default choice. At most one option per property can be the default, and there is no automatic hand-off: if another option already has it, this request is rejected with `400 invalid_request`. Clear the current default with a `PATCH` first.
+
+
+
+
+
+Your system's identifier for this option, for sync and import correlation. Maximum 255 characters.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+`sort_order` is not accepted. Plane appends the new option after the current last one, so create options in the order you want them displayed.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | Missing `name`, a field over 255 characters, `is_default` when the property already has a default, or a property whose `property_type` is not `OPTION`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `not_found` | No such workspace or workspace-level property, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Sandbox",
+ description: "Reported on an isolated test tenant",
+ external_id: "env-sandbox",
+ external_source: "servicedesk",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26",
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "is_default": false,
+ "sort_order": 40000,
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "Work item types are managed at the project level for this workspace."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Remove a choice from a workspace-level `OPTION` property. The delete is soft — the option stops being selectable and disappears from reads, and the request returns `204` with an empty body.
+
+Deleting an option is not the same as renaming it. If the choice is being reworded, `PATCH` it instead: [Update a workspace property option](/api-reference/v2/workspace-work-item-property-options/update-workspace-property-option) keeps the option's `id`, so work items already holding it keep their value.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — delete the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to delete. It is looked up within the property, so an option id under the wrong `property_id` is a `404`.
+
+
+
+
+
+Deleting the property's default option leaves the property with no default. Nothing promotes another option in its place — set a new default explicitly if the property needs one.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. Already-deleted options are `404` too. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "Work item types are managed at the project level for this workspace."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Retrieve one option on a workspace-level `OPTION` property. Use it to resolve a stored option id back to a display name, or to confirm an option still exists before writing it onto a work item.
+
+Reads work in either work item type mode — only writes are mode-gated. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to retrieve.
+
+
+
+
+
+The option is looked up within the property, so a valid option id under the wrong `property_id` is a `404` rather than a match. Deleted options are gone from this endpoint too — a soft-deleted option returns `404`.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's properties. |
+| `404` | `not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/
+
+
+
+
+
+Return the selectable choices on a workspace-level `OPTION` property as a paginated list. This is how you resolve an option name to the `id` you store when setting the property on a work item, and how you build a picker that stays in sync with the property definition.
+
+Results are ordered by `sort_order` by default, which is the order the option list is meant to be displayed in.
+
+Reads work in either work item type mode. Only writes are mode-gated — see [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property whose options you want — see [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+This endpoint filters options by property rather than looking the property up, so an id that isn't a workspace-level property in this workspace — including a project-scoped property id — comes back as an empty list, not a `404`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+There are no filters on this resource. A property's option list is small and self-contained, so fetch it whole and match on `id` in your own code.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the property's own display order. This is the default.
+- `created_at` , `-created_at` — when each option was added
+- `id` , `-id`
+
+A value outside this list is ignored and the default `sort_order` ordering is used, so a typo shows up as an unexpected order rather than an error.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most properties have fewer than 20 options, so one page is usually the whole list.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+Cursor pagination needs a unique, monotonic sort key, and `sort_order` is neither. Pair it with `order_by=created_at` or `order_by=id`; a bare `?paginate=cursor` falls back to the default `sort_order` ordering and is rejected with `ordering_not_cursor_eligible`.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's properties. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57",
+ "name": "Staging",
+ "description": "Reported on the shared pre-release environment",
+ "is_default": false,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "a17f3c95-2d64-4b08-8e51-c94b7d60f382",
+ "name": "Development",
+ "description": "Reported on a local or branch environment",
+ "is_default": false,
+ "sort_order": 30000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## The property option object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the option. This is the value you store when you set the property on a work item, so treat it as the stable handle — `name` is only a label.
+
+- `name` _string_
+
+ The choice as it is displayed. Maximum 255 characters.
+
+- `description` _string_
+
+ Free-form text explaining when to pick this choice.
+
+- `is_default` _boolean_
+
+ Whether this is the property's default choice. At most one option per property can carry it.
+
+- `sort_order` _number_
+
+ Position of the option within the property's list. Lower values come first, and this is the order the list endpoint returns by default. Assigned by Plane — it is not a writable field.
+
+- `external_id` , `external_source` _string_
+
+ Correlation fields for sync and import. Together they let you map an option to a record in another system and find it again later.
+
+::: tip Store the id, not the name
+Renaming an option keeps its `id`, so integrations that matched on `id` keep working and integrations that matched on `name` break. Resolve names to ids once, then reference ids.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Change one option on a workspace-level `OPTION` property — rename it, reword its description, or move the property's default onto it.
+
+The update is partial: fields you omit are left untouched, and omitting a field is not the same as sending `null`. Renaming an option keeps its `id`, so every work item already holding the option keeps its value.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — update the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to update. It is looked up within the property, so an option id under the wrong `property_id` is a `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. Send only what you are changing.
+
+
+
+
+
+The choice as it is displayed. Maximum 255 characters.
+
+
+
+
+
+Free-form text explaining when to pick this choice.
+
+
+
+
+
+Make this the property's default choice, or send `false` to clear it. At most one option per property can be the default: setting it while a different option already holds it returns `400 invalid_request`, so clear the current default first and then set the new one.
+
+
+
+
+
+Your system's identifier for this option, for sync and import correlation. Maximum 255 characters.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+`sort_order` is not accepted here — an option's position is fixed at creation time and cannot be moved through the API.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | A field over 255 characters, or `is_default: true` when another option on the property is already the default. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Pre-production",
+ description: "Reported on the shared pre-release environment",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57",
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment",
+ "is_default": false,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "invalid_request",
+ "code": "invalid_request",
+ "detail": "Only one option can be the default."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-templates/
+
+
+
+
+
+Workspace work item templates pre-fill new work items across projects. Create a workspace work item template.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+Seed payload used on create/update and nested under read `template_data`.
+
+
+
+
+
+Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+
+
+
+
+Whether is published.
+
+
+
+
+
+The short description.
+
+Nullable.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description_html`, `id`, `is_published`, `name`, `short_description`, `short_id`, `slug`, `template_data`, `template_type`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`templates.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Example name",
+ "template_data": {
+ "assignees": null,
+ "description_html": "Details go here.
",
+ "labels": null,
+ "modules": null,
+ "name": "Example name",
+ "priority": "high",
+ "properties": null,
+ "state": null,
+ "type": null
+ },
+ "description_html": "Details go here.
",
+ "is_published": false,
+ "short_description": "example"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Example name",
+ "template_data": {
+ "assignees": None,
+ "description_html": "Details go here.
",
+ "labels": None,
+ "modules": None,
+ "name": "Example name",
+ "priority": "high",
+ "properties": None,
+ "state": None,
+ "type": None
+ },
+ "description_html": "Details go here.
",
+ "is_published": False,
+ "short_description": "example"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Example name",
+ template_data: {
+ assignees: null,
+ description_html: "Details go here.
",
+ labels: null,
+ modules: null,
+ name: "Example name",
+ priority: "high",
+ properties: null,
+ state: null,
+ type: null,
+ },
+ description_html: "Details go here.
",
+ is_published: false,
+ short_description: "example",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_published": false,
+ "name": "Example name",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-templates/{pk}/
+
+
+
+
+
+Workspace work item templates pre-fill new work items across projects. Delete a workspace work item template. A successful delete returns `204` with an empty body.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace work item template id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description_html`, `id`, `is_published`, `name`, `short_description`, `short_id`, `slug`, `template_data`, `template_type`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`templates.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace work item template matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-templates/{pk}/
+
+
+
+
+
+Workspace work item templates pre-fill new work items across projects. Read a single workspace work item template by id.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace work item template id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description_html`, `id`, `is_published`, `name`, `short_description`, `short_id`, `slug`, `template_data`, `template_type`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`templates.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_published": false,
+ "name": "Example name",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace work item template matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-templates/
+
+
+
+
+
+Workspace work item templates pre-fill new work items across projects. List the workspace work item templates you can see. Results are scoped to the path and to what your token is allowed to read.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Set to false to skip the total_count COUNT(\*) (omits total_count).
+
+
+
+
+
+Filter by `is_published`.
+
+
+
+
+
+Number of rows to skip from the start of the result set.
+
+
+
+
+
+Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.
+
+
+
+
+
+Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.
+
+One of `cursor`.
+
+
+
+
+
+Page size (max 200).
+
+
+
+
+
+A search term.
+
+
+
+
+
+Filter by `short_id`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from each row, not returned as `null`. `id` always comes back. Pass `all` for every requestable field.
+
+An unknown name is a `400` that names the valid set, so a typo can't silently cost you the saving. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description_html`, `id`, `is_published`, `name`, `short_description`, `short_id`, `slug`, `template_data`, `template_type`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`templates.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ----------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/", {
+ method: "GET",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_published": false,
+ "name": "Example name",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+ },
+ {
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "is_published": false,
+ "name": "Another example",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+ }
+ ],
+ "next": 1,
+ "pagination": {
+ "style": "offset"
+ },
+ "previous": 1,
+ "total_count": 3
+}
+```
+
+
+
+
+
+
+
+## The workspace work item template object
+
+### Attributes
+
+- `created_at` _string (date-time)_
+
+ When the record was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the record.
+
+- `description_html` _string_
+
+ Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+- `id` _string (uuid)_
+
+ Unique identifier.
+
+- `is_published` _boolean_
+
+ Whether is published.
+
+- `name` _string_
+
+ Display name.
+
+- `short_description` _string_
+
+ The short description.
+
+- `short_id` _string_
+
+ The related short.
+
+- `slug` _string_
+
+ The slug.
+
+- `template_data` _object_
+
+ The template data.
+
+- `template_type` _string_
+
+ The template type.
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_published": false,
+ "name": "Example name",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-templates/{pk}/
+
+
+
+
+
+Workspace work item templates pre-fill new work items across projects. Update a workspace work item template. Send only the keys you want to change — omitted keys keep their current value, and an explicit `null` clears a nullable field.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace work item template id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Rich-text body as HTML. This is the field the Plane editor round-trips.
+
+
+
+
+
+Whether is published.
+
+
+
+
+
+Display name.
+
+Maximum 255 characters.
+
+
+
+
+
+The short description.
+
+Nullable.
+
+
+
+
+
+Seed payload used on create/update and nested under read `template_data`.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted**, not returned as `null`. `id` always comes back. Pass `all` for every requestable field. An unknown name is a `400`. See [Sparse fields](/api-reference/v2/sparse-fields).
+
+Requestable here: `created_at`, `created_by_id`, `description_html`, `id`, `is_published`, `name`, `short_description`, `short_id`, `slug`, `template_data`, `template_type`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`templates.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | The request body or a query parameter failed validation. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan or is switched off. |
+| `403` | `forbidden` | Your role or token scope doesn't allow this. |
+| `404` | `not_found` | No such resource, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | A business rule blocks the write — see the notes above. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "description_html": "Details go here.
",
+ "is_published": false,
+ "name": "Example name"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "description_html": "Details go here.
",
+ "is_published": False,
+ "name": "Example name"
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-templates/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ description_html: "Details go here.
",
+ is_published: false,
+ name: "Example name",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "description_html": "Details go here.
",
+ "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
+ "is_published": false,
+ "name": "Example name",
+ "short_description": "example",
+ "short_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "slug": "my-team",
+ "template_data": {},
+ "template_type": "example"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No workspace work item template matches the given query."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/
+
+
+
+
+
+Attach one or more **existing** workspace properties to a workspace-level work item type. This does not create
+properties — create those first with
+[Create a workspace property](/api-reference/v2/workspace-work-item-properties/create-workspace-work-item-property),
+then send their ids here.
+
+Because the same property can be attached to many types, this is how you reuse one `Severity` definition
+across `Bug`, `Incident`, and `Escalation` instead of maintaining three near-identical fields.
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Attach through the project-level route instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type to attach the properties to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Ids of properties to attach, taken from the workspace property catalog. Send the whole set you want in one
+call rather than one request per property.
+
+Every id must already exist in this workspace. An unknown id — including one that belongs to another workspace
+— fails the request with `400 invalid_request`; nothing is attached, and a cross-tenant id is never silently
+linked.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | `properties` missing, not an array, or holding an id that doesn't exist here. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item types. |
+| `404` | `not_found` | No such workspace or type, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "properties": [
+ "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "properties": [
+ "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ ]
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ properties: ["a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15", "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"],
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "properties": ["a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15", "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"]
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/{pk}/
+
+
+
+
+
+Remove a property from a workspace-level work item type. The type stops carrying the property; nothing else
+changes.
+
+::: info Detaching is not deleting
+The property stays in the workspace catalog and stays attached to every other type that uses it. To remove it
+from the workspace entirely, call
+[Delete a workspace property](/api-reference/v2/workspace-work-item-properties/delete-workspace-work-item-property)
+instead.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Detach through the project-level route instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type to detach the property from.
+
+
+
+
+
+The property's id. A property that is not attached to this type returns `404`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request failed validation — most often a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item types. |
+| `404` | `not_found` | No such workspace, type, or property — or the property isn't on this type. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | This workspace manages work item types at the project level. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/{pk}/
+
+
+
+
+
+Retrieve one property as it is attached to a workspace-level work item type. Use it to read a single
+property's configuration — its `property_type`, whether it is required, its options — without pulling the
+whole list.
+
+This route also answers the membership question: a `200` means the property is attached to this type, and a
+`404` means it is not. A property that exists in the workspace but is not on this type returns `404`, the same
+as an id that does not exist at all.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type the property is attached to.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item types. |
+| `404` | `not_found` | No such workspace, type, or property — or the property isn't on this type. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No property with this id is attached to this work item type."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/
+
+
+
+
+
+Return the custom properties attached to one workspace-level work item type, as a paginated list. Reach for it
+when you are building a form for that type, or checking what a type already carries before attaching more.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes) — this route answers even when the workspace
+manages types at the project level.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type whose properties you want. Get it from
+[List workspace work item types](/api-reference/v2/workspace-work-item-types/list-workspace-work-item-types).
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This list takes no filters or search term — a type's property set is small and returned whole. Check your spelling on
+`order_by` and `paginate`: neither is validated, so an unrecognized `order_by` silently falls back to the default
+ordering and anything other than `paginate=cursor` silently uses offset pagination.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the display order Plane uses for the property list. This is the order you
+ want when rendering a form; note that `sort_order` itself is not returned on the property object.
+- `created_at` , `-created_at` — when each property was created
+- `id` , `-id`
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most types carry fewer than 20 properties, so one page is usually the
+whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the
+response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead
+of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from
+the response.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return on each row. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `default_value`, `description`, `display_name`, `external_id`, `external_source`, `id`, `is_active`, `is_multi`, `is_required`, `logo_props`, `name`, `options`, `property_type`, `relation_type`, `settings`, `validation_rules`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item types. |
+| `404` | `not_found` | No such workspace or type, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ "name": "rollout_date",
+ "display_name": "Rollout date",
+ "description": "When the fix reaches customers",
+ "property_type": "DATETIME",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:24:03.112884Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 2,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "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": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## The property object
+
+Reads on this resource return the full property object, the same shape the workspace property catalog returns.
+Every field is read-only here — this route only changes which properties a type carries, never what a property
+is.
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the property. This is the id you send in `properties` to attach it, and the `pk` you
+ use to detach it.
+
+- `name` _string_
+
+ Read-only companion to `display_name`. You never set it directly.
+
+- `display_name` _string_
+
+ The label shown wherever the property is rendered.
+
+- `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`.
+
+- `relation_type` _string_
+
+ For a `RELATION` property, what it 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. A property can be retired by setting this to `false` on the catalog
+ resource, 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. Manage them through
+ [Property options](/api-reference/v2/workspace-work-item-property-options/overview).
+
+- `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 record in another system
+ and find it again later. Either may be `null`.
+
+- `created_at` _string (date-time)_
+
+ When the property was created.
+
+::: tip There is no separate link object
+The response is the property, not a join record. If you need to know whether a given property is on a type,
+`GET …/properties/{pk}/` — a `404` means it is not attached, and a `200` means it is.
+:::
+
+
+
+
+
+
+```json
+{
+ "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",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-types/
+
+
+
+
+
+Define a work item type for the whole workspace. The type becomes available to projects working from the workspace list, so one call gives every team the same `Bug` or `Incident` rather than each project inventing its own.
+
+::: warning Workspace mode required
+This write only succeeds while the workspace manages work item types at the workspace level. In project mode it returns `409` with code `work_item_types_managed_at_project` — create the type on the project endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name for the type, for example `Incident`. Maximum 255 characters. Reusing a name that already exists in the workspace returns `409`.
+
+
+
+
+
+What this type is for. It is shown next to the type wherever someone picks it, so write it for the person choosing.
+
+
+
+
+
+Whether the type can be selected. Send `false` to create a type that exists but stays out of pickers until you are ready to roll it out.
+
+
+
+
+
+Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, and accepts `null`. Write-only — it is not returned on read, so keep your own mapping to the Plane `id`.
+
+
+
+
+
+The system `external_id` came from, for example `jira`. Maximum 255 characters, and accepts `null`. Write-only, like `external_id` — an `external_id` is only unique within its source, so record both.
+
+
+
+
+
+`is_default`, `is_epic`, `level`, and `logo_props` are read-only. A type created here is a standard work item type; promote it to the workspace default with [Mark a type as default](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ----------------------------------------------------------------------------------------- |
+| `400` | `invalid_request` | `name` is missing, empty, or longer than 255 characters. See `errors[]`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace types. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The type can't be created as requested — most often a name already in use. Read `detail`. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Incident",
+ "description": "Customer-facing outage that needs a response now",
+ "is_active": true,
+ "external_id": "10004",
+ "external_source": "jira"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Incident",
+ "description": "Customer-facing outage that needs a response now",
+ "is_active": True,
+ "external_id": "10004",
+ "external_source": "jira",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-types/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Incident",
+ description: "Customer-facing outage that needs a response now",
+ is_active: true,
+ external_id: "10004",
+ external_source: "jira",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a3f52d07-8e19-4c6b-92d4-0b7e15c8f326",
+ "name": "Incident",
+ "description": "Customer-facing outage that needs a response now",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Create the type on the project's work item types endpoint."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Remove a work item type from the workspace. Because the type is shared, the removal is felt by every project working from the workspace list — check what still uses it before you call this.
+
+A successful delete returns `204` with an empty body. There is nothing to parse; branch on the status code.
+
+::: warning Workspace mode required
+This write only succeeds while the workspace manages work item types at the workspace level. In project mode it returns `409` with code `work_item_types_managed_at_project`. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to delete.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The request can't be processed as sent. See `errors[]`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace types. |
+| `404` | `not_found` | No such type or workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The type can't be deleted in its current state — the response `detail` says why. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info A repeat delete returns 404
+Delete is not idempotent in its response: the second call for the same id returns `404 not_found`, because the type is already gone. Treat `404` on retry as success rather than as an error worth alerting on.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Delete the type on the project's work item types endpoint."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Retrieve one workspace-level type by id. Reach for this when you already hold a type id — from a work item's `type_id`, a webhook payload, or a stored mapping — and need its current name, description, or active flag.
+
+::: info Reads work in either mode
+Retrieval is unaffected by [work item type modes](/api-reference/v2/work-item-type-modes). A workspace type stays readable here even when the workspace manages types at the project level; only writes are mode-gated.
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to retrieve. A project-level type id returns `404` here — this endpoint only resolves types defined on the workspace.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's types. |
+| `404` | `not_found` | No such type or workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info No expansion, and no external ids
+Work item types don't accept `?expand=` — the response is the flat object shown here. `external_id` and `external_source` are write-only and never come back, so resolve a type by the Plane `id` you stored at create time.
+:::
+
+::: info Existence is never leaked
+A type outside your tenant returns `404`, not `403`. If a cached id starts returning `404`, re-read the workspace's set with [List workspace work item types](/api-reference/v2/workspace-work-item-types/list-workspace-work-item-types) rather than retrying.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "not_found",
+ "code": "not_found",
+ "detail": "No Issue Type matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/
+
+
+
+
+
+Return the workspace's work item types as a paginated list. This is where you resolve a type name such as `Bug` to the `id` you need — to set `type_id` on a work item, to attach properties to the type, or to hand to a project [import](/api-reference/v2/work-item-types/import-work-item-types).
+
+There is no project segment in the path: these are the types defined once for the whole workspace.
+
+::: info Reads work in either mode
+Listing is unaffected by [work item type modes](/api-reference/v2/work-item-type-modes). You can read the workspace list even while the workspace manages types at the project level — only writes are mode-gated.
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This endpoint takes ordering and pagination only — there are no filter or search parameters. A workspace's type list is short by design, so read a page and match on `name` or `id` in your own code.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `name` , `-name` — alphabetical, which is what you usually want for a picker
+- `level` , `-level` — the type's level in the work item hierarchy
+- `created_at` , `-created_at` — when each type was added
+- `id` , `-id`
+
+A value outside this list is not rejected — it quietly falls back to the default ordering. Check your spelling: a typo surfaces as a differently-sorted page, not as an error.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most workspaces define fewer than 20 types, so one page is usually the whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return on each row. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------ | ------------------------------------------------------------------------------------ |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's types. |
+| `404` | `not_found` | No such workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/?order_by=name&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "name", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "name", per_page: "50" });
+const response = await fetch(`https://api.plane.so/api/v2/workspaces/my-team/work-item-types/?${params}`, {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "5e8b0c19-7a4d-42f6-9b83-1c0d6e2f7a45",
+ "name": "Epic",
+ "description": "A large body of work spanning several work items",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": true,
+ "level": 1,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.512907Z"
+ },
+ {
+ "id": "9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914",
+ "name": "Task",
+ "description": "Standard unit of work",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.548221Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/mark-default/
+
+
+
+
+
+Promote a type to the workspace default — the type a work item gets when none is supplied. Exactly one type holds the flag, so marking this one clears it on the type that held it before.
+
+`is_default` is read-only on create and update, which is why this is its own call. **Send no body.**
+
+::: warning Workspace mode required
+This write only succeeds while the workspace manages work item types at the workspace level. In project mode it returns `409` with code `work_item_types_managed_at_project` — set the default on the project endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to make the default.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The type is identified entirely by `pk`; send an empty request.
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | The type can't be made default as requested. See `errors[]`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace types. |
+| `404` | `not_found` | No such type or workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The default can't be moved in the current state — the response `detail` says why. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914",
+ "name": "Task",
+ "description": "Standard unit of work",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.548221Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Mark the default on the project's work item types endpoint."
+}
+```
+
+
+
+
+
+
+
+## The work item type object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the type. This is the id you send as `type_id` on a work item, and the id you pass when importing types into a project.
+
+- `name` _string_
+
+ Display name, for example `Bug`. Maximum 255 characters.
+
+- `description` _string_
+
+ What this type is for. Shown next to the type wherever it is picked in Plane, so it is worth writing for the people choosing, not for your integration.
+
+- `is_active` _boolean_
+
+ Whether the type can currently be selected. Deactivating a type retires it from pickers without deleting it or touching the work items already using it.
+
+- `is_default` _boolean_
+
+ Whether this is the workspace's default type. Read-only on create and update — change it with [Mark a type as default](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+- `is_epic` _boolean_
+
+ Whether the type is an epic type. Read-only, and there is no body parameter for it: every type you create through this API is a standard work item type.
+
+- `level` _number_
+
+ The type's level in the work item hierarchy. Read-only, and one of the values you can sort by with `order_by`.
+
+- `logo_props` _any_
+
+ Free-form icon metadata Plane uses to render the type's badge. Managed in the app — read-only over the API.
+
+- `created_at` _string (date-time)_
+
+ When the type was created.
+
+::: info `external_id` is write-only
+You can send `external_id` and `external_source` when creating or updating a type so an import can correlate it with a record in your own system, but neither field comes back on read. Keep your own mapping from your id to the Plane `id`.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Rename a type, rewrite its description, or retire it with `is_active: false`. The edit lands once and every project working from the workspace list sees it — that is the point of managing types at the workspace level.
+
+The update is partial: omitted fields are left untouched, and omitting a field is not the same as sending `null`. There is no `PUT`.
+
+::: warning Workspace mode required
+This write only succeeds while the workspace manages work item types at the workspace level. In project mode it returns `409` with code `work_item_types_managed_at_project`. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to update.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional — send only what changes.
+
+
+
+
+
+New display name. Maximum 255 characters. Renaming is safe for integrations that key on `id`; anything matching on the old name breaks, which is a reason to key on `id`.
+
+
+
+
+
+New description of what the type is for.
+
+
+
+
+
+Send `false` to retire the type from pickers without deleting it — work items already classified with it keep their type. Send `true` to bring it back.
+
+
+
+
+
+Your system's identifier for this type. Maximum 255 characters. Send `null` to clear it. Write-only — it is not returned on read.
+
+
+
+
+
+The system `external_id` came from, for example `jira`. Maximum 255 characters. Send `null` to clear it. Write-only, like `external_id`.
+
+
+
+
+
+`is_default`, `is_epic`, `level`, and `logo_props` are read-only — sending them has no effect. To change which type is the default, call [Mark a type as default](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+
+
+
+
+### Response shaping
+
+
+
+
+
+Comma-separated list of fields to return. Unrequested keys are **omitted** from the response, not returned as `null`, so absent means "not requested" and `null` means "actually null". `id` always comes back whether or not you name it.
+
+Pass `all` for every requestable field. An unknown name is a `400` that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
+
+Requestable here: `created_at`, `description`, `id`, `is_active`, `is_default`, `is_epic`, `level`, `logo_props`, `name`.
+
+See [Sparse fields](/api-reference/v2/sparse-fields).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| `400` | `invalid_request` | An invalid value — for example a `name` over 255 characters. See `errors[]`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `402` | `payment_required` | The feature this endpoint belongs to isn't enabled on your plan, or is switched off. |
+| `403` | `forbidden` | Your role or token scope can't write workspace types. |
+| `404` | `not_found` | No such type or workspace, or it's outside your tenant. |
+| `406` | `not_acceptable` | The `Accept` header asks for a representation the API can't produce. |
+| `409` | `conflict` | The change collides with another type — most often a name already in use. |
+| `413` | `payload_too_large` | The request body is over the size limit. |
+| `415` | `unsupported_media_type` | The `Content-Type` isn't one this endpoint accepts. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Defect",
+ description: "A confirmed break in shipped behavior",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "conflict",
+ "code": "work_item_types_managed_at_project",
+ "detail": "This workspace manages work item types at the project level. Update the type on the project's work item types endpoint."
+}
+```
+
+
+
+
+
@@ -31,7 +31,7 @@ Deploy Plane on your infrastructure with Docker, Kubernetes, or other methods. C
-
+
180+ endpoints to manage projects, work items, cycles, modules, and more.
diff --git a/package.json b/package.json
index fb7e71c9..bad07c9c 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
"type": "module",
"scripts": {
"dev": "vitepress dev docs",
- "build": "(git fetch --unshallow || true) && vitepress build docs",
+ "build": "(git fetch --unshallow || true) && NODE_OPTIONS=--max-old-space-size=8192 vitepress build docs",
"preview": "vitepress preview docs",
"fix:format": "prettier --write .",
"check:format": "prettier --check .",
diff --git a/vercel.json b/vercel.json
index f1bdea82..24ff4e09 100644
--- a/vercel.json
+++ b/vercel.json
@@ -6,7 +6,7 @@
"headers": [
{
"key": "Link",
- "value": "; rel=\"describedby\"; type=\"text/plain\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\""
+ "value": "; rel=\"describedby\"; type=\"text/plain\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\""
},
{
"key": "X-Robots-Tag",
@@ -18,7 +18,11 @@
"redirects": [
{
"source": "/api-reference",
- "destination": "/api-reference/introduction"
+ "destination": "/api-reference/v2/introduction"
+ },
+ {
+ "source": "/api-reference/introduction",
+ "destination": "/api-reference/v2/introduction"
},
{
"source": "/api-reference/byoa/build-plane-app",
@@ -30,35 +34,39 @@
},
{
"source": "/api-reference/cycle-issue/overview",
- "destination": "/api-reference/cycle/overview"
+ "destination": "/api-reference/v1/cycle/overview"
},
{
"source": "/api-reference/cycle-issue/add-cycle-issue",
- "destination": "/api-reference/cycle/add-cycle-work-items"
+ "destination": "/api-reference/v1/cycle/add-cycle-work-items"
},
{
"source": "/api-reference/cycle-issue/list-cycle-issues",
- "destination": "/api-reference/cycle/list-cycle-work-items"
+ "destination": "/api-reference/v1/cycle/list-cycle-work-items"
},
{
"source": "/api-reference/cycle-issue/delete-cycle-issue",
- "destination": "/api-reference/cycle/remove-cycle-work-item"
+ "destination": "/api-reference/v1/cycle/remove-cycle-work-item"
},
{
"source": "/api-reference/module-issue/overview",
- "destination": "/api-reference/module/overview"
+ "destination": "/api-reference/v1/module/overview"
},
{
"source": "/api-reference/module-issue/add-module-issue",
- "destination": "/api-reference/module/add-module-work-items"
+ "destination": "/api-reference/v1/module/add-module-work-items"
},
{
"source": "/api-reference/module-issue/list-module-issues",
- "destination": "/api-reference/module/list-module-work-items"
+ "destination": "/api-reference/v1/module/list-module-work-items"
},
{
"source": "/api-reference/module-issue/delete-module-issue",
- "destination": "/api-reference/module/remove-module-work-item"
+ "destination": "/api-reference/v1/module/remove-module-work-item"
+ },
+ {
+ "source": "/api-reference/:path((?!v1/|v2/).*)",
+ "destination": "/api-reference/v1/:path"
},
{
"source": "/plane-one/governance/authentication/custom-sso",