API V2 Route: Tasks
Last updated: October 5, 2026
General Details:
| Endpoint |
/api/v2/tasks, /api/v2/tasks/<id>, and /api/v2/tasks/<id>/comments
|
| Headers | Authorization: <JWT> |
| HTTP Methods |
GET, POST
|
GET Details:
| Request Body Format | N/A |
| Response Body Format | JSON |
| Required Scopes | TASKS_GET |
Supported Request Filters:
These filters should be query parts in the URL string and follow the standard pattern of <baseUrl>?<key>=<filter>&...
| Field Name | Filter Type | Notes |
|---|---|---|
createdAt |
date or Date Filter | An ISO date string or a complex Date Filter can be utilized |
dueAt |
date or Date Filter | An ISO date string or a complex Date Filter can be utilized |
category |
string or String Filter | The Task Category name |
title |
string or String Filter | |
status |
string | TaskStatus |
priority |
string | TaskPriority |
API Response:
| Field Name | Data Type | Notes |
|---|---|---|
id |
string | Globally unique identifier |
title |
string | |
dateCreated |
date string | ISO Date string |
dateDue |
date string | ISO Date string |
tags |
string[] | An array of Tag Captions |
status |
TaskStatus | |
priority |
TaskPriority | |
category |
CategoryThin | |
creator |
ProfileThin | |
assignment |
TaskAssignment | |
response |
TaskResponse* | *See below for type |
TaskResponse
| Field Name | Data Type | Notes |
|---|---|---|
type |
enum: individual or form
|
|
answer |
{ answer: string } or FormSubmission
|
The answer object is dependent on the response type |
POST Details:
| Request Body Format | JSON |
| Response Body Format | JSON |
| Required Scopes | TASKS_POST |
POST Behavior:
Housing.Cloud will create or update the Task entity based on the existence (or lack thereof) of an id.
POST API Request Body:
Housing.Cloud supports batch creation, as such every POST payload should contain an array of objects with the following structure:
| Field Name | Data Type | Required | Notes |
|---|---|---|---|
id |
string or null | No | Unique value of the task used to determine operation |
title |
string | Yes | |
isSensitive |
boolean | No | |
dateDue |
date string | No | ISO Date string |
tags |
string[] | No | A list of comma separated Tag Captions |
status |
TaskStatus | Yes | |
priority |
TaskPriority | Yes | |
categoryId |
string | Yes | Unique id of the Task Category |
creatorId |
string | Yes | Unique id of Profile whom is the original creator |
assignment |
PostTaskAssignment or null | No |
PostTaskAssignment:
| Field Name | Filter Type | Notes |
|---|---|---|
profileId |
string or null | Unique id of Profile whom the task is assigned to |
roleId |
string or null | Unique id of Role whom the task is assigned to |
If neither are provided, the system will utilize the Task Category auto-assignment mechanism.
POST Comments Details:
Adds one or more comments or internal notes to an existing Task.
| Endpoint | /api/v2/tasks/<id>/comments |
| Request Body Format | JSON |
| Response Body Format | JSON |
| Required Scopes | TASK_COMMENTS_POST |
POST Comments Behavior:
Each entry is added to the Task identified by <id> in the URL path. A public comment (isPublic: true, the default) is visible to the task's creator, assignee, and followers; an internal note (isPublic: false) is visible to staff only. Comments created this way behave exactly like comments authored in the app — followers and assignees are notified and the action is recorded on the task's timeline. A request against a Task that does not exist returns 404.
POST Comments API Request Body:
Housing.Cloud supports batch creation, as such every POST payload should contain an array of objects with the following structure:
| Field Name | Data Type | Required | Notes |
|---|---|---|---|
text |
string | Yes | The comment body |
creatorId |
string | Yes | Unique id of the Profile authoring the comment |
isPublic |
boolean | No | Defaults to true (public comment). Set false for a staff-only internal note |
isSensitive |
boolean | No | Defaults to false
|
POST Comments API Response:
| Field Name | Data Type | Notes |
|---|---|---|
numTotal |
number | Total number of comments in the request |
numSuccess |
number | Number successfully created |
numErrors |
number | Number that failed |
errors |
array or null | Per-entity errors when any fail |
GET Comments Details:
Reads the comments and internal notes attached to an existing Task.
| Endpoint | /api/v2/tasks/<id>/comments |
| Request Body Format | N/A |
| Response Body Format | JSON |
| Required Scopes | TASK_COMMENTS_GET |
| Optional Scopes | TASK_COMMENTS_SENSITIVE_GET |
GET Comments Behavior:
Returns the notes on the Task identified by <id> in the URL path, oldest first — the order the thread reads in. Results are paged with the standard offset and limit query parts; limit defaults to 1000 and is capped at 1000. Internal notes are included and identified by isPublic: false; the same credential can already create them with TASK_COMMENTS_POST. A request against a Task that does not exist, or that belongs to another tenant, returns 404. A non-numeric <id> returns 400.
GET Comments Visibility:
With only TASK_COMMENTS_GET, notes flagged sensitive are omitted from the response entirely. They are not redacted placeholders and they do not consume a page slot — so a page returning fewer rows than limit does not mean you have reached the end of the collection. Page until you receive an empty page.
Granting TASK_COMMENTS_SENSITIVE_GET alongside TASK_COMMENTS_GET returns those notes inline in the same collection, flagged isSensitive: true. isSensitive is always present on every comment; for a key without the sensitive scope it is always false.
TASK_COMMENTS_SENSITIVE_GET is not sufficient on its own — a key holding it without TASK_COMMENTS_GET receives 403.
Supported Request Filters:
These filters should be query parts in the URL string and follow the standard pattern of <baseUrl>?<key>=<filter>&...
| Field Name | Filter Type | Notes |
|---|---|---|
createdAt |
date or Date Filter | An ISO date string or a complex Date Filter can be utilized |
creatorId |
string | Unique id of the Profile authoring the comment |
GET Comments API Response:
| Field Name | Data Type | Notes |
|---|---|---|
id |
string | Globally unique identifier |
text |
string | The comment body |
subject |
string | Empty string when the note has no subject |
dateCreated |
date string | ISO Date string |
isPublic |
boolean |
false for a staff-only internal note |
isSensitive |
boolean |
true only when the note is flagged sensitive and the key holds TASK_COMMENTS_SENSITIVE_GET
|
creator |
ProfileThin | The Profile authoring the comment |
Shared Enum Types:
TaskStatus:
OPEN |
IN_PROGRESS |
NEED_MORE_INFO |
CLOSED |
CANCELLED |
DRAFT |
TaskPriority:
LOW |
MEDIUM |
HIGH |
URGENT |