# Tasks

## GET /v1/tasks

> List tasks

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Tasks"}],"servers":[{"url":"https://app.hivo.com.au/api/rest","description":"Production"}],"security":[{"XUserId":[],"XApiKey":[]}],"components":{"securitySchemes":{"XUserId":{"type":"apiKey","in":"header","name":"X-User-Id","description":"HIVO User ID"}},"schemas":{"TaskListResponse":{"type":"object","properties":{"meta":{"type":"object"},"links":{"$ref":"#/components/schemas/PaginationLinks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskResource"}}},"required":["meta","data"]},"PaginationLinks":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"first":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}}},"TaskResource":{"type":"object","properties":{"type":{"type":"string","enum":["tasks"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"TaskAttributes":{"type":"object","description":"Task attributes. Fields are optional and vary by endpoint and user permissions. Checklist items are filtered by user permissions.","properties":{"name":{"type":"string"},"createdAt":{"type":"integer","description":"Unix seconds"},"lastModified":{"type":"integer","description":"Unix seconds"},"dueDate":{"type":"integer","description":"Unix seconds"},"clientId":{"type":"string"},"ownerEntityId":{"type":"string"},"targetEntityId":{"type":"string"},"archived":{"type":"boolean"},"checklist":{"type":"array","items":{"type":"object"},"description":"Filtered to show only items visible to the requesting user"},"permissionLevel":{"type":"integer","description":"User's permission level on this task"}},"additionalProperties":true},"JsonApiLinkage":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/Link"},"thumbnail":{"$ref":"#/components/schemas/LinkObject"}},"additionalProperties":true},"Link":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/LinkObject"}]},"LinkObject":{"type":"object","description":"JSON:API link object","properties":{"href":{"type":"string","format":"uri"},"meta":{"type":"object","description":"Non-standard meta-information for the link","properties":{"version":{"type":"string","description":"Asset version name used to generate the link (e.g., thumbnail)"}},"additionalProperties":true}},"required":["href"]},"ErrorResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorObject"}}},"required":["errors"]},"TopLevelMeta":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server timestamp in milliseconds"},"authentication":{"type":"string","description":"Authentication method, e.g. apiKey"},"links":{"type":"object","properties":{"me":{"type":"string","format":"uri"}}}}},"ErrorObject":{"type":"object","properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["status","title"]},"Error429Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamp":{"type":"integer"},"retryAfter":{"type":"integer"}}}}}]}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429Response"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/tasks":{"get":{"summary":"List tasks","operationId":"listTasks","tags":["Tasks"],"parameters":[{"name":"sort","in":"query","description":"Sort key. Allowed values are name, -name, createdAt, -createdAt, lastModified, -lastModified, dueDate, -dueDate. Defaults to -lastModified.","schema":{"type":"string","enum":["name","-name","createdAt","-createdAt","lastModified","-lastModified","dueDate","-dueDate"],"default":"-lastModified"}},{"name":"limit","in":"query","description":"Maximum number of tasks to return (1–256). Defaults to 32.","schema":{"type":"integer","minimum":1,"maximum":256,"default":32}},{"name":"skip","in":"query","description":"Number of tasks to skip (pagination) (0–65536). Defaults to 0.","schema":{"type":"integer","minimum":0,"maximum":65536,"default":0}},{"name":"filter[id]","in":"query","description":"Task ID filter. May be repeated and/or provided as a comma‑separated list. Max 512 IDs.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"filter[search]","in":"query","description":"General search string (max 256 chars). Searches task name (case‑insensitive).","schema":{"type":"string","maxLength":256}},{"name":"filter[clientId]","in":"query","description":"Admin‑only. Client ID to filter within (ObjectId).","schema":{"type":"string"}},{"name":"filter[archived]","in":"query","description":"Filters by archived status. true returns archived tasks; false returns non‑archived.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /v1/tasks/{taskId}

> Get task

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Tasks"}],"servers":[{"url":"https://app.hivo.com.au/api/rest","description":"Production"}],"security":[{"XUserId":[],"XApiKey":[]}],"components":{"securitySchemes":{"XUserId":{"type":"apiKey","in":"header","name":"X-User-Id","description":"HIVO User ID"}},"schemas":{"TaskResponse":{"type":"object","properties":{"meta":{"type":"object"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"},"data":{"$ref":"#/components/schemas/TaskResource"}},"required":["data"]},"JsonApiLinkage":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/Link"},"thumbnail":{"$ref":"#/components/schemas/LinkObject"}},"additionalProperties":true},"Link":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/LinkObject"}]},"LinkObject":{"type":"object","description":"JSON:API link object","properties":{"href":{"type":"string","format":"uri"},"meta":{"type":"object","description":"Non-standard meta-information for the link","properties":{"version":{"type":"string","description":"Asset version name used to generate the link (e.g., thumbnail)"}},"additionalProperties":true}},"required":["href"]},"TaskResource":{"type":"object","properties":{"type":{"type":"string","enum":["tasks"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"TaskAttributes":{"type":"object","description":"Task attributes. Fields are optional and vary by endpoint and user permissions. Checklist items are filtered by user permissions.","properties":{"name":{"type":"string"},"createdAt":{"type":"integer","description":"Unix seconds"},"lastModified":{"type":"integer","description":"Unix seconds"},"dueDate":{"type":"integer","description":"Unix seconds"},"clientId":{"type":"string"},"ownerEntityId":{"type":"string"},"targetEntityId":{"type":"string"},"archived":{"type":"boolean"},"checklist":{"type":"array","items":{"type":"object"},"description":"Filtered to show only items visible to the requesting user"},"permissionLevel":{"type":"integer","description":"User's permission level on this task"}},"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorObject"}}},"required":["errors"]},"TopLevelMeta":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server timestamp in milliseconds"},"authentication":{"type":"string","description":"Authentication method, e.g. apiKey"},"links":{"type":"object","properties":{"me":{"type":"string","format":"uri"}}}}},"ErrorObject":{"type":"object","properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["status","title"]},"Error429Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamp":{"type":"integer"},"retryAfter":{"type":"integer"}}}}}]}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429Response"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/tasks/{taskId}":{"get":{"summary":"Get task","operationId":"getTask","tags":["Tasks"],"parameters":[{"name":"filter[clientId]","in":"query","description":"Admin‑only. Client ID to filter within (ObjectId).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```