Task Management

Overview

Tasks are the core work units in Xenia. Through a client key you can both read and write your workspace’s tasks: browse the grouped catalog, run a filtered/paginated list, fetch the full details of a single task, and create, edit, re-status or delete tasks. New tasks can be assigned to users, teams or locations, or to roles — the same targeting the web app offers — and can be created as recurring projects. See Assigning work.

Authentication & base URL

All requests go to https://api.xenia.team and every path starts with /api/v1. Authenticate with your client credentials (see Client Key Setup):

x-client-key: <your-client-key>
x-client-secret: <your-client-secret>
x-client-user: <optional-user-id>   # act as a specific workspace user

The workspace is derived from the key, so the {workspaceId} in each path must be your key’s own workspace. Always include the /workspaces/{workspaceId} segment — the unscoped task variants are not available to API keys (calling them returns 403). Each route also enforces the key user’s permission — reads require the key’s default-user role to grant access to the tasks/work-order surface, and writes require the permissions listed under Permissions.

Responses use Xenia’s standard envelope: a data payload plus a meta object. There is no status, statusCode, success, or requestId field, and successful POST calls return HTTP 200. Long queries are bounded by an ALB timeout of roughly 60 seconds, so narrow your filters/pagination on large workspaces.

Task Catalog

Return the grouped catalog of tasks with per-group counts — the same data that powers the Tasks board. Filters and pagination are supplied in the request body (every field is optional). Endpoint: POST /api/v1/ops/workspaces/{workspaceId}/tasks/catalog

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/catalog" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "searchText": "safety",
    "hideCompleted": true,
    "groupBy": "WorkspaceId",
    "orderBy": "createdAt",
    "orderDirection": "DESC",
    "limit": 150,
    "offset": 0,
    "viewType": "current"
  }'

Request Body (all optional):

Field	Type	Default	Description
`searchText`	string	`""`	Match task title/description
`hideCompleted`	boolean	—	Exclude completed tasks
`groupBy`	string	`"WorkspaceId"`	Grouping dimension for the counts/rows
`orderBy`	string	`"createdAt"`	Sort field
`orderDirection`	string	`"DESC"`	`ASC` or `DESC`
`view`	string	`"list"`	View mode
`viewType`	string	`"current"`	`"current"` or `"all"` (includes scheduled tasks)
`limit`	number	`150`	Page size
`offset`	number	`0`	Rows to skip
`advanceFilters`	object	—	`{ "filters": [...] }` advanced filter tree

Response:

{
  "data": {
    "counts": [
      { "group": "Open", "count": 25 },
      { "group": "Completed", "count": 156 }
    ],
    "tasks": [
      {
        "id": "task-uuid-1",
        "title": "Weekly Safety Inspection",
        "taskStatus": "Open",
        "priority": "High",
        "dueDate": "2024-12-20T17:00:00Z",
        "taskNumber": 1234
      }
    ],
    "apiTime": { "count": 12, "list": 34, "total": 46 }
  },
  "meta": {}
}

Task List

A flat, filtered, paginated list of tasks. Returns a total count plus the matching rows. Endpoint: POST /api/v1/ops/workspaces/{workspaceId}/tasks/list

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/list" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 100,
    "searchText": "safety",
    "taskStatus": ["Open", "In Progress"],
    "priority": ["High", "Medium"],
    "taskLocations": ["location-uuid"],
    "taskCategories": ["service-type-uuid"],
    "fromDate": "2024-12-01",
    "toDate": "2024-12-31",
    "sort": { "dueDate": "ASC" }
  }'

Request Body (all optional):

Field	Type	Default	Description
`offset`	number	`0`	Rows to skip
`limit`	number	`100`	Page size
`sort`	object	—	Sort clause, e.g. `{ "dueDate": "ASC" }`
`searchText`	string	—	Match title/description
`taskStatus`	string[]	—	Filter by status(es)
`priority`	string[]	—	Filter by priority
`taskLocations`	string[]	—	Filter by location IDs
`taskAssets`	string[]	—	Filter by asset IDs
`taskCategories`	string[]	—	Filter by service-type (category) IDs
`taskType`	object	—	e.g. `{ "recurringTask": true }`
`taskIds`	string[]	—	Restrict to specific task IDs
`fromDate` / `toDate`	string	—	Date range (YYYY-MM-DD)
`hideCompleted`	boolean	—	Exclude completed tasks
`advanceFilters`	object	—	Advanced filter tree

Add ?count=true to the URL to run a count-only query; the response is then { "data": { "count": 45 }, "meta": {} }.

Response:

