# Operational Work Items API

Work items provide a separate operational workflow for follow-up work attached to existing Tradly records. For example, a laundry business can link a work item to an order and move it through its configured states without changing the order's payment or fulfilment status.

All examples use Bearer authentication. Tenant and user identity are resolved from the authenticated request by the gateway; do not send separate identity headers.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Access and privacy

Tenant administrators can create, edit, assign, and link work items. A non-admin user can list and read only work assigned to that user or their active staff profile. Only tenant administrators can filter the list by another assignee. Source links and assignees are validated against the same tenant.

Supported linked objects are `order`, `listing`, `transaction`, `account`, and `form_submission`. A relation is `primary`, `related`, or `duplicate`. An assignee is either `user` or `staff`; for a staff assignee, `assignee_id` is the staff profile ID.

## Create and assign a work item

`POST /v1/work-items`

Tenant-admin only. `title` is required (maximum 255 characters). Optional fields include `description`, `category_id`, `priority` (`low`, `normal`, `high`, or `urgent`), `due_at`, `assignee_type`, `assignee_id`, and `links`. The initial status comes from the tenant's active operational-work-item workflow; it is not supplied in the create request.

Categories, when used, must be active categories with type `operational_work_items` in this tenant. If no initial workflow step is configured, creation returns `503`.

```bash
curl -X POST "$API/v1/work-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "title": "Wash and prepare order",
    "description": "Customer requested wash, press, and same-day pickup.",
    "priority": "high",
    "due_at": "2026-12-10T16:00:00Z",
    "assignee_type": "staff",
    "assignee_id": 12,
    "links": [
      {"object_type": "order", "object_id": 6563, "relation": "primary"}
    ]
  }'
```

The response contains `data.work_item`, its `links`, and `status_history`.

## List and retrieve work

`GET /v1/work-items`

Optional filters: `page` (default `1`), `per_page` (default `20`, maximum `100`), `status`, `priority`, `category_id`, `assignee_type` + `assignee_id`, and `object_type` + `object_id`. Assignee filtering is admin-only. Linked-object filters must be supplied together.

```bash
curl "$API/v1/work-items?object_type=order&object_id=6563&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
```

`GET /v1/work-items/{id}` returns one work item. Both list and detail enforce the assignment-based visibility rule for non-admin users.

## Edit and reassign

`PATCH /v1/work-items/{id}`

Tenant-admin only. Supply any fields to change: `title`, `description`, `priority`, `due_at`, `category_id`, `assignee_type`, or `assignee_id`. To clear a due date or category/assignee, send `null` where supported. Assignee type and ID must identify an active same-tenant user or staff profile.

## Change status

`PATCH /v1/work-items/{id}/status`

An admin or assigned user/staff can request a status transition. `status` must be a step in the active operational workflow and the transition must be allowed by that workflow. `note` is optional and is recorded in status history.

```bash
curl -X PATCH "$API/v1/work-items/901/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{"status":"in_progress","note":"Started processing the order"}'
```

Replace `in_progress` with a status configured in the tenant's workflow; status values are not a fixed API enum.

## Manage links and history

`POST /v1/work-items/{id}/links` — tenant-admin only; body fields: `object_type`, `object_id`, and optional `relation` (defaults to `related`). Repeating a link updates its relation rather than creating a duplicate.

`DELETE /v1/work-items/{id}/links/{link_id}` — tenant-admin only.

`GET /v1/work-items/{id}/history` — returns status changes in chronological order; visible to tenant admins and assigned users/staff.

The backend also has an archive handler, but the current public gateway template does not expose `DELETE /v1/work-items/{id}`. It is intentionally not listed as a callable public endpoint here.

## Endpoint summary

| Method | Endpoint | Access | Purpose |
|---|---|---|---|
| `GET` | `/v1/work-items` | Tenant user | List visible work items |
| `POST` | `/v1/work-items` | Tenant admin | Create and optionally assign work |
| `GET` | `/v1/work-items/{id}` | Admin or assignee | Retrieve one item |
| `PATCH` | `/v1/work-items/{id}` | Tenant admin | Edit or reassign |
| `PATCH` | `/v1/work-items/{id}/status` | Admin or assignee | Transition status |
| `POST` | `/v1/work-items/{id}/links` | Tenant admin | Link an existing record |
| `DELETE` | `/v1/work-items/{id}/links/{link_id}` | Tenant admin | Remove a link |
| `GET` | `/v1/work-items/{id}/history` | Admin or assignee | Read status history |

## Related APIs

- [Orders](orders) — the underlying customer order remains on its existing lifecycle.
- [Categories](categories) — work-item categories use the `operational_work_items` type.

Configure the active work-item statuses and transitions in the tenant's Approval Engine before using the status endpoint. The approval-engine configuration itself does not yet have a dedicated page in this API reference.