Tasks
Use kosuke tasks list <workspaceId> for one workspace and kosuke tasks list across your workspaces. Agent credentials stay within their workspace.
When creating a task with hintProjectId, attachments use the project's chat-session upload transport. The CLI stages batches larger than 20 MiB through /api/projects/{hintProjectId}/attachments when the operation advertises that path. Tasks without a hint project do not accept attachments.
| Method | Path | Description |
|---|---|---|
| GET | /api/organizations/{workspaceId}/tasks?status=&owners=&priorities=&labels=&createdBy=&project=&projects=&q=&doneSince=&limit=&cursor=&sortBy=&sortOrder=&needsYou=&includePrompt=&includeOpenCount=&workspace=&threadId= | List tasks in one workspace. Before you file or propose a ticket, read the open ones (--status todo,in_progress --include-prompt, following meta.pagination.nextCursor with --cursor) and judge overlap by meaning, not title words: work another task or session already covers gets no new ticket. |
| POST | /api/organizations/{workspaceId}/tasks | File a task. A hint files into that project; YOLO returns a Backlog item. From Sensei, ownerId is the member, or the teammate they name; leave sandboxSize to the member, who changes it in the task's Properties. Answers shareUrl: link the task's title to it. |
| GET | /api/organizations/{workspaceId}/tasks/{taskId} | Get a task and its execution details. |
| PATCH | /api/organizations/{workspaceId}/tasks/{taskId} | Edit a task. |
| DELETE | /api/organizations/{workspaceId}/tasks/{taskId} | Delete a task. |
| POST | /api/organizations/{workspaceId}/tasks/{taskId}/move | Move a Todo or In progress Personal task into a workspace. Members and Sensei only. |
| POST | /api/organizations/{workspaceId}/tasks/{taskId}/start | Start a Todo task. Members and Sensei only. sandboxSize and appStack set the task's Sandbox size and App stack as it starts; absent keeps what the task holds. The member's ask to start is the yes: start without reading back credits or sandboxes. A refusal leaves it in the Backlog: say what the platform answered and do not retry. |
| GET | /api/tasks?status=&owners=&priorities=&labels=&createdBy=&project=&projects=&q=&doneSince=&limit=&cursor=&sortBy=&sortOrder=&needsYou=&includePrompt=&includeOpenCount=&workspace=&threadId= | List tasks across your workspaces. Agent credentials stay in their workspace. includeOpenCount counts Todo and In progress with the same filters, independent of status and cursor. Before you file or propose a ticket, read the open ones (--status todo,in_progress --include-prompt, following meta.pagination.nextCursor with --cursor) and judge overlap by meaning, not title words: work another task or session already covers gets no new ticket. |
List responses are { data: Task[], meta: { pagination: { pageSize, hasMore, nextCursor } } }. Pass nextCursor as cursor for the next page. Ordering defaults to newest creation first. Choose --sort-by activity|created|priority and --sort-order asc|desc on tasks list, with or without a workspace, or sortBy and sortOrder in the API. Keep the same sort when following a cursor; another sort returns 400 Invalid cursor. Filters include comma-separated status (todo, in_progress, done, archived; every status when absent), owners (member IDs, me, none, any), priorities, createdBy (agent or member), project or projects, q and doneSince, which keeps only the Done and Archived tasks that reached that status since then.
Filter by label with --labels '["bug","ui"]' on tasks list, with or without a workspace (the API's labels query parameter is a URL-encoded JSON array). A task matches any selected label on its Chat Session, combined with the other filters. Tasks with no Chat Session never match. Names are trimmed, normalized to lowercase and deduplicated; at most 20 are accepted. Invalid JSON or names return 400 Invalid labels filter. [] means no label filter. Pagination and open counts follow the filter.
Read the available names and colors with kosuke tasks labels list <workspaceId> (GET /api/organizations/{workspaceId}/labels). It returns { data: [{ name, color }] }, one row per name sorted by name, across the workspace's repository catalogs, including unused labels and excluding Apps. The oldest repository holding a name supplies its color (creation time, then project ID). The hidden Personal organization works too. Access follows the task list; an agent or Cron credential without a member identity sees only its permitted projects.
GET /api/tasks also includes meta.workspaces with workspace IDs and names. includeOpenCount=true adds meta.openCount: Todo plus In progress across the same workspace and property filters, independent of status and pagination.
GET /api/organizations/{workspaceId}/tasks/{taskId} returns { data: TaskDetail }, with the task properties, chatSession, full session, description, createdBy, filedReason, doneAt, archivedAt, hintProjectName and the viewer's thread. Session-less tasks have null execution details.
File with kosuke tasks create <workspaceId> --title "Fix the export" --description "Include archived records". A member or Sensei may omit --hint-project. Sandbox and Cron callers must supply a hint and follow the session filing rules, including a reason. A hint into a YOLO project returns { data: { backlogItem } }; otherwise create returns { data: { task, sessionId } }.
Start takes projectId, an optional skill, and optional sandboxSize and appStack, which replace what the task holds. Members and Sensei may start. A draft stays in its filed project; a task without a session needs a deployed Collaboration project. Start preserves the activation response and structured refusal, and a refused activation leaves the task Todo for retry.
Update delegates execution properties to the session, and status (todo, done, archived) maps to its Backlog, Completed or Archived status under the session's rules: a Completed session cannot be archived. Without a session, only title, description, priority, ownerId, sandboxSize, appStack and status are editable; Archive keeps doneAt, and todo restores the task and clears both times. hintProjectId, sent alone with an optional ifRevision, files a Todo task with no repository in a deployed Collaboration project without starting it, and keeps its Assignee. The same project again succeeds; another project, or a task that is no longer Todo, returns 409. sandboxSize (small, medium, large, xlarge; left out, the project's size) and appStack (start, the default, or skip, which boots without the project's services) are refused with 409 SANDBOX_SETTINGS_LOCKED once the task's session has started; see Chat sessions. A write racing Start returns 409: reload the task before retrying. Deletes return 204.
A Todo task's Repository is the project Sensei filed it in, or the one chosen in the task modal; once set, it is read-only. Its Sandbox size and App stack stay editable until it starts. Cards open the task modal; Open chat is the only way to the conversation. Tasks without a session have text-only descriptions, with no artifacts until Start. They cannot be Card or MCP ship targets: name them by title and start them with tasks start.
The workspace Tasks page has Todo, In progress, Done and Archived (the last two for 7 days). Sensei files tasks; there is no New session button or ⌘J shortcut. Existing sessions create --status backlog continues to work.
kosuke tasks list <workspaceId> --status todo,in_progress
kosuke tasks list <workspaceId> --labels '["bug","ui"]'
kosuke tasks list --labels '["bug"]'
kosuke tasks labels list <workspaceId>
kosuke tasks get <workspaceId> <taskId>
kosuke tasks create <workspaceId> --hint-project <projectId> --title "Fix export" --description "Include archived records" --sandbox-size small --app-stack skip
kosuke tasks update <workspaceId> <taskId> --hint-project <projectId>
kosuke tasks update <workspaceId> <taskId> --status archived
kosuke tasks start <workspaceId> <taskId> --project-id <projectId> --skill ship
Lists are paginated; use --include-prompt for duplicate checks and read truncated descriptions with tasks get.
List with --include-prompt (includePrompt=true) to return prompt and promptTruncated: up to 4,000 characters of the description, or the linked session's first user message. Follow meta.pagination.nextCursor for subsequent pages.
Create returns shareUrl, the absolute workspace Tasks link opening the task, and keeps sessionId for execution commands. With a hint project, --attach <path> (repeat per file) uploads attachments through multipart to the draft session. Attachments without a hint project return 400 because descriptions without a session are text only.