Ask about auth, request shape, or code samples in your preferred language.

API Assistant

Every request to public SDK endpoints must include a valid API key header.

Send the task fields needed to create a task in the integration context.

Differential pressure above threshold for two shifts.

Replace inlet filter on Line 1

name

siteId

Task type. `"1"` for a manual task, `"3"` for a task about a data source. Send it explicitly — leaving it out makes the request fail asking for `deviceId`.

typeId

Data source the task is about. Required when `typeId` is `"3"`, and not allowed when `typeId` is `"1"`.

deviceId

Priority — `5` Low, `10` Medium, `15` High. An unrecognised value is silently ignored.

priorityId

Status. Defaults to `"5"` (To Do). Omit the key rather than sending `null`.

statusId

description

dueDate

assigneeId

Channel the task’s feed post is created in.

toChannelId

fileIds

Rich-text description as an array of nodes. A plain HTML string is rejected — use `description` for plain text.

formattedDescription

Require time to be logged before the task can be completed.

timeSpentMandatory

Set true to skip the automatic opening comment. Omit it rather than sending false.

noInitialComment

Use this endpoint to create a task in Zira from an external integration flow.

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

x-api-key

Request body format for the JSON payload.

Content-Type

ID of the newly created task. It comes back as a number, while `GET /tasks` returns task IDs as strings — convert before comparing.

data

Returns the new task’s ID as a bare number under `data`. The created task is not echoed back — call `GET /tasks` if you need the full record.

Add Task


## `POST /task/`

Use this endpoint to create a task in Zira from an external integration flow.

## Authentication

```http
x-api-key: <your-api-key>
Content-Type: application/json
```

See [API Authentication](/developers/api-reference/api-authentication) for how to create a key.

## Request body

Send the task fields needed to create a task in the integration context.

