This is the developer-facing tool list for the SoWork MCP server. Connect from Claude or ChatGPT via remote MCP, authenticate with your SoWork account, and call any of the tools below from your chat.
get_meReturns the authenticated user — who this connection acts as — including timezone and current presence in this workspace. Use it to ground yourself before acting: your own user id, name, timezone, and availability.
{
"type": "object",
"properties": {}
}
list_usersReturns every teammate (owner or contributor) in the user's SoWork workspace, each with their current presence (online/away/offline) and any text status. Presence reflects this workspace only; staleness is a few seconds. Use this to discover who is around before sending a direct message, or to enumerate the team. Set includeTimezone=true only when the question needs teammates' local dates or times.
{
"additionalProperties": false,
"type": "object",
"properties": {
"includeTimezone": {
"default": false,
"description": "Include each teammate's last known timezone when available. Adds a profile lookup per teammate; omitted or false skips those lookups.",
"type": "boolean"
}
}
}
get_userReturns one teammate's profile, timezone, and current presence by user id. If you do not know it, call list_users first. Responds with an error code "not_found" if the id is not a member of this workspace.
{
"additionalProperties": false,
"type": "object",
"properties": {
"userId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
}
},
"required": [
"userId"
]
}
list_teamsReturns the teams in the SoWork workspace, sorted by name, each with its id, name, color and member count. Pass userId to see which teams one person is on (empty for someone who isn't an admin or teammate), and query to find teams whose name contains some text, ignoring case; a team must match both when both are given. Use a team id in a mention, [@name](team:<id>), or with list_team_members to see who is on it.
{
"additionalProperties": false,
"type": "object",
"properties": {
"userId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "Only the teams this person is on. Someone who isn't an admin or teammate of the office is on no team.",
"type": "string"
},
"query": {
"minLength": 1,
"maxLength": 35,
"pattern": "\\S",
"description": "Only the teams whose name contains this text, ignoring case.",
"type": "string"
}
}
}
get_teamReturns one team by id: name, color and member count. Get ids from list_teams. Responds with error code "team_not_found" if no team of this workspace has that id.
{
"additionalProperties": false,
"type": "object",
"properties": {
"teamId": {
"format": "uuid",
"description": "Team id. Mention the team in a message with `[@name](team:<id>)`.",
"type": "string"
}
},
"required": [
"teamId"
]
}
list_team_membersReturns one page of a team's members, each with presence, in a stable order. Get team ids from list_teams. Default limit 50, maximum 100; if nextCursor is present, more members exist — pass it back verbatim as cursor.
{
"additionalProperties": false,
"type": "object",
"properties": {
"teamId": {
"format": "uuid",
"description": "Team id. Mention the team in a message with `[@name](team:<id>)`.",
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"cursor": {
"minLength": 1,
"type": "string"
}
},
"required": [
"teamId"
]
}
list_channelsReturns the group channels the user is a member of and can post to, newest activity first. Direct-message and meeting channels are not included. Paginate with `limit`/`before`; filter to recently-active channels with `updatedSince`. If `nextCursor` is present, more channels exist — page with it or tell the user the list is partial. Use this before send_channel_message to discover the channel id.
{
"type": "object",
"properties": {
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
},
"updatedSince": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
}
}
}
list_channel_membersLists the people in a channel the user is in, with each one's channel role (owner = the member who created it). If nextCursor is present, more members exist — page with cursor or tell the user the list is partial.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"cursor": {
"minLength": 1,
"type": "string"
}
},
"required": [
"channelId"
]
}
read_channel_messagesReads recent messages from a channel the user is a member of. Get a channelId via list_channels. Walk history backward with `before`; catch up forward with `after` or `since` (these directions are mutually exclusive). If `nextCursor` is present, more messages exist in the direction you are walking.
{
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
},
"after": {
"minLength": 1,
"type": "string"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
}
},
"required": [
"channelId"
]
}
read_direct_messagesRead recent messages from a direct-message conversation you belong to. Use a channelId from list_dm_conversations. Walk history backward with before; catch up forward with after or since. These direction parameters are mutually exclusive. If nextCursor is present, more messages exist.
{
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
},
"after": {
"minLength": 1,
"type": "string"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
}
},
"required": [
"channelId"
]
}
read_threadReads one thread: its root message (`parent`) plus a page of replies, oldest-first. Pass exactly one of `messageId` or `url`. `messageId` may be the thread root or any reply — replies resolve to their root. `url` is a pasted SoWork chat link (https://app.sowork.com/l/chat/..., /l/chatV2/... or an address-bar link https://app.sowork.com/s/.../_chat/...) to a message; pass the whole link and never decode its segments yourself (a channel link is refused with its channel id and type — read it with read_channel_messages / read_direct_messages). When the linked message is a reply it comes back inside `messages`, not as `parent` — page with `before`/`after` if it is not on the first page. Channel and DM reads return TOP-LEVEL messages only, so this is the only way to see replies; on those reads a message carries `replyCount` exactly when it has a thread (search results never carry it — absent there means 'not reported'). Also the way to inspect a single message's attachments: `parent` comes back even when the thread has no replies. `before`/`after` are mutually exclusive message-id cursors.
{
"additionalProperties": false,
"type": "object",
"properties": {
"messageId": {
"minLength": 1,
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
},
"after": {
"minLength": 1,
"type": "string"
}
}
}
list_dm_conversationsList your 1:1 and group DM conversations in the current workspace, most recently active first. Pass a conversation id to read_direct_messages to read it or send_channel_message to reply. Filter by userId, unread=true, or updatedSince; self=true returns only your conversation with yourself (your personal notes thread). Continue nextCursor with before and the same filters. Omit scope for the normal workspace inbox; use the scope parameter only to request another inbox.
{
"type": "object",
"properties": {
"scope": {
"description": "Omit for 1:1 and group DMs in the current workspace (workspace). Choose external for cross-workspace conversations — 1:1 and group alike — plus 1:1 DMs in other workspaces you can still access, or support for support conversations. Keep the same scope on every page. Returned conversation IDs work with existing message, thread, and attachment operations; access is checked on every request.",
"anyOf": [
{
"const": "workspace",
"type": "string"
},
{
"const": "external",
"type": "string"
},
{
"const": "support",
"type": "string"
}
]
},
"userId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
},
"self": {
"type": "boolean"
},
"unread": {
"type": "boolean"
},
"updatedSince": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
}
}
}
search_messagesFull-text search across messages the user can access (their workspace channels, plus DM and support conversations they participate in — including ones with no owning workspace), newest-first. `query` is required and takes search operators (see its description). Filter by senderId, channelId (one id or a list), and since/until (unix seconds); every filter must hold. Pass lang (the user's app language) to also read operators in that language, and tz (the user's IANA time zone) so dates mean the user's days; without them operators are English only and dates are UTC. If nextCursor is present, more results exist — page with it. Results never carry replyCount, even for messages that have threads: absence here means "not reported", not "no thread" — use read_thread if a hit's replies matter.
{
"type": "object",
"properties": {
"query": {
"minLength": 1,
"maxLength": 256,
"description": "Words to find (every word must match), with optional operators, in English or the lang language: from:<@userId> or from:@name; in:<#channelId>, in:#channel or in:@name (1:1 DMs with that person); with:@name (conversations they are in); before:, after: or on: a YYYY-MM-DD date, today or yesterday, in tz (before: and after: leave out that day); during: a date, YYYY-MM, YYYY or a month name; is:thread (thread replies, not the message that started the thread); \"exact phrase\"; prefix* (3+ characters). Put - before a word, phrase, prefix, from:, in: or with: to exclude it. Repeating from:, in: or with: matches any of the values. Quote a name with spaces: from:@\"Sara Lee\". A person's name matches exactly, or by how it starts; a channel name must match exactly. Prefer <@userId>/<#channelId> with ids from list_users, list_channels or list_dm_conversations. Quote a whole token to search it as text: \"from: the team\".",
"type": "string"
},
"lang": {
"minLength": 1,
"maxLength": 35,
"description": "The user's app language, so query may also use its operator words, is: values, words for today and yesterday, month names and numeric date order: en, es, fr, de, pt, id, ja, ko, zh-CN or zh-TW (case-sensitive). English operators always work. Omit for English only.",
"type": "string"
},
"tz": {
"minLength": 1,
"maxLength": 64,
"description": "IANA time zone (e.g. America/Los_Angeles) that before:, after:, on: and during: read days in. Defaults to UTC.",
"type": "string"
},
"senderId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
},
"channelId": {
"anyOf": [
{
"minLength": 1,
"maxLength": 256,
"type": "string"
},
{
"type": "array",
"items": {
"minLength": 1,
"maxLength": 256,
"type": "string"
}
}
]
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"until": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"limit": {
"minimum": 1,
"maximum": 50,
"default": 20,
"type": "integer"
},
"cursor": {
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
]
}
resolve_chat_linkTurns a SoWork chat link (https://app.sowork.com/l/chat/..., /l/chatV2/... or an address-bar link https://app.sowork.com/s/.../_chat/...) into ids: `channel` (id, type; `name` for group channels) and, for a message link, `messageId` — the linked message itself — plus `parentId` when that message is a thread reply. Pass the whole URL; never decode its segments yourself. To read a message link in one call, pass the URL to read_thread as `url` instead. Otherwise call read_thread with `messageId` (a root message comes back as `parent`; a reply comes back inside `messages` under its `parentId` root — page with `before`/`after` if it is not on the first page), or read_channel_messages / read_direct_messages with `channel.id` by `channel.type`.
{
"additionalProperties": false,
"type": "object",
"properties": {
"url": {
"minLength": 1,
"maxLength": 2048,
"type": "string"
}
},
"required": [
"url"
]
}
get_attachment_download_urlIssues a short-lived signed URL for one of a message's attachments. `index` is the attachment's position in that message's `attachments` list (read it from a message returned by read_channel_messages, read_direct_messages, or read_thread — do not guess). The URL needs no further authentication and expires ~5 minutes after issue, so fetch it immediately; if it lapses, call this again for a fresh URL rather than retrying the stale one.
{
"additionalProperties": false,
"type": "object",
"properties": {
"messageId": {
"minLength": 1,
"type": "string"
},
"index": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"messageId",
"index"
]
}
list_meetingsLists meetings in the workspace, most-recently-started first. Use active=true for currently-running meetings, or since/until (unix seconds) to filter by start time. Owners see every meeting; contributors see all but room-restricted ones. If nextCursor is present, more exist.
{
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"until": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"type": "string"
}
}
}
list_meeting_libraryLists ended meetings (notes, transcript, recording) accessible to the caller, sorted by meeting start time, newest first. Filter by since/until (unix seconds, on startedAt) and collectionId. If nextCursor is present, more results exist — page with it. Backed by a near-real-time search index, so a just-ended meeting may take a moment to appear. Each item carries MANIFESTS, never content: the notes/transcripts arrays list what exists, not the text itself. To read or summarize a meeting, call get_meeting_library_item with the matching include.
{
"additionalProperties": false,
"type": "object",
"properties": {
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"until": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"collectionId": {
"minLength": 1,
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 50,
"default": 20,
"type": "integer"
},
"cursor": {
"minLength": 1,
"type": "string"
}
}
}
search_meeting_libraryFull-text and speaker search across ended meetings (title, notes, transcript, chat) accessible to the caller. query is required. speakerId restricts to transcript/chat turns spoken by that user (e.g. "what did Mark say"). kinds filters to title/note/transcript/chat (one id or a list). Each match's snippet is the server's highlight. If nextCursor is present, more results exist — page with it.
{
"additionalProperties": false,
"type": "object",
"properties": {
"query": {
"minLength": 1,
"maxLength": 256,
"type": "string"
},
"speakerId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
},
"kinds": {
"anyOf": [
{
"const": "title",
"type": "string"
},
{
"const": "note",
"type": "string"
},
{
"const": "transcript",
"type": "string"
},
{
"const": "chat",
"type": "string"
},
{
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"anyOf": [
{
"const": "title",
"type": "string"
},
{
"const": "note",
"type": "string"
},
{
"const": "transcript",
"type": "string"
},
{
"const": "chat",
"type": "string"
}
]
}
}
]
},
"language": {
"minLength": 1,
"type": "string"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"until": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"limit": {
"minimum": 1,
"maximum": 50,
"default": 20,
"type": "integer"
},
"cursor": {
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
]
}
get_meeting_library_itemReturns the record for a single ended meeting by digestId. The meeting notes (summary) come back BY DEFAULT — call it with just the digestId to read what happened. include takes one id or a list of notes/transcript/video/chat and is honored verbatim, so when you want the transcript as well pass both (include: ["notes","transcript"]); include: "none" returns the manifests alone. NEVER report that a meeting has no notes, no transcript, or no content unless the content field itself came back absent or empty — the notes/transcripts manifest arrays list what EXISTS and are not the content. templateId/language select which notes document or transcript to return when a meeting has more than one; both default to the primary. Note that translation produces translated NOTES (e.g. a Spanish summary), never a translated transcript — a meeting has exactly one transcript, in the language it was spoken. videoUrl (when included) expires 24 hours after it is issued. chatMessages (when included) is the lean meeting chat snapshot — authorId/authorName/text/sentAt, oldest first — present only when the meeting captured chat (see the chat manifest field). Returns error code "meeting_library_item_not_found" if the id is unknown or the caller lacks access — the two cases are indistinguishable on purpose.
{
"additionalProperties": false,
"type": "object",
"properties": {
"digestId": {
"description": "Meeting library item (digest) id.",
"type": "string"
},
"include": {
"anyOf": [
{
"const": "notes",
"type": "string"
},
{
"const": "transcript",
"type": "string"
},
{
"const": "video",
"type": "string"
},
{
"const": "chat",
"type": "string"
},
{
"const": "none",
"type": "string"
},
{
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"anyOf": [
{
"const": "notes",
"type": "string"
},
{
"const": "transcript",
"type": "string"
},
{
"const": "video",
"type": "string"
},
{
"const": "chat",
"type": "string"
},
{
"const": "none",
"type": "string"
}
]
}
}
]
},
"templateId": {
"minLength": 1,
"type": "string"
},
"language": {
"minLength": 1,
"type": "string"
}
},
"required": [
"digestId"
]
}
get_working_hoursPer-member daily working hours for the workspace: clock in/out and seconds split across available, in-meeting, busy, and away. Requires the admin team-analytics permission. Pass date=YYYY-MM-DD for one day, or from/to (YYYY-MM-DD, inclusive, max 92 days) for a range; the two are exclusive, and with neither it covers today. timezone is an IANA zone (default UTC) and is echoed back. Includes everyone with activity; role is present only for current admins/teammates. Pass teamId (an id from list_teams) to cover only the current admins and teammates on that team. meetingSeconds overlaps the other buckets — not additive. Durations (availableSeconds, meetingSeconds, busySeconds, awaySeconds, totalSeconds) are seconds — present them to people as hours and minutes (e.g. "2h 15m"), never raw seconds; clockIn/clockOut are unix seconds — show a local time of day.
{
"additionalProperties": false,
"type": "object",
"properties": {
"date": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "A single calendar day (YYYY-MM-DD). Exclusive with from/to.",
"type": "string"
},
"from": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Inclusive range start (YYYY-MM-DD). Pair with to.",
"type": "string"
},
"to": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Inclusive range end (YYYY-MM-DD). Pair with from.",
"type": "string"
},
"timezone": {
"minLength": 1,
"description": "IANA timezone (e.g. America/Los_Angeles). Defaults to UTC.",
"type": "string"
},
"teamId": {
"format": "uuid",
"description": "Only the current admins and teammates on this team, by its id from list_teams.",
"type": "string"
}
}
}
get_taskRead a task you can see by its ID, including current status, latest message, deliverables, and version.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
}
},
"required": [
"taskId"
]
}
get_task_attachment_download_urlIssues a short-lived signed URL for a file on a task or on one of its comments. Take `attachmentId` from the task's `attachments` (get_task) or a comment's `attachments` (list_task_activity); do not guess. The URL needs no further authentication and expires ~5 minutes after issue, so fetch it immediately; if it lapses, call this again rather than retrying the stale one.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"attachmentId": {
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "A file on the task or on one of its comments.",
"type": "string"
}
},
"required": [
"taskId",
"attachmentId"
]
}
list_tasksList the tasks you are on (assigned to you, a collaborator, or on a team that is on the task), newest updated first; with projectId, the tasks in that project instead (list_task_projects shows the projects you can see); with parentTaskId, that task's sub-tasks you can see. Narrow these with involvement: assigned for the tasks assigned to you, collaborating for those you are on while someone else or nobody is assigned (any, the default, keeps both); with assigneeUserId (anyone) or unassigned, but not together with involvement=assigned; with comma-separated statusId values (ids from list_task_statuses) or status values; or look one up by externalId. Tasks you can read only through a meeting summary are not listed. Use one of before, after, or since. Default limit 50, maximum 100. Not a durable change feed; polling clients deduplicate by id/version and periodically refresh.
{
"additionalProperties": false,
"type": "object",
"properties": {
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"maxLength": 4096,
"type": "string"
},
"after": {
"minLength": 1,
"maxLength": 4096,
"type": "string"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
},
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "List the tasks in this project instead of the tasks you are on. A project you cannot see returns 404 task_project_not_found.",
"type": "string"
},
"involvement": {
"description": "Your part in the tasks listed. any (the default): assigned to you, or you are a collaborator, yourself or through a team. assigned: assigned to you. collaborating: you are a collaborator, yourself or through a team, and someone else or nobody is assigned. With projectId, narrows the project's tasks the same way. assigned is not combined with assigneeUserId or unassigned.",
"anyOf": [
{
"const": "any",
"type": "string"
},
{
"const": "assigned",
"type": "string"
},
{
"const": "collaborating",
"type": "string"
}
]
},
"assigneeUserId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"description": "Only tasks assigned to this user, anyone in the office. Send your own user ID for the tasks assigned to you. Not with unassigned.",
"type": "string"
},
"unassigned": {
"description": "Only tasks nobody is assigned to. Not with assigneeUserId.",
"type": "boolean"
},
"parentTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "List this task's sub-tasks that you can see instead of the tasks you are on. With projectId, only those in the project; involvement narrows them the same way.",
"type": "string"
},
"externalId": {
"minLength": 1,
"maxLength": 1024,
"description": "The task with this externalId, if any. At most one task matches.",
"type": "string"
},
"status": {
"minLength": 1,
"maxLength": 100,
"description": "Comma-separated task statuses.",
"type": "string"
},
"statusId": {
"minLength": 1,
"maxLength": 1000,
"description": "Comma-separated ids of the office's statuses (GET /v1/task-statuses): only tasks in one of them, as `statusId` on the task reads. An id that is not one of the office's statuses returns 400 invalid_request.",
"type": "string"
}
}
}
list_task_activityRead a task’s activity by task ID: change entries (status changes, reassignments, and other fields with their values before and after) and comments (including each status message set on it). A change entry of only field changes keeps taking in its author’s next field changes for up to 30 minutes while they keep editing. Newest first by default; use one of before, after, or since. Default limit 50, maximum 100. Undo a change with undo_task_change; report progress with update_task; comment with add_task_comment.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"limit": {
"minimum": 1,
"maximum": 100,
"default": 50,
"type": "integer"
},
"before": {
"minLength": 1,
"maxLength": 4096,
"type": "string"
},
"after": {
"minLength": 1,
"maxLength": 4096,
"type": "string"
},
"since": {
"minimum": 0,
"maximum": 253402300799,
"type": "integer"
}
},
"required": [
"taskId"
]
}
list_task_projectsList every task project you can see, by name, with its lists and your role on it (viewer, editor or owner). Pass a project's id to list_tasks as projectId to read its tasks, or to add_task_to_project.
{
"additionalProperties": false,
"type": "object",
"properties": {}
}
list_task_custom_fieldsList the office's custom fields: each one's id, name, type (number, text, tags, single_select or multi_select) and a select field's options. A task has the custom fields of its projects (customFieldIds on each project from list_task_projects); read its values in customFieldValues on the task, and set them by field id with create_task or update_task.
{
"additionalProperties": false,
"type": "object",
"properties": {}
}
list_task_statusesList the office's task statuses in order: each one's id, name, category (backlog, unstarted, started, done, canceled) and color, and defaultStatusId, the status a task created without one starts in. Every task of the office is in one of them (statusId on the task). Read them before setting or filtering statuses: an office can rename, remove and add statuses (ids s-…), so don't assume the five status values. Put a task in one with statusId on create_task or update_task, and filter list_tasks with statusId.
{
"additionalProperties": false,
"type": "object",
"properties": {}
}
list_task_labelsList the office's labels: id, name and color. Any task can carry any of them; set a task's labels with labelIds on create_task or update_task.
{
"additionalProperties": false,
"type": "object",
"properties": {}
}
list_task_viewsList a project's saved views (its tabs, in order): layout (list or board), the fields shown, and the filter, sort and grouping, in the format create_task_view takes.
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
}
},
"required": [
"projectId"
]
}
create_taskCreate a task. To report your own work, set assigneeUserId to your own user id (from get_me); without an assignee the task is unassigned. You and the assignee are added as collaborators. collaboratorTeamIds (team ids from list_teams) puts teams on it: their members can see and change it, as collaborators can. Only collaborators, members of its teams and the people its projects are shared with can see a task, so leaving it with update_task takes it out of your sight. An externalId (your own id for the task) must be unique in the office. parentTaskId makes it a sub-task of another task; sub-tasks are one level deep, so the parent can't itself be a sub-task. Name is at most 200 characters; statusMessage at most 4000. statusId puts the task in one of the office's statuses: read them with list_task_statuses rather than assuming the five status values, since an office can add its own (such as an Ice box in Backlog); a status the office added reads as its category's status in status. Without status, statusId or canceled: true, the task starts in the office's default status (defaultStatusId from list_task_statuses). Use a stable idempotencyKey for creation retries (required for apps); it is remembered for 24 hours.
{
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
},
"status": {
"description": "Without it, `statusId` and `canceled`, the task starts in the office's default status (`defaultStatusId` from GET /v1/task-statuses). Use `blocked` when the task can't continue without someone's help, including when it failed, and say why in `statusMessage`.",
"anyOf": [
{
"const": "backlog",
"type": "string"
},
{
"const": "queued",
"type": "string"
},
{
"const": "in_progress",
"type": "string"
},
{
"const": "blocked",
"type": "string"
},
{
"const": "completed",
"type": "string"
}
]
},
"statusId": {
"pattern": "^(backlog|queued|in_progress|blocked|completed|canceled)$|^s-[A-Za-z0-9]{1,32}$",
"description": "One of the office's statuses, by its `id` from GET /v1/task-statuses, such as a status the office added (`s-…`). It sets `status` and `canceledAt` to match it. Sent with a `status` or `canceled` that doesn't match it, or naming no status of the office, it returns 400 invalid_request.",
"type": "string"
},
"canceled": {
"description": "True closes the task as canceled (closed without doing it): it gets status `completed` and `canceledAt`. Send it with status `completed` or no status; with another status it returns 400 invalid_request.",
"type": "boolean"
},
"assigneeUserId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"description": "A current teammate or app in the office, including yourself. Omit it to leave the task unassigned.",
"type": "string"
},
"collaboratorUserIds": {
"maxItems": 100,
"uniqueItems": true,
"description": "Current teammates or apps in the office to add to the task. You are added as a collaborator too, and the limit counts you; remove yourself with an update.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
}
},
"collaboratorTeamIds": {
"maxItems": 22,
"uniqueItems": true,
"description": "The teams on the task. Every member of a team on it can see and change the task, as its collaborators can, and finds it among the tasks they are on. Mentioning a team in a comment, `[@name](team:<id>)`, also puts it on the task. Team ids come from `GET /v1/teams`. Each team added must be an active team of the office, and the office's plan must include teams; otherwise 400 invalid_team. At most 22.",
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
"externalId": {
"minLength": 1,
"maxLength": 1024,
"pattern": "\\S",
"description": "Your own identifier for the task, such as the id of the pull request or card it tracks. Unique within the office; set only when the task is created. Prefixing it with your system's name (`github:…`) avoids colliding with other integrations.",
"type": "string"
},
"description": {
"minLength": 1,
"maxLength": 20000,
"pattern": "\\S",
"description": "Markdown, like a comment's text. A person is mentioned as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. Plain text is valid markdown. The people and teams the description newly mentions are told (`me.task_mentioned`), and a mentioned person who can't see the task, or a mentioned team not on it, is put on the task. Mentioning someone who isn't a teammate or app of the office, or a channel, returns 400 invalid_mention.",
"type": "string"
},
"statusMessage": {
"minLength": 1,
"maxLength": 4000,
"pattern": "\\S",
"description": "A short status line shown with the task, such as what is happening now. Each one sent is also added to the task's activity as a comment by you.",
"type": "string"
},
"origin": {
"description": "Where the task was requested: a chat message (`chat`), a meeting (`meeting`), a meeting library item (`meetingLibrary`), or an outside link (`link`). More types may be added later, so handle a type you don't recognize. A `meetingLibrary` origin must name a meeting summary in this office that you can read: everyone who can read that summary can then read the task.",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meeting",
"type": "string"
},
"meetingId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"meetingId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meetingLibrary",
"type": "string"
},
"digestId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"digestId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
},
"deliverables": {
"maxItems": 20,
"description": "What the task produced: chat messages (`chat`) or outside links (`link`), in the same shapes as `origin`. More types may be added later, so handle a type you don't recognize.",
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
}
},
"projectIds": {
"maxItems": 10,
"uniqueItems": true,
"description": "The projects the task is in. A task in no project is visible only to its collaborators; a project shares its tasks with everyone it is shared with. Adding a task to a project requires edit access to that project.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"type": "string"
}
},
"dueDate": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "A calendar date, `YYYY-MM-DD`, with no time zone.",
"type": "string"
},
"labelIds": {
"maxItems": 100,
"uniqueItems": true,
"description": "The task's labels, by label ID, as `GET /v1/task-labels` lists the office's labels. Any task in the office can carry any of them. Each must be a label of the office; otherwise 400 invalid_label. At most 100.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
"parentTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Makes the task a sub-task of this task. Sub-tasks are one level deep: the parent can't be a sub-task, a task that has sub-tasks can't become one, and a task has at most 50 sub-tasks. The parent must be a task of the office you can see, and not the task itself. Otherwise 400 invalid_task_relation.",
"type": "string"
},
"customFieldValues": {
"maxProperties": 100,
"description": "Custom field values to set, by field ID. Each field must come from one of the projects the task is in (after this request), and each value must fit its type: a number for a `number` field (rounded to its `precision`; at most 15 significant digits), text of 1 to 1024 characters for a `text` field, a list of up to 20 texts of 1 to 50 characters for a `tags` field, the ID of an enabled option for a `single_select` field, and a list of IDs of enabled options for a `multi_select` field. Otherwise 400 invalid_custom_field_value.",
"type": "object",
"patternProperties": {
"^(.*)$": {}
}
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"name"
]
}
create_tasksCreate up to 100 tasks at once, each as create_task takes it, in the order given (tasks put in one list line up in that order). Each result is the task or the error that refused it; one refused doesn't stop the rest. Pass a stable idempotencyKey to make a retry return what the first call made (remembered 24 hours). The key covers each task by its place in the list, so a retry makes only the ones still missing.
{
"additionalProperties": false,
"type": "object",
"properties": {
"tasks": {
"minItems": 1,
"maxItems": 100,
"description": "The tasks to create, at most 100, each as `POST /v1/tasks` takes it.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
},
"status": {
"description": "Without it, `statusId` and `canceled`, the task starts in the office's default status (`defaultStatusId` from GET /v1/task-statuses). Use `blocked` when the task can't continue without someone's help, including when it failed, and say why in `statusMessage`.",
"anyOf": [
{
"const": "backlog",
"type": "string"
},
{
"const": "queued",
"type": "string"
},
{
"const": "in_progress",
"type": "string"
},
{
"const": "blocked",
"type": "string"
},
{
"const": "completed",
"type": "string"
}
]
},
"statusId": {
"pattern": "^(backlog|queued|in_progress|blocked|completed|canceled)$|^s-[A-Za-z0-9]{1,32}$",
"description": "One of the office's statuses, by its `id` from GET /v1/task-statuses, such as a status the office added (`s-…`). It sets `status` and `canceledAt` to match it. Sent with a `status` or `canceled` that doesn't match it, or naming no status of the office, it returns 400 invalid_request.",
"type": "string"
},
"canceled": {
"description": "True closes the task as canceled (closed without doing it): it gets status `completed` and `canceledAt`. Send it with status `completed` or no status; with another status it returns 400 invalid_request.",
"type": "boolean"
},
"assigneeUserId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"description": "A current teammate or app in the office, including yourself. Omit it to leave the task unassigned.",
"type": "string"
},
"collaboratorUserIds": {
"maxItems": 100,
"uniqueItems": true,
"description": "Current teammates or apps in the office to add to the task. You are added as a collaborator too, and the limit counts you; remove yourself with an update.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
}
},
"collaboratorTeamIds": {
"maxItems": 22,
"uniqueItems": true,
"description": "The teams on the task. Every member of a team on it can see and change the task, as its collaborators can, and finds it among the tasks they are on. Mentioning a team in a comment, `[@name](team:<id>)`, also puts it on the task. Team ids come from `GET /v1/teams`. Each team added must be an active team of the office, and the office's plan must include teams; otherwise 400 invalid_team. At most 22.",
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
"externalId": {
"minLength": 1,
"maxLength": 1024,
"pattern": "\\S",
"description": "Your own identifier for the task, such as the id of the pull request or card it tracks. Unique within the office; set only when the task is created. Prefixing it with your system's name (`github:…`) avoids colliding with other integrations.",
"type": "string"
},
"description": {
"minLength": 1,
"maxLength": 20000,
"pattern": "\\S",
"description": "Markdown, like a comment's text. A person is mentioned as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. Plain text is valid markdown. The people and teams the description newly mentions are told (`me.task_mentioned`), and a mentioned person who can't see the task, or a mentioned team not on it, is put on the task. Mentioning someone who isn't a teammate or app of the office, or a channel, returns 400 invalid_mention.",
"type": "string"
},
"statusMessage": {
"minLength": 1,
"maxLength": 4000,
"pattern": "\\S",
"description": "A short status line shown with the task, such as what is happening now. Each one sent is also added to the task's activity as a comment by you.",
"type": "string"
},
"origin": {
"description": "Where the task was requested: a chat message (`chat`), a meeting (`meeting`), a meeting library item (`meetingLibrary`), or an outside link (`link`). More types may be added later, so handle a type you don't recognize. A `meetingLibrary` origin must name a meeting summary in this office that you can read: everyone who can read that summary can then read the task.",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meeting",
"type": "string"
},
"meetingId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"meetingId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meetingLibrary",
"type": "string"
},
"digestId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"digestId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
},
"deliverables": {
"maxItems": 20,
"description": "What the task produced: chat messages (`chat`) or outside links (`link`), in the same shapes as `origin`. More types may be added later, so handle a type you don't recognize.",
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
}
},
"projectIds": {
"maxItems": 10,
"uniqueItems": true,
"description": "The projects the task is in. A task in no project is visible only to its collaborators; a project shares its tasks with everyone it is shared with. Adding a task to a project requires edit access to that project.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"type": "string"
}
},
"dueDate": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "A calendar date, `YYYY-MM-DD`, with no time zone.",
"type": "string"
},
"labelIds": {
"maxItems": 100,
"uniqueItems": true,
"description": "The task's labels, by label ID, as `GET /v1/task-labels` lists the office's labels. Any task in the office can carry any of them. Each must be a label of the office; otherwise 400 invalid_label. At most 100.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
"parentTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Makes the task a sub-task of this task. Sub-tasks are one level deep: the parent can't be a sub-task, a task that has sub-tasks can't become one, and a task has at most 50 sub-tasks. The parent must be a task of the office you can see, and not the task itself. Otherwise 400 invalid_task_relation.",
"type": "string"
},
"customFieldValues": {
"maxProperties": 100,
"description": "Custom field values to set, by field ID. Each field must come from one of the projects the task is in (after this request), and each value must fit its type: a number for a `number` field (rounded to its `precision`; at most 15 significant digits), text of 1 to 1024 characters for a `text` field, a list of up to 20 texts of 1 to 50 characters for a `tags` field, the ID of an enabled option for a `single_select` field, and a list of IDs of enabled options for a `multi_select` field. Otherwise 400 invalid_custom_field_value.",
"type": "object",
"patternProperties": {
"^(.*)$": {}
}
}
},
"required": [
"name"
]
}
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"tasks"
]
}
update_taskUpdate a task by its ID; pass expectedVersion to guard against changes you have not seen. An optional statusMessage (at most 4000 characters) replaces the task's status line and is recorded in the activity as your comment, with or without a status change. Reassign with assigneeUserId (null unassigns). statusId puts the task in one of the office's statuses: read them with list_task_statuses rather than assuming the five status values, since an office can add its own (such as an Ice box in Backlog); a status the office added reads as its category's status in status. collaboratorTeamIds sets the teams on it (team ids from list_teams). parentTaskId makes it a sub-task of another task; sub-tasks are one level deep, so the parent can't itself be a sub-task. parentTaskId null makes a sub-task a top-level task again. Arrays and origin are replaced whole; null clears optional fields. Only people on the task and editors of its projects can change it. On task_version_conflict, read the task and activity before deciding whether to retry.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the task is still at that version; otherwise 409 task_version_conflict. Omit it to change the task as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
},
"status": {
"description": "Use `blocked` when the task can't continue without someone's help, including when it failed, and say why in `statusMessage`.",
"anyOf": [
{
"const": "backlog",
"type": "string"
},
{
"const": "queued",
"type": "string"
},
{
"const": "in_progress",
"type": "string"
},
{
"const": "blocked",
"type": "string"
},
{
"const": "completed",
"type": "string"
}
]
},
"statusId": {
"pattern": "^(backlog|queued|in_progress|blocked|completed|canceled)$|^s-[A-Za-z0-9]{1,32}$",
"description": "One of the office's statuses, by its `id` from GET /v1/task-statuses, such as a status the office added (`s-…`). It sets `status` and `canceledAt` to match it. Sent with a `status` or `canceled` that doesn't match it, or naming no status of the office, it returns 400 invalid_request.",
"type": "string"
},
"canceled": {
"description": "True closes the task as canceled (closed without doing it): it gets status `completed` and `canceledAt`. Send it with status `completed` or no status; with another status it returns 400 invalid_request. False on a canceled task makes it a plain completed task.",
"type": "boolean"
},
"assigneeUserId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"description": "Reassign to a current teammate or app in the office; null leaves the task unassigned.",
"type": [
"string",
"null"
]
},
"collaboratorUserIds": {
"anyOf": [
{
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"collaboratorTeamIds": {
"description": "The teams on the task. Every member of a team on it can see and change the task, as its collaborators can, and finds it among the tasks they are on. Mentioning a team in a comment, `[@name](team:<id>)`, also puts it on the task. Team ids come from `GET /v1/teams`. Each team added must be an active team of the office, and the office's plan must include teams; otherwise 400 invalid_team. At most 22. Replaces the whole list; null takes every team off the task.",
"anyOf": [
{
"maxItems": 22,
"uniqueItems": true,
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
{
"type": "null"
}
]
},
"description": {
"minLength": 1,
"maxLength": 20000,
"pattern": "\\S",
"description": "Markdown, like a comment's text. A person is mentioned as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. Plain text is valid markdown. The people and teams the description newly mentions are told (`me.task_mentioned`), and a mentioned person who can't see the task, or a mentioned team not on it, is put on the task. Mentioning someone who isn't a teammate or app of the office, or a channel, returns 400 invalid_mention. Null clears it.",
"type": [
"string",
"null"
]
},
"statusMessage": {
"minLength": 1,
"maxLength": 4000,
"pattern": "\\S",
"description": "A short status line shown with the task, such as what is happening now. Each one sent is also added to the task's activity as a comment by you. Null clears the status line and adds no comment.",
"type": [
"string",
"null"
]
},
"origin": {
"description": "Where the task was requested: a chat message (`chat`), a meeting (`meeting`), a meeting library item (`meetingLibrary`), or an outside link (`link`). More types may be added later, so handle a type you don't recognize. A `meetingLibrary` origin must name a meeting summary in this office that you can read: everyone who can read that summary can then read the task. Replaces the whole origin; null clears it.",
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meeting",
"type": "string"
},
"meetingId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"meetingId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meetingLibrary",
"type": "string"
},
"digestId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"digestId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
},
{
"type": "null"
}
]
},
"deliverables": {
"description": "What the task produced: chat messages (`chat`) or outside links (`link`), in the same shapes as `origin`. More types may be added later, so handle a type you don't recognize. Replaces the whole list; null clears it.",
"anyOf": [
{
"maxItems": 20,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
}
},
{
"type": "null"
}
]
},
"projectIds": {
"description": "The projects the task is in. A task in no project is visible only to its collaborators; a project shares its tasks with everyone it is shared with. Adding a task to a project requires edit access to that project. Replaces the whole list; null removes the task from every project. Removing it from a project requires edit access to that project, or to the task.",
"anyOf": [
{
"maxItems": 10,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"dueDate": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "A calendar date, `YYYY-MM-DD`, with no time zone. Null clears it.",
"type": [
"string",
"null"
]
},
"labelIds": {
"description": "The task's labels, by label ID, as `GET /v1/task-labels` lists the office's labels. Any task in the office can carry any of them. Each must be a label of the office; otherwise 400 invalid_label. At most 100. Replaces the whole list; null takes every label off the task.",
"anyOf": [
{
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"parentTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Makes the task a sub-task of this task. Sub-tasks are one level deep: the parent can't be a sub-task, a task that has sub-tasks can't become one, and a task has at most 50 sub-tasks. The parent must be a task of the office you can see, and not the task itself. Otherwise 400 invalid_task_relation. Null makes it a top-level task again.",
"type": [
"string",
"null"
]
},
"customFieldValues": {
"maxProperties": 100,
"description": "Custom field values to set, by field ID. Each field must come from one of the projects the task is in (after this request), and each value must fit its type: a number for a `number` field (rounded to its `precision`; at most 15 significant digits), text of 1 to 1024 characters for a `text` field, a list of up to 20 texts of 1 to 50 characters for a `tags` field, the ID of an enabled option for a `single_select` field, and a list of IDs of enabled options for a `multi_select` field. Otherwise 400 invalid_custom_field_value. Fields you leave out keep their values; null clears a field, which works whether or not it still comes from the task's projects.",
"type": "object",
"patternProperties": {
"^(.*)$": {}
}
}
},
"required": [
"taskId"
]
}
update_tasksChange up to 100 tasks at once: each update is a taskId with the fields update_task takes. Each result is the task or the error that refused it; one refused doesn't stop the rest.
{
"additionalProperties": false,
"type": "object",
"properties": {
"updates": {
"minItems": 1,
"maxItems": 100,
"description": "The changes, at most 100: each a task ID with the fields `PATCH /v1/tasks/{taskId}` takes. Two changes to one task are made in the order sent.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the task is still at that version; otherwise 409 task_version_conflict. Omit it to change the task as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
},
"status": {
"description": "Use `blocked` when the task can't continue without someone's help, including when it failed, and say why in `statusMessage`.",
"anyOf": [
{
"const": "backlog",
"type": "string"
},
{
"const": "queued",
"type": "string"
},
{
"const": "in_progress",
"type": "string"
},
{
"const": "blocked",
"type": "string"
},
{
"const": "completed",
"type": "string"
}
]
},
"statusId": {
"pattern": "^(backlog|queued|in_progress|blocked|completed|canceled)$|^s-[A-Za-z0-9]{1,32}$",
"description": "One of the office's statuses, by its `id` from GET /v1/task-statuses, such as a status the office added (`s-…`). It sets `status` and `canceledAt` to match it. Sent with a `status` or `canceled` that doesn't match it, or naming no status of the office, it returns 400 invalid_request.",
"type": "string"
},
"canceled": {
"description": "True closes the task as canceled (closed without doing it): it gets status `completed` and `canceledAt`. Send it with status `completed` or no status; with another status it returns 400 invalid_request. False on a canceled task makes it a plain completed task.",
"type": "boolean"
},
"assigneeUserId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"description": "Reassign to a current teammate or app in the office; null leaves the task unassigned.",
"type": [
"string",
"null"
]
},
"collaboratorUserIds": {
"anyOf": [
{
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"collaboratorTeamIds": {
"description": "The teams on the task. Every member of a team on it can see and change the task, as its collaborators can, and finds it among the tasks they are on. Mentioning a team in a comment, `[@name](team:<id>)`, also puts it on the task. Team ids come from `GET /v1/teams`. Each team added must be an active team of the office, and the office's plan must include teams; otherwise 400 invalid_team. At most 22. Replaces the whole list; null takes every team off the task.",
"anyOf": [
{
"maxItems": 22,
"uniqueItems": true,
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
{
"type": "null"
}
]
},
"description": {
"minLength": 1,
"maxLength": 20000,
"pattern": "\\S",
"description": "Markdown, like a comment's text. A person is mentioned as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. Plain text is valid markdown. The people and teams the description newly mentions are told (`me.task_mentioned`), and a mentioned person who can't see the task, or a mentioned team not on it, is put on the task. Mentioning someone who isn't a teammate or app of the office, or a channel, returns 400 invalid_mention. Null clears it.",
"type": [
"string",
"null"
]
},
"statusMessage": {
"minLength": 1,
"maxLength": 4000,
"pattern": "\\S",
"description": "A short status line shown with the task, such as what is happening now. Each one sent is also added to the task's activity as a comment by you. Null clears the status line and adds no comment.",
"type": [
"string",
"null"
]
},
"origin": {
"description": "Where the task was requested: a chat message (`chat`), a meeting (`meeting`), a meeting library item (`meetingLibrary`), or an outside link (`link`). More types may be added later, so handle a type you don't recognize. A `meetingLibrary` origin must name a meeting summary in this office that you can read: everyone who can read that summary can then read the task. Replaces the whole origin; null clears it.",
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meeting",
"type": "string"
},
"meetingId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"meetingId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "meetingLibrary",
"type": "string"
},
"digestId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[^/]+$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"digestId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
},
{
"type": "null"
}
]
},
"deliverables": {
"description": "What the task produced: chat messages (`chat`) or outside links (`link`), in the same shapes as `origin`. More types may be added later, so handle a type you don't recognize. Replaces the whole list; null clears it.",
"anyOf": [
{
"maxItems": 20,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "chat",
"type": "string"
},
"channelId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"messageId": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"channelId",
"messageId"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "link",
"type": "string"
},
"url": {
"minLength": 1,
"maxLength": 2048,
"pattern": "^https?://",
"type": "string"
},
"label": {
"minLength": 1,
"maxLength": 200,
"pattern": "\\S",
"type": "string"
}
},
"required": [
"type",
"url"
]
}
]
}
},
{
"type": "null"
}
]
},
"projectIds": {
"description": "The projects the task is in. A task in no project is visible only to its collaborators; a project shares its tasks with everyone it is shared with. Adding a task to a project requires edit access to that project. Replaces the whole list; null removes the task from every project. Removing it from a project requires edit access to that project, or to the task.",
"anyOf": [
{
"maxItems": 10,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"dueDate": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "A calendar date, `YYYY-MM-DD`, with no time zone. Null clears it.",
"type": [
"string",
"null"
]
},
"labelIds": {
"description": "The task's labels, by label ID, as `GET /v1/task-labels` lists the office's labels. Any task in the office can carry any of them. Each must be a label of the office; otherwise 400 invalid_label. At most 100. Replaces the whole list; null takes every label off the task.",
"anyOf": [
{
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
{
"type": "null"
}
]
},
"parentTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Makes the task a sub-task of this task. Sub-tasks are one level deep: the parent can't be a sub-task, a task that has sub-tasks can't become one, and a task has at most 50 sub-tasks. The parent must be a task of the office you can see, and not the task itself. Otherwise 400 invalid_task_relation. Null makes it a top-level task again.",
"type": [
"string",
"null"
]
},
"customFieldValues": {
"maxProperties": 100,
"description": "Custom field values to set, by field ID. Each field must come from one of the projects the task is in (after this request), and each value must fit its type: a number for a `number` field (rounded to its `precision`; at most 15 significant digits), text of 1 to 1024 characters for a `text` field, a list of up to 20 texts of 1 to 50 characters for a `tags` field, the ID of an enabled option for a `single_select` field, and a list of IDs of enabled options for a `multi_select` field. Otherwise 400 invalid_custom_field_value. Fields you leave out keep their values; null clears a field, which works whether or not it still comes from the task's projects.",
"type": "object",
"patternProperties": {
"^(.*)$": {}
}
}
},
"required": [
"taskId"
]
}
}
},
"required": [
"updates"
]
}
delete_taskSoft-delete a task by its ID; pass expectedVersion to guard against changes you have not seen. Hides its activity and frees its externalId. Only people on the task and editors of its projects can delete it. Repeated authorized deletion succeeds.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the task is still at that version; otherwise 409 task_version_conflict. Omit it to change the task as it is now.",
"type": "integer"
}
},
"required": [
"taskId"
]
}
add_task_commentAdd a markdown comment (at most 10000 characters) to a task's activity: results, questions, or notes. Anyone who can read the task can comment. Mention people as [@Name](user:<id>) and teams as [@name](team:<id>): each mentioned person and team is added to the task, and a person or team that can't see it yet is added only when you can change the task, otherwise the comment is refused. A person (not an app) who comments becomes a collaborator too. It does not change the task's status line; set statusMessage with update_task for that. Use a stable idempotencyKey for retries (required for apps); it is remembered for 24 hours.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"text": {
"minLength": 1,
"maxLength": 10000,
"pattern": "\\S",
"description": "Markdown. Plain text is valid markdown. Mention a person as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. A new comment puts a mentioned person who can't see the task, or a mentioned team not on it, on the task when you can change it; otherwise, and in an edit, such a mention returns 400 invalid_mention.",
"type": "string"
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"taskId",
"text"
]
}
update_task_commentReplace the text of one of your own comments on a task (its activity entry ID from list_task_activity or add_task_comment). Only the author can edit a comment; change entries can't be edited.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"commentId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "The comment: its activity entry ID.",
"type": "string"
},
"text": {
"minLength": 1,
"maxLength": 10000,
"pattern": "\\S",
"description": "Markdown. Plain text is valid markdown. Mention a person as `[@Name](user:<id>)` and a team as `[@name](team:<id>)`. A new comment puts a mentioned person who can't see the task, or a mentioned team not on it, on the task when you can change it; otherwise, and in an edit, such a mention returns 400 invalid_mention.",
"type": "string"
}
},
"required": [
"taskId",
"commentId",
"text"
]
}
delete_task_commentDelete a comment from a task's activity by its activity entry ID. Its author, or anyone who can change the task, can delete it; change entries can't be deleted. A comment that is already gone returns task_comment_not_found. The task's status line is not changed.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"commentId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "The comment: its activity entry ID.",
"type": "string"
}
},
"required": [
"taskId",
"commentId"
]
}
delete_task_attachmentTake one file off a task, by its ID from the task's `attachments` (get_task). Needs the right to change the task. It is a change in the task's activity, so undo_task_change can put the file back. A file the task doesn't have, including one on a comment, returns not_found.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"attachmentId": {
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "A file on the task or on one of its comments.",
"type": "string"
}
},
"required": [
"taskId",
"attachmentId"
]
}
undo_task_changeUndo a change entry of a task's activity (its activity entry ID from list_task_activity): each field it changed goes back to its value before, as your own change entry (its undoneActivityId names the entry undone; undo that one to put the change back), checked as update_task checks a change. If the task no longer holds what the entry set, because someone changed it since, it answers task_changed_since and changes nothing; read the activity again before deciding. A comment delete (fieldChanges.deletedComments) is an entry too: undoing it puts the comments back. So is a task delete (fieldChanges.deleted): undoing it restores the task, with the sub-tasks deleted with it, unless a project it was in is gone or a live task has its externalId. Comments and the entry recording the task's creation can't be undone.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"activityId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "An entry of the task's activity, by its ID.",
"type": "string"
}
},
"required": [
"taskId",
"activityId"
]
}
add_task_to_projectPut a task in a project, so everyone the project is shared with can see it. Needs the right to change the task and edit access to the project. listId puts it in one of the project's lists (from list_task_projects); a list that completes tasks completes it. A task already in the project is returned unchanged. At most 10 projects per task.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"listId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the project's lists to put the task in. Without it the task is in the project's first list. A list that completes tasks completes it. Ignored when the task is already in the project.",
"type": "string"
}
},
"required": [
"taskId",
"projectId"
]
}
remove_task_from_projectTake a task out of a project, with its place on that project's board. An editor of the project, or anyone who can change the task, can. People who saw the task only through that project lose sight of it. A task not in the project is returned unchanged.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
}
},
"required": [
"taskId",
"projectId"
]
}
move_taskMove a task within one of its projects' boards: to the end of a list (listId), or just before or after another task of the project (beforeTaskId or afterTaskId). A list that completes tasks completes it. The task's placements say which list it is in.
{
"additionalProperties": false,
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"listId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the project's lists, from `GET /v1/task-projects`.",
"type": "string"
},
"beforeTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Put the task just before this task of the project.",
"type": "string"
},
"afterTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Put the task just after this task of the project.",
"type": "string"
}
},
"required": [
"taskId",
"projectId"
]
}
move_tasksMove up to 100 tasks at once, each as move_task (with its projectId), in the order given: moving tasks one after another to the end of a list puts them in that order. Each result is the task or the error that refused it.
{
"additionalProperties": false,
"type": "object",
"properties": {
"moves": {
"minItems": 1,
"maxItems": 100,
"description": "The moves, at most 100, made in the order sent: a move can name a task an earlier move placed.",
"type": "array",
"items": {
"additionalProperties": false,
"description": "Where to put the task on the project's board: in a list (`listId`), and before or after another task of that project (`beforeTaskId` or `afterTaskId`, not both), whose list it then joins. Without a neighbour it goes to the end of the list; without `listId` it stays in its list. Moving it into a list that completes tasks completes it, and out of one reopens it.",
"type": "object",
"properties": {
"taskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Task ID.",
"type": "string"
},
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "The project whose board the task moves on.",
"type": "string"
},
"listId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the project's lists, from `GET /v1/task-projects`.",
"type": "string"
},
"beforeTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Put the task just before this task of the project.",
"type": "string"
},
"afterTaskId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Put the task just after this task of the project.",
"type": "string"
}
},
"required": [
"taskId",
"projectId"
]
}
}
},
"required": [
"moves"
]
}
create_task_projectCreate a task project you own: name, color (#RRGGBB), its board's lists (sections; default To Do, In Progress, Done), the custom fields its tasks have (ids from list_task_custom_fields or create_task_custom_field), and sharing (teammates, admins, guests, people by user id, teams by team id, each viewer or editor). Share it, or nobody else sees it or its tasks. It starts with a List and a Board view. Pass a stable idempotencyKey to make a retry return what the first call made (remembered 24 hours).
{
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"description": "Not unique: two projects in an office can share a name.",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
},
"lists": {
"minItems": 1,
"maxItems": 50,
"description": "The project's board: its lists (sections), in order, at least one and at most 50. Replaces the whole board. A list with the `id` of one of the project's lists keeps it, with its tasks; a list without an `id`, or with an id the board doesn't have, is a new list. Tasks in a list left out move to the first list. A list that keeps the English name of a default list (`To Do`, `In Progress`, `Done`) stays a default list, which the app shows translated. `completesTasks` (default false; a list you keep keeps its own) makes moving a task into the list complete it.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the project’s list IDs, to keep that list.",
"type": "string"
},
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"type": "string"
},
"completesTasks": {
"type": "boolean"
}
},
"required": [
"name"
]
}
},
"customFieldIds": {
"maxItems": 50,
"uniqueItems": true,
"description": "The custom fields the project's tasks have, in order: IDs of the office's fields (`GET /v1/task-custom-fields`), at most 50. Replaces the whole list. A value a task holds stays when its field leaves the project, and can then only be cleared.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
"sharing": {
"additionalProperties": false,
"description": "Who the project is shared with, besides its owner (its creator, who always keeps the `owner` role): the office's admins, its teammates (sharing with teammates shares with admins too, at least as much) and its guests, people by user ID, and teams by team ID (`GET /v1/teams`), each as a `viewer` (reads its tasks) or an `editor` (can also add tasks to it, change its tasks, change the project and share it). Everyone it is shared with sees its tasks. Default: shared with no one but you.",
"type": "object",
"properties": {
"admins": {
"description": "The office's admins (owner role).",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"teammates": {
"description": "Every teammate of the office (contributor role), and its admins with them.",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"guests": {
"description": "The office's guests.",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"users": {
"maxProperties": 99,
"description": "People, by user ID: teammates, guests or apps of the office. Not the owner, who is never listed.",
"type": "object",
"patternProperties": {
"^(.*)$": {
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
}
}
},
"teams": {
"description": "Teams, by team ID. Each must be an active team of the office, and the office's plan must include teams.",
"type": "object",
"patternProperties": {
"^(.*)$": {
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
}
}
}
}
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"name",
"color"
]
}
update_task_projectChange a project's name, color, lists, custom fields or sharing; lists, customFieldIds and sharing are each replaced whole. Name a list you keep by its id (from list_task_projects); a list without an id is new, and tasks in a list you leave out move to the first list. Needs the editor or owner role.
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the project is still at that version; otherwise 409. Omit it to change the project as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"description": "Not unique: two projects in an office can share a name.",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
},
"lists": {
"minItems": 1,
"maxItems": 50,
"description": "The project's board: its lists (sections), in order, at least one and at most 50. Replaces the whole board. A list with the `id` of one of the project's lists keeps it, with its tasks; a list without an `id`, or with an id the board doesn't have, is a new list. Tasks in a list left out move to the first list. A list that keeps the English name of a default list (`To Do`, `In Progress`, `Done`) stays a default list, which the app shows translated. `completesTasks` (default false; a list you keep keeps its own) makes moving a task into the list complete it.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the project’s list IDs, to keep that list.",
"type": "string"
},
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"type": "string"
},
"completesTasks": {
"type": "boolean"
}
},
"required": [
"name"
]
}
},
"customFieldIds": {
"maxItems": 50,
"uniqueItems": true,
"description": "The custom fields the project's tasks have, in order: IDs of the office's fields (`GET /v1/task-custom-fields`), at most 50. Replaces the whole list. A value a task holds stays when its field leaves the project, and can then only be cleared.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
}
},
"sharing": {
"additionalProperties": false,
"description": "Who the project is shared with, besides its owner (its creator, who always keeps the `owner` role): the office's admins, its teammates (sharing with teammates shares with admins too, at least as much) and its guests, people by user ID, and teams by team ID (`GET /v1/teams`), each as a `viewer` (reads its tasks) or an `editor` (can also add tasks to it, change its tasks, change the project and share it). Everyone it is shared with sees its tasks. Replaces the whole sharing; `{}` leaves only the owner. Needs the editor or owner role.",
"type": "object",
"properties": {
"admins": {
"description": "The office's admins (owner role).",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"teammates": {
"description": "Every teammate of the office (contributor role), and its admins with them.",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"guests": {
"description": "The office's guests.",
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
},
"users": {
"maxProperties": 99,
"description": "People, by user ID: teammates, guests or apps of the office. Not the owner, who is never listed.",
"type": "object",
"patternProperties": {
"^(.*)$": {
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
}
}
},
"teams": {
"description": "Teams, by team ID. Each must be an active team of the office, and the office's plan must include teams.",
"type": "object",
"patternProperties": {
"^(.*)$": {
"anyOf": [
{
"const": "viewer",
"type": "string"
},
{
"const": "editor",
"type": "string"
}
]
}
}
}
}
}
},
"required": [
"projectId"
]
}
delete_task_projectDelete a project you own, with its views. Its tasks stay, without it; people who saw them only through the project lose sight of them. Confirm with the user first.
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
}
},
"required": [
"projectId"
]
}
create_task_custom_fieldCreate a custom field in the office's library: number (with precision), text, tags, single_select or multi_select (with options, each a name and #RRGGBB color). Names are unique in the office. Add it to a project with update_task_project customFieldIds, then set values on tasks in customFieldValues. Pass a stable idempotencyKey to make a retry return what the first call made (remembered 24 hours).
{
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"description": "Unique in the office, ignoring case; otherwise 409 task_custom_field_name_taken.",
"type": "string"
},
"type": {
"description": "What its values are: `number`, `text`, `tags` (any number of free texts), `single_select` (one option) or `multi_select` (any number of options). It never changes.",
"anyOf": [
{
"const": "number",
"type": "string"
},
{
"const": "text",
"type": "string"
},
{
"const": "tags",
"type": "string"
},
{
"const": "single_select",
"type": "string"
},
{
"const": "multi_select",
"type": "string"
}
]
},
"description": {
"maxLength": 500,
"type": "string"
},
"options": {
"maxItems": 200,
"description": "A select field's options, in order, at most 200. An option without an `id` is new. `enabled` defaults to true for a new option; a disabled option can't be set, and tasks that hold it keep it. Select fields only.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the field's option IDs, to keep that option.",
"type": "string"
},
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"name",
"color"
]
}
},
"precision": {
"minimum": 0,
"maximum": 6,
"description": "A number field's decimal places, 0 to 6 (default 0): its values are rounded to them. Number fields only.",
"type": "integer"
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"name",
"type"
]
}
update_task_custom_fieldChange a field's name, description, options or decimal places; its type never changes. options is replaced whole, but an option can't be removed, only disabled (enabled: false); an option without an id is new.
{
"additionalProperties": false,
"type": "object",
"properties": {
"fieldId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Custom field ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the field is still at that version; otherwise 409. Omit it to change the field as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"type": "string"
},
"description": {
"maxLength": 500,
"description": "Null clears it.",
"type": [
"string",
"null"
]
},
"options": {
"maxItems": 200,
"description": "A select field's options, in order, at most 200. An option without an `id` is new. `enabled` defaults to true for a new option; a disabled option can't be set, and tasks that hold it keep it. Replaces the whole list, except that an option can't be removed: leaving one out returns 400, so disable it instead. An option you keep keeps its `enabled` unless you send it.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "One of the field's option IDs, to keep that option.",
"type": "string"
},
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"name",
"color"
]
}
},
"precision": {
"minimum": 0,
"maximum": 6,
"type": "integer"
}
},
"required": [
"fieldId"
]
}
delete_task_custom_fieldDelete a custom field (its creator or an office admin): it leaves every project and its values are cleared from every task. This can't be undone; confirm with the user first.
{
"additionalProperties": false,
"type": "object",
"properties": {
"fieldId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Custom field ID.",
"type": "string"
}
},
"required": [
"fieldId"
]
}
create_task_labelCreate a label in the office's library: a name (unique in the office) and a #RRGGBB color. Check list_task_labels first for one that already fits. Pass a stable idempotencyKey to make a retry return what the first call made (remembered 24 hours).
{
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"description": "Unique in the office, ignoring case; otherwise 409 task_label_name_taken.",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"name",
"color"
]
}
update_task_labelRename or recolor a label.
{
"additionalProperties": false,
"type": "object",
"properties": {
"labelId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Label ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the label is still at that version; otherwise 409. Omit it to change the label as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 28,
"pattern": "\\S",
"type": "string"
},
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "A hex color, `#RRGGBB`.",
"type": "string"
}
},
"required": [
"labelId"
]
}
delete_task_labelDelete a label: every task lets go of it. Its creator can while no task carries it; an office admin always. Confirm with the user first.
{
"additionalProperties": false,
"type": "object",
"properties": {
"labelId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Label ID.",
"type": "string"
}
},
"required": [
"labelId"
]
}
create_task_viewCreate a saved view of a project, a tab everyone it is shared with sees: layout list or board, fields (list columns: list, status, labels, assignee, dueDate, project, or cf:<type>:<fieldId>; board cards: custom fields only), filter (a tree of {and:[...]}, {or:[...]}, {not:...} over conditions {field, op, value or values}; see the filter field's description), sort (up to 3 {field, direction}) and group (a list view only: section:<projectId>, status or cf:single_select:<fieldId>). It goes after the last tab unless placed with beforeViewId or afterViewId. Needs the editor or owner role. Pass a stable idempotencyKey to make a retry return what the first call made (remembered 24 hours).
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"layout": {
"anyOf": [
{
"const": "list",
"type": "string"
},
{
"const": "board",
"type": "string"
}
]
},
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"description": "Absent: the layout's own name.",
"type": "string"
},
"fields": {
"maxItems": 60,
"uniqueItems": true,
"description": "The fields the view shows, in order, at most 60. A list view's columns: the built-in `list`, `status`, `labels`, `assignee`, `dueDate`, `project`, `createdAt`, `updatedAt` (`list` is the task's section), and custom fields as `cf:<type>:<fieldId>` (for example `cf:single_select:<fieldId>`); the task's name always shows. A board view's cards show custom fields only. Default: none.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"type": "string"
}
},
"filter": {
"description": "Which of the project's tasks the view shows: a tree of `{\"and\": [...]}`, `{\"or\": [...]}` and `{\"not\": ...}` over conditions `{\"field\", \"op\", ...}`, as the app's filter builder saves it. Fields: `statusId` (`eq`/`in` over the office's status IDs, as `GET /v1/task-statuses` lists them: a task matches when its `statusId` reads one of them), `status` (`eq`/`in` over the stored task statuses), `waitingOn` (`eq`/`in` of `waiting`, an open task that waits on at least one other open task, as the SoWork app's Blocked by sets it, and `notWaiting`; it is not the `blocked` status), `assignee` (`eq`/`in` user IDs, `isEmpty`), `collaborators` and `teams` (`hasAny`/`hasAll`, `isEmpty`), `labels` (`hasAny`/`hasAll` label IDs, `isEmpty`), `name` (`textContains`), `dueDate` (`eq`/`lt`/`lte`/`gt`/`gte` a `YYYY-MM-DD` day, `relativeDays`, `isEmpty`), `createdAt`, `completedAt` and `canceledAt` (`relativeDays`, `isEmpty`; `canceledAt` is set only while a task is canceled, so `{\"not\": {\"field\": \"canceledAt\", \"op\": \"isEmpty\"}}` is the canceled tasks), `source` (`eq`/`in` of `meeting`, `chat`, `external`, `manual`), `section:<projectId>` (`in` the project's list IDs) and custom fields `cf:<type>:<fieldId>` (number: `eq`/`lt`/`lte`/`gt`/`gte`, `isEmpty`; text: `textContains`, `isEmpty`; tags: `hasAny`/`hasAll`, `isEmpty`; single select: `eq`/`in` option IDs, `isEmpty`; multi select: `hasAny`/`hasAll`, `isEmpty`). A list of values goes in `values`, one value in `value`. `relativeDays` takes `from` and `to`, days after today in each viewer's time zone (negative is before today; overdue is `{\"to\": -1}`). A user ID may be `$me`, the person looking at the view. Absent: every task of the project."
},
"sort": {
"maxItems": 3,
"description": "How the view orders its tasks, at most 3 keys, each a field and a direction: `status`, `assignee`, `name`, `dueDate`, `createdAt`, `updatedAt`, `completedAt`, `canceledAt`, `source` or a custom field `cf:<type>:<fieldId>`. Empty: newest first; a board keeps each list in the board's order.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"field": {
"minLength": 1,
"maxLength": 128,
"type": "string"
},
"direction": {
"anyOf": [
{
"const": "asc",
"type": "string"
},
{
"const": "desc",
"type": "string"
}
]
}
},
"required": [
"field",
"direction"
]
}
},
"group": {
"additionalProperties": false,
"description": "What a list view groups its tasks by, one level: `section:<projectId>` (the project's sections, in the board's order), `status`, or a single select `cf:single_select:<fieldId>`. Board views don't group.",
"type": "object",
"properties": {
"field": {
"minLength": 1,
"maxLength": 128,
"type": "string"
},
"direction": {
"anyOf": [
{
"const": "asc",
"type": "string"
},
{
"const": "desc",
"type": "string"
}
]
}
},
"required": [
"field",
"direction"
]
},
"beforeViewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Where the view goes among the project's tabs: before or after another of its views (`beforeViewId` or `afterViewId`, not both). Default: the last tab.",
"type": "string"
},
"afterViewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Where the view goes among the project's tabs: before or after another of its views (`beforeViewId` or `afterViewId`, not both).",
"type": "string"
},
"idempotencyKey": {
"pattern": "^[A-Za-z0-9_-]{16,128}$",
"description": "Stable key for retrying creation, remembered for 24 hours. Required for app callers.",
"type": "string"
}
},
"required": [
"projectId",
"layout"
]
}
update_task_viewChange a view's name, fields, filter, sort or grouping, or move its tab with beforeViewId or afterViewId. Its layout never changes; null clears the name, filter and grouping.
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"viewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "View ID.",
"type": "string"
},
"expectedVersion": {
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version you last read. When sent, the change applies only if the view is still at that version; otherwise 409. Omit it to change the view as it is now.",
"type": "integer"
},
"name": {
"minLength": 1,
"maxLength": 50,
"pattern": "\\S",
"description": "Null: the layout's own name.",
"type": [
"string",
"null"
]
},
"fields": {
"maxItems": 60,
"uniqueItems": true,
"description": "The fields the view shows, in order, at most 60. A list view's columns: the built-in `list`, `status`, `labels`, `assignee`, `dueDate`, `project`, `createdAt`, `updatedAt` (`list` is the task's section), and custom fields as `cf:<type>:<fieldId>` (for example `cf:single_select:<fieldId>`); the task's name always shows. A board view's cards show custom fields only.",
"type": "array",
"items": {
"minLength": 1,
"maxLength": 128,
"type": "string"
}
},
"filter": {
"description": "Which of the project's tasks the view shows: a tree of `{\"and\": [...]}`, `{\"or\": [...]}` and `{\"not\": ...}` over conditions `{\"field\", \"op\", ...}`, as the app's filter builder saves it. Fields: `statusId` (`eq`/`in` over the office's status IDs, as `GET /v1/task-statuses` lists them: a task matches when its `statusId` reads one of them), `status` (`eq`/`in` over the stored task statuses), `waitingOn` (`eq`/`in` of `waiting`, an open task that waits on at least one other open task, as the SoWork app's Blocked by sets it, and `notWaiting`; it is not the `blocked` status), `assignee` (`eq`/`in` user IDs, `isEmpty`), `collaborators` and `teams` (`hasAny`/`hasAll`, `isEmpty`), `labels` (`hasAny`/`hasAll` label IDs, `isEmpty`), `name` (`textContains`), `dueDate` (`eq`/`lt`/`lte`/`gt`/`gte` a `YYYY-MM-DD` day, `relativeDays`, `isEmpty`), `createdAt`, `completedAt` and `canceledAt` (`relativeDays`, `isEmpty`; `canceledAt` is set only while a task is canceled, so `{\"not\": {\"field\": \"canceledAt\", \"op\": \"isEmpty\"}}` is the canceled tasks), `source` (`eq`/`in` of `meeting`, `chat`, `external`, `manual`), `section:<projectId>` (`in` the project's list IDs) and custom fields `cf:<type>:<fieldId>` (number: `eq`/`lt`/`lte`/`gt`/`gte`, `isEmpty`; text: `textContains`, `isEmpty`; tags: `hasAny`/`hasAll`, `isEmpty`; single select: `eq`/`in` option IDs, `isEmpty`; multi select: `hasAny`/`hasAll`, `isEmpty`). A list of values goes in `values`, one value in `value`. `relativeDays` takes `from` and `to`, days after today in each viewer's time zone (negative is before today; overdue is `{\"to\": -1}`). A user ID may be `$me`, the person looking at the view. Absent: every task of the project. Null: every task of the project."
},
"sort": {
"maxItems": 3,
"description": "How the view orders its tasks, at most 3 keys, each a field and a direction: `status`, `assignee`, `name`, `dueDate`, `createdAt`, `updatedAt`, `completedAt`, `canceledAt`, `source` or a custom field `cf:<type>:<fieldId>`. Empty: newest first; a board keeps each list in the board's order.",
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"properties": {
"field": {
"minLength": 1,
"maxLength": 128,
"type": "string"
},
"direction": {
"anyOf": [
{
"const": "asc",
"type": "string"
},
{
"const": "desc",
"type": "string"
}
]
}
},
"required": [
"field",
"direction"
]
}
},
"group": {
"description": "What a list view groups its tasks by, one level: `section:<projectId>` (the project's sections, in the board's order), `status`, or a single select `cf:single_select:<fieldId>`. Board views don't group. Null: not grouped.",
"anyOf": [
{
"additionalProperties": false,
"description": "What a list view groups its tasks by, one level: `section:<projectId>` (the project's sections, in the board's order), `status`, or a single select `cf:single_select:<fieldId>`. Board views don't group.",
"type": "object",
"properties": {
"field": {
"minLength": 1,
"maxLength": 128,
"type": "string"
},
"direction": {
"anyOf": [
{
"const": "asc",
"type": "string"
},
{
"const": "desc",
"type": "string"
}
]
}
},
"required": [
"field",
"direction"
]
},
{
"type": "null"
}
]
},
"beforeViewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Where the view goes among the project's tabs: before or after another of its views (`beforeViewId` or `afterViewId`, not both).",
"type": "string"
},
"afterViewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Where the view goes among the project's tabs: before or after another of its views (`beforeViewId` or `afterViewId`, not both).",
"type": "string"
}
},
"required": [
"projectId",
"viewId"
]
}
delete_task_viewDelete a project's view; a project keeps at least one. Confirm with the user first.
{
"additionalProperties": false,
"type": "object",
"properties": {
"projectId": {
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
"description": "Project ID.",
"type": "string"
},
"viewId": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "View ID.",
"type": "string"
}
},
"required": [
"projectId",
"viewId"
]
}
send_channel_messagePosts a Markdown message to a channel as the user. Supports emphasis, links, lists, quotes, and code; bare HTTP(S) URLs become clickable links, and explicit links accept absolute HTTP(S) or mailto: destinations. To mention someone, write a link: [@Name](user:<userId>) notifies that person, [@name](team:<teamId>) notifies the team's members in the channel (get team ids via list_teams), [#name](channel:<channelId>) links a channel, and [@channel](broadcast:channel) notifies everyone in the channel — use that only when the user explicitly asked to notify the whole channel. Only include mention links you intend to notify; to refer to someone without notifying them, write their name as plain text. Plain @name text stays literal. A mention link that does not resolve is rejected with invalid_mention. The user must be a member of the channel. This is a real, teammate-visible side effect — always confirm intent and exact text with the user before calling. Maximum text length is 40,000 characters; longer messages are rejected. Get a channelId via list_channels. To reply inside a thread rather than posting to the channel, pass parentId — the thread ROOT message id (a listed message's `id`, or a reply's `parentId`).
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"text": {
"minLength": 1,
"maxLength": 40000,
"description": "Message text in Markdown. Bare HTTP(S) URLs become clickable links; explicit links accept absolute HTTP(S) or mailto: destinations. Mention someone with a link: [@Name](user:<userId>), [@name](team:<teamId>), [#name](channel:<channelId>), or [@channel](broadcast:channel). Plain @name text stays literal and notifies no one.",
"type": "string"
},
"parentId": {
"format": "uuid",
"type": "string"
}
},
"required": [
"channelId",
"text"
]
}
send_direct_messageSends a Markdown 1:1 direct message to one teammate by user id. Supports emphasis, links, lists, quotes, and code; bare HTTP(S) URLs become clickable links, and explicit links accept absolute HTTP(S) or mailto: destinations. To mention someone, write a link: [@Name](user:<userId>) notifies that person, [#name](channel:<channelId>) links a channel, and [@channel](broadcast:channel) notifies everyone in the channel — use that only when the user explicitly asked to notify the whole channel. Only include mention links you intend to notify; to refer to someone without notifying them, write their name as plain text. Plain @name text stays literal. A mention link that does not resolve is rejected with invalid_mention. Get a recipientId via list_users. The recipient must be a teammate in this workspace; passing the OWN id of the user sends to their private conversation with themselves (their personal notes thread), which only they can see. This is a real, teammate-visible side effect — always confirm intent and exact text. Maximum text length is 40,000 characters. Returns the sent message; use the message's channel.id with send_channel_message for follow-up replies in the same conversation.
{
"additionalProperties": false,
"type": "object",
"properties": {
"recipientId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
},
"text": {
"minLength": 1,
"maxLength": 40000,
"description": "Message text in Markdown. Bare HTTP(S) URLs become clickable links; explicit links accept absolute HTTP(S) or mailto: destinations. Mention someone with a link: [@Name](user:<userId>), [#name](channel:<channelId>), or [@channel](broadcast:channel). Plain @name text stays literal and notifies no one.",
"type": "string"
}
},
"required": [
"recipientId",
"text"
]
}
create_channelCreates a public or private channel with the user as its owner, adding memberIds (user ids from list_users; teammates or apps, not guests). type is required; a private channel is visible only to its members. The name is stored lowercase with other characters turned into "-" (at most 60 characters after that). Names are not unique, so check list_channels before creating to avoid a duplicate. Posts join notices that every member sees — confirm with the user before calling.
{
"additionalProperties": false,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"maxLength": 255,
"description": "Channel name. Stored the way the app formats it: lowercase, with every run of characters other than letters and digits turned into one `-` (`Pye-Barker - PRO-260431` becomes `pye-barker-pro-260431`). At most 60 characters after formatting. Names are not unique.",
"type": "string"
},
"type": {
"anyOf": [
{
"const": "public",
"type": "string"
},
{
"const": "private",
"type": "string"
}
]
},
"description": {
"minLength": 1,
"maxLength": 1000,
"description": "What the channel is for, shown in its details.",
"type": "string"
},
"memberIds": {
"minItems": 0,
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
}
}
},
"required": [
"name",
"type"
]
}
update_channelChanges a channel's name or description; omitted fields stay as they are and description null clears it. Only the channel's owner (the member who created it) or a workspace owner may do this; others get forbidden. An archived channel can't be changed (channel_archived).
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"name": {
"minLength": 1,
"maxLength": 255,
"description": "Channel name. Stored the way the app formats it: lowercase, with every run of characters other than letters and digits turned into one `-` (`Pye-Barker - PRO-260431` becomes `pye-barker-pro-260431`). At most 60 characters after formatting. Names are not unique.",
"type": "string"
},
"description": {
"minLength": 1,
"maxLength": 1000,
"description": "What the channel is for, shown in its details.",
"type": [
"string",
"null"
]
}
},
"required": [
"channelId"
]
}
add_channel_membersAdds people to a channel by user id (from list_users), up to 100 at a time; anyone already in it is skipped. Each person added gets a notice everyone in the channel sees — confirm with the user first. Only the channel's owner (the member who created it) or a workspace owner may do this; others get forbidden.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"userIds": {
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"type": "array",
"items": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
}
}
},
"required": [
"channelId",
"userIds"
]
}
remove_channel_memberRemoves one person from a channel and posts a notice everyone in it sees — confirm with the user first. Removing someone who isn't in the channel changes nothing. The user can't remove themselves. Only the channel's owner (the member who created it) or a workspace owner may do this; others get forbidden.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
},
"userId": {
"pattern": "^[a-zA-Z0-9]{4,36}$",
"description": "An alphanumeric resource identifier.",
"type": "string"
}
},
"required": [
"channelId",
"userId"
]
}
archive_channelArchives a channel: it leaves everyone's channel list and becomes read-only until unarchived; its history stays. Any member except a guest may archive it (the general channel and channels everyone is added to automatically need a workspace owner). Archiving an archived channel changes nothing.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
}
},
"required": [
"channelId"
]
}
unarchive_channelUnarchives a channel, returning it to its members' channel lists and making it writable again. The same people who may archive a channel may unarchive it. Archived channels don't appear in list_channels, so take the id from the user or an earlier result.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
}
},
"required": [
"channelId"
]
}
delete_channelDeletes a channel and its messages for everyone. This cannot be undone — prefer archive_channel to keep the history, and always confirm with the user first. Only the channel's owner (the member who created it) or a workspace owner may do this; others get forbidden.
{
"additionalProperties": false,
"type": "object",
"properties": {
"channelId": {
"minLength": 1,
"type": "string"
}
},
"required": [
"channelId"
]
}
add_reactionAdds an emoji reaction to a chat message as the user — a real, teammate-visible action, so only react when the user asked for it. `type` accepts the emoji character itself (👍) or its shortcode ("+1", "eyes", "heart", "tada"); the response reports the canonical shortcode plus the resolved emoji. `messageId` is the id of a message returned by read_channel_messages, read_direct_messages, read_thread, or search_messages — never invent one. Re-adding a reaction you already added is a no-op. Returns the post-write count of members holding that reaction.
{
"additionalProperties": false,
"type": "object",
"properties": {
"messageId": {
"format": "uuid",
"type": "string"
},
"type": {
"minLength": 1,
"maxLength": 50,
"type": "string"
}
},
"required": [
"messageId",
"type"
]
}
remove_reactionRemoves the user's OWN reaction of the given `type` from a chat message — it cannot remove another member's reaction. `type` accepts the emoji character (👍) or its shortcode ("+1"), same as add_reaction. Removing a reaction that was never added is a no-op success. Returns the post-write count of members still holding that reaction.
{
"additionalProperties": false,
"type": "object",
"properties": {
"messageId": {
"format": "uuid",
"type": "string"
},
"type": {
"minLength": 1,
"maxLength": 50,
"type": "string"
}
},
"required": [
"messageId",
"type"
]
}
update_presenceUpdates your own presence in this workspace. Set availability ('available', 'busy', or 'away') and/or a textStatus. Omit a field to leave it unchanged; send textStatus as null to clear it. This changes how teammates see you.
{
"type": "object",
"properties": {
"availability": {
"anyOf": [
{
"const": "available",
"type": "string"
},
{
"const": "busy",
"type": "string"
},
{
"const": "away",
"type": "string"
}
]
},
"textStatus": {
"anyOf": [
{
"minLength": 1,
"maxLength": 256,
"type": "string"
},
{
"type": "null"
}
]
}
}
}
announcePosts an announcement to the whole workspace — a 10-second popup shown to every member, plus a message in the default public channel. Requires owner or contributor. This is a real, workspace-wide side effect — always confirm intent and the exact text with the user first. Maximum 100 characters.
{
"additionalProperties": false,
"type": "object",
"properties": {
"text": {
"minLength": 1,
"maxLength": 100,
"type": "string"
}
},
"required": [
"text"
]
}
ring_gongRings the gong for the whole workspace — a 10-second popup with the gong sound effect, shown to every member. Requires owner or contributor. This is a real, workspace-wide side effect — always confirm intent and the exact text with the user first. Maximum 100 characters.
{
"additionalProperties": false,
"type": "object",
"properties": {
"text": {
"minLength": 1,
"maxLength": 100,
"type": "string"
}
},
"required": [
"text"
]
}
searchChatGPT-compatible search across this workspace. Returns matching messages (full-text), teammates, and channels. Each result id is prefixed ("msg:...", "user:u_...", or "channel:ch_...") for use with the fetch tool. Claude and ChatGPT Developer Mode should prefer the dedicated search_messages / read_channel_messages tools.
{
"additionalProperties": false,
"type": "object",
"properties": {
"query": {
"minLength": 1,
"maxLength": 256,
"type": "string"
}
},
"required": [
"query"
]
}
fetchChatGPT-compatible fetch for ids returned by the search tool. Pass a prefixed id ("user:u_...", "channel:ch_...", or "msg:<channelId>:<messageId>"). Returns the teammate, a recent channel transcript, or the message's own text. A message is returned ALONE — no thread replies and no attachments; use read_thread for those. Pass ids from search verbatim — do not construct them.
{
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"minLength": 1,
"maxLength": 256,
"type": "string"
}
},
"required": [
"id"
]
}