coLab API

Unauthenticated by necessity — the caller has no credential yet. What comes back is a pending request that stays worthless until somebody signed in approves it.

Answered with a token once somebody has approved the pairing, and until then with a reason to keep waiting. A pending poll is a 400 with a body rather than a 200, which is what RFC 8628 specifies and what stops a client treating 'not yet' as success. A device code buys exactly one token.

The endpoint to call first. It confirms a pairing worked, and hands back a workspace id so a client can create things without an operator digging one out of a URL.

One query across projects, tasks, notes, milestones, decisions, comments, chat messages, attachments, links, previews and review pins — everything the token's owner can reach. This is the same search the app's own ⌘K palette runs.

A leading @Name narrows to one person's work, and @me is whoever the token belongs to. Wrapping the query in double quotes means exactly this, and suppresses spelling correction. project_id confines the search to one accessible project; kinds=note makes it a note-only content search.

Not paged: this is a bounded, ranked set rather than a walk through a table, and a cursor over relevance would be a cursor over an order that moves.

workspace_id is needed only when you belong to more than one and the token is not pinned — otherwise there is exactly one right answer and asking would be pedantry.

Takes the project's whole history with it, so only the owning team may.

The view an API has that the app does not really offer: 'everything assigned to me that is overdue' is one call here and a walk through the dashboard in a browser.

A field left out is left alone; a field sent as null is cleared. That distinction is the whole reason this is a PATCH — it lets you hand over {"assignee_id": "…"} without first reading the task back to avoid blanking its due date.

todo → doing → done, and around again from done. What a keyboard shortcut or a chat command actually wants: advancing needs no knowledge of where the task currently is.

An @name here is resolved to a person or a project agent exactly as it is from the composer in the app — so this can reach a teammate by mail, or start an agent run.

Multipart only. Up to 10 files per task, 15 MB each, 60 MB total — cumulative with whatever the task already carries, not just this call's batch.

With the same bearer token used to read its task.

An Open Graph preview is fetched for it automatically, in the background.

By the person who wrote it, or by the team that owns the project.

Send task_id to attach existing work idempotently. Without it, title creates a new task and connects it to this note.

Neither the note nor task is deleted.

Leaves the work planned against it standing, with its milestone set to null — losing a date should not take the tasks with it.

The owning team's to do, and never the author's alone — a log its writers can quietly tidy is not a record.

Leave title and content out for a blank note, or provide template_id to copy defaults. Explicit title/content override template values.

Project guests see project templates only; owning-team members also see workspace templates.

Private to the authenticated user; visits are ordered newest first and capped at 50.

Changes future instantiations only; existing notes remain independent.

Existing notes created from it remain unchanged.

A field left out is left alone. Writes only the note's stored copy — see the content field's own description on this shape.

Returns resolved and unresolved [[Note title]] references written by this note, plus the notes that link back to it.

Open threads first, with replies oldest first.

Moves the note to the front of this user's project recents without changing shared note state.

Notes and metadata remain intact.

Only the author may edit body; any project editor may resolve or reopen.

The author or owning team may delete it; replies are deleted with the thread.

Only the reply author may edit it.

The reply author or owning team may delete it.

Send task_id to attach existing work idempotently. Without it, title creates a new task and connects it to this note.

Neither the note nor task is deleted.

The review link exists from this moment; nothing reaches it until the snippet is on the page. GET /previews/{id}/review-link returns both.

A field left out is left alone. status: "closed" ends the review: the threads stay, the overlay stops being served, and every reviewer key stops resolving.

Takes every pin on it too. Closing it instead keeps what was said.

Behind an edit grant rather than on every list: the link is a credential — whoever holds it may comment — for the same reason a project's share token is never returned with the project.

This is also the only followable address a preview has, and the one to use for anything meaning “open the preview”. hosted_url is where the files answer, on an origin that receives no coLab session, so a request there is refused without a ticket — and a build opened directly carries no review overlay, so the notes left on it are invisible. This link mints the ticket and switches the overlay on.

Mints a new link and kills the old one, along with every reviewer key issued against it. What people already wrote stays where it is.

Newest first, each with its whole conversation.

The reply appears in the overlay on the build itself, not only in coLab, so the person who pinned it is told without an account and without being emailed.

The task quotes the thread rather than only linking to it — a preview URL is the thing here most likely to stop resolving. A pin that is already a task is refused.

The viewport as their own browser captured it. 404 when there is none.

Only the author, and only a message that has not been deleted. Who it names with @ is worked out again from the new text. A message needs text, so this cannot clear one.

By the person who wrote it, or by the team that owns the project. The text, files, reactions and task links go; the message stays as a deleted one so a reply to it still has something to point at.

Reports a message as objectionable. From then on the message is hidden from you, and the operator is told and reviews it within 24 hours. Reporting the same message again answers with the first report. Your own messages, and removed ones, cannot be reported.

Their messages, reactions and typing are hidden from you, a direct conversation with them leaves your list, nothing they do notifies you, and neither of you can message the other directly. They are not told. Blocking twice is the same as once.

The project's people and its agents (by handle) in a channel — what a composer offers after an @. Empty in a direct chat, where @ names no one.

The name to mention is handle, never name. /projects/{id}/mentions lists these alongside the people, which is the better call when the question is who you can address rather than what agents exist.

The project's people and its agents in one list, each carrying mention — the literal text to write after the @.

Worth calling before writing a mention rather than after wondering why one did nothing. Mentions are matched against a fixed list when the text is saved, and anything that does not match is kept as ordinary prose: nobody is notified, no agent runs, and nothing reports a problem. A person is named by their display name and an agent by its handle — two different fields, and confusing them fails silently.

Mentioning an agent is what triggers a run, so this is also how work is handed to one. Guests invited to this one project are included; they can be given work here like anybody else.

Mentions resolve in a task's details, a task comment, a note and a chat message. They do not resolve in a reply on a review pin, which stores its body verbatim.

{"kind":"direct","agent_id":"…"} opens your private chat with one agent — sending to it starts the agent automatically. {"kind":"direct","user_id":"…"} opens a direct message with another person on this project — one who can also reply, so the project's owners and editors — and returns the existing one if there is one; each message notifies the other person. Give agent_id or user_id, not both. {"kind":"channel","title":"…"} creates a channel, which wakes agents only when their @handle appears.

Send JSON, or multipart form data with the same fields and up to four files. A direct chat wakes its agent; a channel message wakes every enabled agent named with an @handle.

Starting requires write access to the channel, same as posting. Once one is running, anyone who can read the channel may join it — this endpoint answers either way.

The huddle itself ends once nobody is left in it.

Kept to whoever started it, or the workspace that owns the project.

The image_url of a message's previews entry, with the same bearer token used to read its conversation.

With the same bearer token used to read its conversation.

Newest first, in two tiers as on the web. direct is what is addressed at you: a mention, a reply, work handed to you, a direct message, a huddle. activity is the ambient rest: a task created or finished, a decision recorded. Each row's sentence arrives already worded in three pieces (text.actor in bold, the quiet text.verb, text.subject in bold), so a new kind reads correctly in an older client; text.actor is null for a folded row, where count leads. url is app-relative. The unread counts for both tiers come back too.

For a client that polls to keep a badge honest: a few counts, not a hundred rows.

One tier, or both when none is given. Changes only what you have seen.