```json
{
  "name": "Replace inlet filter on Line 1",
  "siteId": "1512",
  "typeId": "1",
  "priorityId": "10",
  "statusId": "5",
  "toChannelId": "45187",
  "description": "Differential pressure above threshold for two shifts."
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Task name. |
| `siteId` | string | yes | Site the task belongs to. |
| `typeId` | string | yes | Task type. `"1"` for a manual task, `"3"` for a task about a data source. Send it explicitly — leaving it out makes the request fail asking for `deviceId`. |
| `deviceId` | string | no | Data source the task is about. Required when `typeId` is `"3"`, and not allowed when `typeId` is `"1"`. |
| `priorityId` | string | no | Priority — `5` Low, `10` Medium, `15` High. An unrecognised value is silently ignored. |
| `statusId` | string | no | Status. Defaults to `"5"` (To Do). Omit the key rather than sending `null`. |
| `description` | string | no | Plain-text task description. |
| `dueDate` | string | no | When the task is due. |
| `assigneeId` | string | no | User to assign the task to. |
| `toChannelId` | string | no | Channel the task’s feed post is created in. |
| `fileIds` | string[] | no | Files to attach to the task. |
| `formattedDescription` | object[] | no | Rich-text description as an array of nodes. A plain HTML string is rejected — use `description` for plain text. |
| `timeSpentMandatory` | boolean | no | Require time to be logged before the task can be completed. |
| `noInitialComment` | boolean | no | Set true to skip the automatic opening comment. Omit it rather than sending false. |

## Response

`200 OK`

Returns the new task’s ID as a bare number under `data`. The created task is not echoed back — call `GET /tasks` if you need the full record.

```json
{
  "data": 9901
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | number | ID of the newly created task. It comes back as a number, while `GET /tasks` returns task IDs as strings — convert before comparing. |

### Good to know

- Send `typeId` explicitly. Leave it out and the request fails asking for `deviceId`; send `typeId: "1"` and `deviceId` must be omitted; send `typeId: "3"` and `deviceId` is required.
- Creating a task also creates a feed post for it in the target channel and adds an opening comment. Send `noInitialComment: true` to skip the comment.
- Assignees and followers are always notified — there is no way to create a task silently.
- The body is strict: any field not listed above is rejected with `400`. That includes `imageIds`, `mentions`, `hashtags` and `ctas`, which belong to posts rather than tasks.
- All IDs must be quoted strings. `siteId: 15` as a number is a `400`; so are `"0"` and `""`.
- `statusId` defaults to `"5"` (To Do) and `typeId` to `"1"`. Sending an explicit `null` for either is rejected — omit the key instead.
- An ID that does not exist — an unknown priority, status or site — is accepted and then quietly ignored, so the task is created without that field set. Check your IDs.
- Do not add a query string to this request; it interferes with body validation and produces a misleading `400`.

## Errors

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

```json
{
  "message": "Internal server error.",
  "internalErrorCode": "02-001"
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request failed validation — a missing required field, a field the schema does not allow, an unparseable body, a value out of range, or a malformed `lastValue`. |
| `401` | The API key resolved to a user context that is not allowed to read or write the record you asked for. |
| `403` | The `x-api-key` header is missing or is not a recognised key. API Gateway rejects the call before the endpoint runs, so the body is only `{"message":"Forbidden"}`. |
| `409` | The write conflicts with an existing record, or it references a record that does not exist. |
| `429` | The API key exceeded the rate limit or quota on its usage plan. Also returned by API Gateway rather than the endpoint. |
| `500` | Unexpected server error, or the database returned no result where one was required. |



## `PATCH /task/{id}`

Use this endpoint to update an existing task through the integration-facing task pipeline.

## Authentication

```http
x-api-key: <your-api-key>
Content-Type: application/json
```

See [API Authentication](/developers/api-reference/api-authentication) for how to create a key.

## Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | ID of the task to update. This is where the task ID belongs — a body `id` is ignored when both are sent. |

## Request body

Send only the fields you want to change. The task ID goes in the URL path, not in the body.

```json
{
  "statusId": "20",
  "priorityId": "15",
  "description": "Filter replaced, awaiting verification."
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `statusId` | string | no | New status. Setting it to `"25"` (Cancelled) also removes the task’s post from the feed. |
| `priorityId` | string | no | New priority — `5` Low, `10` Medium, `15` High. |
| `name` | string | no | New task name. |
| `description` | string | no | New plain-text description. |
| `dueDate` | string | no | New due date. |
| `siteId` | string | no | Move the task to another site. |
| `toChannelId` | string | no | Move the task’s feed post to another channel. |
| `fileIds` | string[] | no | Files to attach. |
| `formattedDescription` | object[] | no | Rich-text description as an array of nodes. |
| `timeSpentMandatory` | boolean | no | Require time to be logged before completion. |
| `id` | string | no | Optional and redundant — the path parameter is what identifies the task, and it wins if you send both. |

## Response

`200 OK`

Applies your changes and returns a number — the ID of the change-log comment Zira posted on the task. If nothing actually changed, you get the string `"SUCCESS"` instead. Handle both shapes; neither contains the updated task.

```json
{
  "data": 90214
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | number | string | A number (the ID of the change-log comment that was posted) when something changed, or the string `"SUCCESS"` when nothing changed — or when the task has no feed post to comment on. It is never the task ID. |

### Good to know

- The response never contains the updated task. Call `GET /tasks` afterwards if you need the new state.
- The task ID comes from the URL path. An `id` in the body is optional, and if you send both, the path wins.
- A `PATCH` with no body is valid and simply reports no change.
- Any change that actually alters the task is written as a readable comment on its feed post — "changed status to Done", "assigned to …" — and broadcast to anyone watching. A request that changes nothing is silent.
- Setting `statusId` to `"25"` (Cancelled) hides the task’s post for anyone currently viewing the feed instead of updating it in place.
- The `typeId` / `deviceId` pairing rule that applies when creating a task does not apply here — both are accepted freely.
- The body is strict: `imageIds`, `mentions` and `ctas` are rejected with `400`. `fileIds` and `formattedDescription` are accepted.
- Reassigning through this endpoint is unreliable — `assigneeId` is not converted the way it is on create. Verify the result before depending on it.

## Errors

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

```json
{
  "message": "Internal server error.",
  "internalErrorCode": "02-001"
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request failed validation — a missing required field, a field the schema does not allow, an unparseable body, a value out of range, or a malformed `lastValue`. |
| `401` | The API key resolved to a user context that is not allowed to read or write the record you asked for. |
| `403` | The `x-api-key` header is missing or is not a recognised key. API Gateway rejects the call before the endpoint runs, so the body is only `{"message":"Forbidden"}`. |
| `409` | The write conflicts with an existing record, or it references a record that does not exist. |
| `429` | The API key exceeded the rate limit or quota on its usage plan. Also returned by API Gateway rather than the endpoint. |
| `500` | Unexpected server error, or the database returned no result where one was required. |


Update Task


## `GET /tasks`

Purpose:

- return a paginated list of tasks

Notes:

- resolves image and file URLs in the returned task data

## `POST /task/`

Purpose:

- create a task through the SDK-facing integration flow

Important behavior:

- adapts IDs into enum or database-backed objects where needed
- triggers notifications and task-related side effects

## `PATCH /task/{id}`

Purpose:

- update an existing task

Important behavior:

- supports status, priority, and site-related conversions
- may trigger notification hooks or downstream side effects

## Integration guidance

- treat task endpoints as command-style APIs
- document which system or workflow owns the task updates
- test enum and ID mappings carefully when integrating from external systems


Reference the task query, create, and update endpoints used by SDK-driven task workflows.

Property	Required	Type	Example	Description
name	Required	string	`Replace inlet filter on Line 1`	Task name.
siteId	Required	string	`1512`	Site the task belongs to.
typeId	Required	string	`1`	Task type. `"1"` for a manual task, `"3"` for a task about a data source. Send it explicitly — leaving it out makes the request fail asking for `deviceId`.
deviceId	Optional	string	`43510`	Data source the task is about. Required when `typeId` is `"3"`, and not allowed when `typeId` is `"1"`.
priorityId	Optional	string	`10`	Priority — `5` Low, `10` Medium, `15` High. An unrecognised value is silently ignored.
statusId	Optional	string	`5`	Status. Defaults to `"5"` (To Do). Omit the key rather than sending `null`.
description	Optional	string	`Differential pressure above threshold for two shifts.`	Plain-text task description.
dueDate	Optional	string	`2026-06-01T12:00:00Z`	When the task is due.
assigneeId	Optional	string	`318`	User to assign the task to.
toChannelId	Optional	string	`45187`	Channel the task’s feed post is created in.
fileIds	Optional	string[]	`["812", "813"]`	Files to attach to the task.
formattedDescription	Optional	object[]	`[{ "type": "paragraph", "children": [{ "text": "Line 1 filter" }] }]`	Rich-text description as an array of nodes. A plain HTML string is rejected — use `description` for plain text.
timeSpentMandatory	Optional	boolean	`false`	Require time to be logged before the task can be completed.
noInitialComment	Optional	boolean	`true`	Set true to skip the automatic opening comment. Omit it rather than sending false.

https://api.zira.us/public/task/

Description