Practice tasks

GET /tasks and GET /tasks/{id} use the shared authorised task read service. The live organisation key must explicitly have read_tasks; existing keys are not updated. This grants practice-wide task reads, not a staff user's “my tasks” view. A client-supplied user ID is a filter, never delegated authority. No MCP permission or FHIR conformance is implied.

List accepts limit (default 20, maximum 100), offset (maximum 100000), patient_id, assignee_user_id, assignee_team_id, parent_task_id, status, urgency, due_at_gte and due_at_lte. Choose at most one assignment filter. Dates are UTC instants in YYYY-MM-DDTHH:mm:ssZ form. Repeated, empty or unknown parameters and inverted dates return 422. Unavailable filter references return 404, even for empty lists. Get takes a UUID and rejects query parameters.

Sort is created_at DESC, id DESC. A lookahead determines has_more and next_offset. Offset pagination is not an export snapshot under concurrent changes. Lists include subtasks, tasks without patients, completed tasks, archived tasks and snoozed tasks by default. Native states are open, in_progress, completed, and cancelled (the UI's “Archived”). Unknown states are excluded. completed_at, due_at and snoozed_until remain separate facts; the API neither computes a current work queue nor silently repairs inconsistent legacy status/date combinations. Snoozing does not alter the due date.

Response fields are task ID/number, patient ID, title, description, category, status, urgency, assignment IDs, parent ID, dates, and native version. Instructions can contain patient information, so both operations require the dedicated task grant and successful responses use Cache-Control: no-store. Title and description are bounded to 1000 and 20000 characters; oversized legacy records fail closed instead of silently truncating instructions.

The task, optional patient, assignee membership/team and parent task must belong to the authorised practice. References are batch-checked for each page before projection, including its lookahead. Historical assignee membership is checked for practice ownership without treating it as current staff authority. User profiles, arbitrary linked entities, import/retry internals, comments, activity and consultation context are not returned by this increment. Patient portal patient_tasks, their action links and configuration are a separate model.

Example: GET /tasks?patient_id=16249000-0000-4000-8000-000000000003&status=open&limit=20. List returns {data: [...], meta: {request_id, limit, has_more, next_offset}}; get returns {data: {...}, meta: {request_id}}. First-party request logs retain machine-key and practice attribution. Third-party analytics use the fixed /api-v1/tasks label without task IDs or query filters. The broader analytics fix remains #15496.

No creation, completion, snooze, reassignment or deletion action is implemented. Final CI, security/clinical assessment and deployed reference-query/staging acceptance remain pending; the draft PR does not establish release availability.

curl -X GET "https://example.com/tasks"

{  "data": [    {      "id": "string",      "task_number": "string",      "patient_id": "string",      "title": "string",      "description": "string",      "category": "string",      "status": "open",      "urgency": "routine",      "assignee_user_id": "string",      "assignee_team_id": "string",      "parent_task_id": "string",      "due_at": "string",      "snoozed_until": "string",      "completed_at": "string",      "created_at": "string",      "updated_at": "string",      "version": 0    }  ],  "meta": {    "request_id": "string",    "limit": 0,    "has_more": true,    "next_offset": 0  }}

curl -X GET "https://example.com/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "string",    "task_number": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "category": "string",    "status": "open",    "urgency": "routine",    "assignee_user_id": "string",    "assignee_team_id": "string",    "parent_task_id": "string",    "due_at": "string",    "snoozed_until": "string",    "completed_at": "string",    "created_at": "string",    "updated_at": "string",    "version": 0  },  "meta": {    "request_id": "string"  }}