{
  "data": {
    "count": 45,
    "rows": [
      {
        "id": "task-uuid-1",
        "title": "Weekly Safety Inspection",
        "taskStatus": "Open",
        "priority": "High",
        "dueDate": "2024-12-20T17:00:00Z",
        "taskNumber": 1234
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "total": 45
  }
}

Task Details

Fetch the full detail object for a single task, including its assignees, location, asset, attached checklist/submission, and creator. Endpoint: GET /api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/details

curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/details" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "data": {
    "id": "task-uuid",
    "title": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "taskStatus": "In Progress",
    "priority": "High",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "taskNumber": 1234,
    "taskUniqueId": "T-1234",
    "isChecklistRequired": true,
    "attachment": ["https://storage.xenia.team/attachment.pdf"],
    "Creator": { "id": "creator-uuid", "firstName": "Jane", "lastName": "Doe" },
    "Location": { "id": "location-uuid", "name": "Building A" },
    "Asset": { "id": "asset-uuid", "name": "Fire Extinguisher #42" },
    "ServiceType": { "id": "service-type-uuid", "type": "Safety" },
    "Checklist": { "id": "checklist-uuid", "name": "Safety Checklist", "itemsCount": 12 },
    "ChecklistLog": { "id": "submission-uuid", "status": "InProgress" },
    "TaskAssignees": [
      {
        "Assigned": { "id": "user-uuid", "firstName": "John", "lastName": "Smith" },
        "Team": null,
        "Role": null,
        "Location": { "id": "location-uuid", "name": "Building A" }
      }
    ],
    "vendorId": null,
    "createdAt": "2024-12-19T10:00:00Z"
  },
  "meta": {}
}

The path parameter is the task ID. The details payload is a serialized task record with many associations (Creator, Finisher, Location, Asset, ServiceType, Checklist, ChecklistLog, TaskAssignees, time logs, work-order costs, and more). Which fields are present depends on the task type and what is set on the task.

Create a Task

Create one or more tasks. title is the only required field. Endpoint: POST /api/v1/ops/workspaces/{workspaceId}/tasks

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reset the endcap planogram",
    "description": "Swap in the new seasonal set",
    "priority": "High",
    "assignees": ["8f1c...user-id", "3ab9...team-id"],
    "locationIds": ["5fb5a0c0-1d2d-4260-ac7d-33d0576ead0e"],
    "dueTime": "2026-08-04T17:00:00-04:00",
    "checklistId": "c0b0e7cb-1202-4b7b-8e70-fbb8104126ba"
  }'

Request Body:

Field	Type	Required	Description
`title`	string	yes	Task title
`description`	string	no	Task description
`additionalDescription`	string	no	Extra description block
`priority`	string	no	Task priority
`assignees`	string[]	no	User, team or location ids — see Assigning work
`assigneesRoles`	object	no	Role-based targeting — mutually exclusive with `assignees`
`locationIds`	string[]	no	Locations to tag the task to
`checklistId`	string	no	Template to attach to the task
`serviceTypeId`	string	no	Task category / service type
`attachment`	string[]	no	Attachment keys
`startTime`	string	no	ISO-8601 start; include the offset
`dueTime`	string	no	ISO-8601 due; include the offset
`endDate`	string	no	End of the schedule window for recurring work
`dateFrom`	string	no	Earliest date the task may start
`taskStatus`	string	no	Starting status; defaults to `Open`
`isTimeBound`	boolean	no	Defaults to `false`
`recurringTask`	boolean	no	Recurring schedule
`instanceCadence`	object	no	Cadence for a recurring schedule
`isMultiTasks`	boolean	no	Create one separate task per assignee
`isAutoTagLocation`	boolean	no	Derive `locationIds` from each assignee
`isProject`	boolean	no	Create a recurring project instead of a one-off task
`projectType`	string	no	`user`, `asset` or `role` — required shape when `isProject` is `true`

Timestamps are parsed with the offset you send, so always include one (-04:00, Z, …). A dueTime in the past on a non-recurring task is adjusted forward rather than rejected. startDate is derived from startTime/dueTime and your workspace’s working hours — sending it has no effect.

Successful calls return HTTP 200 with the created task(s) in data and the message Task(s) Created.

Assigning work

assignees is a single array that accepts user ids, team ids and location ids interchangeably — Xenia resolves each id to the right kind of target. This mirrors the assignee picker in the web app. Role-based assignment uses a separate field, assigneesRoles, and the two are mutually exclusive: send assignees or assigneesRoles, never both.

Assign to users, teams and/or locations

