Areas

List areas

GET /v1/organizations/:orgRef/products/:productSlug/areas

Required role: Member.

Query parameters:

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`).
`pageSize`	`integer`	Results per page (default: `20`, max: `100`).
`all`	`"true" \| "false"`	When `"true"`, returns every matching area in one response and ignores `page` and `pageSize`.
`archived`	`"true" \| "false"`	Filter by archive state. Defaults to active areas.
`importance`	`string`	Comma-separated list of `high`, `normal`, `low`.
`type`	`string`	Comma-separated list of `page`, `template`, `component`, `process`, `feature`.
`riskFactor`	`string`	Comma-separated list of risk factors. Matches areas with any of them.
`owner`	`string`	Comma-separated list of user IDs. Use `unassigned` to match areas with no responsible person.
`q`	`string`	Searches area names and labels. Max 100 characters.
`sortField`	`"name" \| "createdAt" \| "importance" \| "manual"`	Field to sort by (default: `"name"`). `"manual"` uses the product’s custom area order.
`sortDirection`	`"asc" \| "desc"`	Sort direction (default: `"asc"`). Ignored for `"manual"`.
`includeOpenIssueCount`	`"true" \| "false"`	With `all=true`, set to `"true"` to include `openIssueCount`. Without it, `openIssueCount` is `0` in that mode. Paginated responses always include it.

Risk factor values: financial, legal, authentication, health-safety, irreversible-actions, data-visualization, multimedia, motion, custom-widget, documents, third-party, user-generated-content, time-limits.

Response:

{
  "areas": [
    {
      "id": "...",
      "name": "Checkout",
      "slug": "checkout",
      "type": "page",
      "importance": "high",
      "sortOrder": 10,
      "productId": "...",
      "responsiblePersonId": "...",
      "responsiblePersonName": "Sam Lee",
      "responsiblePersonEmail": "sam@example.com",
      "responsiblePersonImage": null,
      "openIssueCount": 3,
      "labels": ["checkout", "payments"],
      "riskFactors": ["financial"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "archivedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  }
}

The responsiblePerson* fields are null when the area has no responsible person. labels are the provider labels that link imported issues to the area.

Create an area

POST /v1/organizations/:orgRef/products/:productSlug/areas

Required role: Admin or owner.

Cannot create an area in an archived product — returns 409 Conflict.

Request body:

Field	Type	Required	Description
`name`	`string`	Yes	Area name. Must contain at least one letter or number.
`type`	`"page" \| "template" \| "component" \| "process" \| "feature"`	No	Defaults to `"page"`.
`importance`	`"high" \| "normal" \| "low"`	No	Defaults to `"normal"`.
`riskFactors`	`string[]`	No	Risk factors from the list under List areas.
`labels`	`string[]`	No	Provider labels that link imported issues to this area. Up to 50, each up to 100 characters. Matched case-insensitively.
`responsiblePersonId`	`string \| null`	No	User ID of the responsible person. Must be a member of the organization.

Returns 201 Created with a Location header.

Get an area

GET /v1/organizations/:orgRef/products/:productSlug/areas/:areaSlug

Required role: Member.

Returns archived areas too.

Response:

{
  "area": {
    "id": "...",
    "name": "Checkout",
    "slug": "checkout",
    "type": "page",
    "importance": "high",
    "sortOrder": 10,
    "productId": "...",
    "responsiblePersonId": "...",
    "labels": ["checkout", "payments"],
    "riskFactors": ["financial"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "archivedAt": null
  }
}

Unlike the list, this doesn’t include openIssueCount or the responsible person’s name, email, or image.

Update an area

PATCH /v1/organizations/:orgRef/products/:productSlug/areas/:areaSlug

Required role: Admin or owner.

Request body (all fields optional):

Field	Type	Description
`name`	`string`	New name. Regenerates the slug.
`type`	`"page" \| "template" \| "component" \| "process" \| "feature"`	Area type.
`importance`	`"high" \| "normal" \| "low"`	Importance.
`riskFactors`	`string[]`	Replaces the area’s risk factors.
`labels`	`string[]`	Replaces the area’s labels.
`responsiblePersonId`	`string \| null`	Responsible person. `null` clears it.

Reorder areas

PATCH /v1/organizations/:orgRef/products/:productSlug/areas/reorder

Required role: Admin or owner.

Sets the product’s custom area order, used when listing with sortField=manual.

Request body:

Field	Type	Required	Description
`areaIds`	`string[]`	Yes	IDs of every active area in the product, in the new order. No duplicates. Archived areas are left out.

Returns { "areas": [...] } with the product’s active areas in their new order.

Returns 409 Conflict if the product is archived, or if areaIds doesn’t match the product’s current active areas exactly (for example, because an area was added or archived since you fetched the list). Fetch the list again and retry.

Delete an area

DELETE /v1/organizations/:orgRef/products/:productSlug/areas/:areaSlug

Required role: Admin or owner.

Permanently deletes the area. Issues tagged with this area lose the association. Returns 204 No Content.

Archive an area

POST /v1/organizations/:orgRef/products/:productSlug/areas/:areaSlug/archive

Required role: Admin or owner.

Idempotent — archiving an already-archived area succeeds.

Unarchive an area

POST /v1/organizations/:orgRef/products/:productSlug/areas/:areaSlug/unarchive

Required role: Admin or owner.

Returns 409 Conflict if the parent product is still archived.