Skip to main content
Cowork is your company’s shared board of work. Each ticket on it is a task: people file it, plan it, assign it and finish it, Mist can work on it, and your company can send it to an agency. The Mist task board and Cowork in the Fluid admin are built on the Cowork API, so anything they do with a task, your code can do too. This guide covers creating a task, reading the board’s tasks and changing one. The API reference covers the rest: discussions, attachments, Mist runs and agency requests.

​
Before you start

Every Cowork endpoint needs a Bearer token for a person, sent as Authorization: Bearer <token>. The token must belong to a company admin. A company API token is refused with 403, because Cowork records every write against the person who made it. The person’s role needs the permission for what you do:

​
Create a task

Send the task to Submit standalone company work:
  • client_id is your own identity for this submission, unique within the company. It takes letters, digits, _ and -. Sending the same submission again returns the task already stored, so a retry never makes a second ticket. A different submission with a client_id already used answers 409.
  • title is required, up to 255 characters.
  • description is optional, up to 10,000 characters.
  • due_on is optional: a calendar day, YYYY-MM-DD. A day that doesn’t exist, such as 2026-02-30, is refused with 422.
The answer is 201 with the new task under task. Keep its id and its lock_version: you need both to change it. A new task starts open.

​
Read the tasks

List the company’s work returns undeleted tasks, the most recently updated first:
  • Results use cursor pagination. Ask for up to 100 tasks with page[limit] (25 by default), and pass the cursor from meta.pagination.next_cursor as page[cursor] for the next page.
  • filter[status] keeps the statuses you list, comma-separated.
  • filter[assignee] keeps tasks assigned to one person by their user id, to nobody (unassigned), or to Mist (agent).
  • sort is updated (the default), board for the order the board draws a column, or due.

​
Change a task

Each change below carries expected_version: the lock_version you last read. If someone changed the task since, the change is refused with 409, and the answer includes the current task, so retry against that one. Change what the company’s work says changes the title, description, kind, priority or due date. Send only what changes:
priority is urgent, high, medium, low, or null. kind is bug, change, feature, design, support, or null. Status and owner have routes of their own:
  • Record a person’s verdict on the company’s work moves the task with status_change. Its status is open, needs_info, in_progress, review or skipped. In a company with Cowork on, only the people working a ticket move it, such as its assignee. Anyone else is refused with 403.
  • Say who owns the company’s work assigns the task with assignment. Its assignee is { "kind": "user", "user_id": 42 } for an admin of the company, or null for nobody.

​
Create tasks from a Site

On a company Site, the page can call Cowork itself, as the admin who has it open. Declare cowork: write (and cowork: read to list tickets) in config/access.json, have your company allow cowork under Visitor data, and call /cowork/tasks with fluid.api. Each call does what the visitor could do with their own sign-in, so a visitor who can’t use Cowork gets 403. See File a Cowork ticket. That only reaches Cowork as the visitor, on a company Site. To file tickets for visitors who can’t use Cowork themselves, or from a member’s own Site, use a server function instead. A function has no Fluid credential of its own that reaches Cowork, so keep an admin’s token as a secret and call the API with fetch:
functions/file-ticket.ts
Give the function signed_in access in config/functions.json, so only signed-in visitors can file. Every task it makes is created as the admin whose token it holds, so the function names the visitor in the description.