{
  "title": "Weekly cooler audit",
  "assignees": ["8f1c...user-id", "3ab9...team-id", "5fb5...location-id"]
}

Assign by role

{
  "title": "Weekly cooler audit",
  "assigneesRoles": {
    "roles": ["7c2d...role-id"],
    "creationType": "user",
    "locations": ["5fb5...location-id"]
  }
}

Set "isMultiTasks": true to fan a single request out into one separate task per assignee rather than one shared task with several assignees. To resolve the ids these fields need, use the discovery endpoints:

Target	Endpoint
Users	`GET /api/v1/mgt/workspaces/{workspaceId}/users`
Teams	`GET /api/v1/mgt/workspaces/{workspaceId}/teams`
Locations	`GET /api/v1/mgt/workspaces/{workspaceId}/locations`
Roles	`GET /api/v1/mgt/workspaces/{workspaceId}/roles`

Recurring projects

Setting "isProject": true creates a recurring project — a schedule that generates task instances over time — instead of a single task. Pass projectType as user, asset or role, and supply the matching target: assignees for user, assets for asset, assigneesRoles.roles for role. Projects require the Projects feature on your workspace. The response returns immediately while the schedule is generated in the background, so the project’s task instances appear shortly after the call succeeds. Once created, a project can be read, analysed, paused, resumed and ended over the API — see the Project Management guide.

Edit a Task

Endpoint: POST /api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/edit Send only the fields you want to change; the body accepts the same fields as create.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/edit" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "Low", "dueTime": "2026-08-06T17:00:00-04:00" }'

Change Task Status

Endpoint: PATCH /api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/status

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/status" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Completed" }'

Request Body:

Field	Type	Required	Description
`status`	string	yes	`Open`, `In Progress`, `On Hold`, `Paused` or `Completed`

This endpoint takes status, not taskStatus. taskStatus is the field name used when creating a task — sending it here will not change the status.

Archived tasks and not-yet-activated (planned) tasks reject status changes.Setting Completed on a task that requires a template submission returns 405 “Completion of template is required to finish this task” until the attached template has actually been submitted. Complete the submission first, then set the status.

Delete a Task

Endpoint: DELETE /api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}

curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Deleting a task is not reversible through the API. Guard bulk scripts carefully — a loop over a task list can remove a lot of work in one pass.

Permissions

Each write route enforces the key’s default-user role (or the user named in x-client-user):

Operation	On a task	On a work order
Create	Manage Tasks	— (not available to API keys)
Edit	Manage Tasks	Manage Work Orders
Change status	Change Task Status	Change Work Order Status
Delete	Manage Tasks	Manage Work Orders

The permission required depends on the kind of record, not on which one you happen to hold: holding Manage Tasks does not let you edit or delete a work order, and vice versa. Status changes carry one extra rule. Without Change Status of Others’ Tasks (or …Others’ Work Orders), a key can only re-status records it is assigned to — where “assigned” matches the key user’s own id, any of their teams, any of their locations, or their role. Grant the “others’” permission to the key’s default user if your integration needs to re-status work across the workspace. Creating a task also requires an active subscription and available capacity under your plan’s task limit.

What you can’t do via API key

These task operations exist in Xenia but are not reachable with a client key (they return 403 Forbidden: API key not authorized for this route). Use the web/mobile app or a signed-in user session for them:

Create a work order (/tasks/work-orders)
Bulk task updates and CSV export
Archive a recurring series
Claim, return or reassign an existing task’s assignees individually
Work-order costs

Assignees can still be set when you create a task, or replaced by editing it — only the per-assignee add/remove routes are closed. For reporting and export needs, use the read-only reporting surface instead.

Data Extraction & Reporting — task analytics, grid reports, and BI integration
Submission Exports — PDF/Excel/spreadsheet exports
User Lifecycle — manage the users tasks are assigned to

Getting Started

Workflows

Integrations

Overview

Authentication & base URL

Task Catalog

Task List

Task Details

Create a Task

Assigning work

Recurring projects

Edit a Task

Change Task Status

Delete a Task

Permissions

What you can’t do via API key

​Overview

​Authentication & base URL

​Task Catalog

​Task List

​Task Details

​Create a Task

​Assigning work

​Recurring projects

​Edit a Task

​Change Task Status

​Delete a Task

​Permissions

​What you can’t do via API key

​Related Guides

Overview

Authentication & base URL

Task Catalog

Task List

Task Details

Create a Task

Assigning work

Recurring projects

Edit a Task

Change Task Status

Delete a Task

Permissions

What you can’t do via API key

Related Guides