Template categories overview

Template categories group templates by subject, such as engineering or marketing. Plane authors and maintains them, and the API exposes them read-only.

The catalog is global. Its routes sit at /api/v2/template-categories/, with no workspace in the path, and every workspace sees the same categories. POST, PATCH, and DELETE on these routes return 405 method_not_allowed.

Project templates list their categories in category_ids, and List project templates filters on them with ?category_id= and ?category_id__in=. Tagging a template with a category isn't available through the API.

The template category object

Attributes

• id string (uuid)

  Unique identifier for the category. This is the value in a project template's category_ids.

• name string

  Display name, unique across the catalog. Maximum 255 characters.

• slug string

  URL-safe key, unique across the catalog. Maximum 48 characters. Filter on it with ?slug=.

• description string

  What the category covers.

• logo_props object

  Editor-owned descriptor for the category icon.

• sort_order number

  Display position. Lower values sort first, and the list sorts on it by default.

• is_active boolean

  Whether the category is in use. Inactive categories are left out of reads unless you ask for them. See Inactive categories.

• created_at string (date-time)

  When the category was created.

• updated_at string (date-time)

  When the category was last updated.

• updated_by_id string (uuid)

  The user who last updated the category. Usually null, because Plane seeds the catalog.

Response200

{
  "id": "0c6e2a8f-4d1b-4e93-b7a5-9f3c1d8e2b60",
  "name": "Engineering",
  "slug": "engineering",
  "description": "Templates for software teams",
  "logo_props": {},
  "sort_order": 10000.0,
  "is_active": true,
  "created_at": "2025-11-04T08:15:27.640912Z",
  "updated_at": "2025-11-04T08:15:27.640912Z",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/template-categories/	List template categories
GET	/api/v2/template-categories/{pk}/	Get a template category

Inactive categories

Reads return active categories only, unless the request has an is_active query parameter:

• No is_active: active categories only.
• ?is_active=false: inactive categories only.
• ?is_active=true: active categories only, the same as the default.

The same rule applies to Get a template category. An inactive category's id returns 404 unless you add ?is_active=false.

Access

Any authenticated caller can read the catalog. An OAuth token needs template_categories:read or the global read scope. There is no workspace to check membership against and no feature gate, so a workspace's plan doesn't affect these endpoints.

Response shaping

Every read accepts ?fields= for sparse responses. See Sparse fields. Nothing is deferred on list rows. Errors follow the shared problem+json contract.

Changed from v1

• v2 adds Get a template category. v1 had only the list.
• The list is paginated, filterable, searchable, and sortable. v1 returned every active category in one array.
• v1 always hid inactive categories. v2 hides them by default and returns them with ?is_active=false.

See Migrating from v1 for the full list.