Add work to the Backlog and start it later

Add a chat session to the Backlog to record the work now and start it later. A Backlog session holds its prompt and uses no sandbox until it starts. Starting it runs the prompt as the first turn.

1. Add the session to the Backlog

curl -s -X POST "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions" \
  -H "Authorization: Bearer $KOSUKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Migrate the jobs table",
    "content": "Move the jobs table to the new schema and backfill the existing rows.",
    "status": "backlog",
    "priority": "high"
  }' > backlog.json

SESSION_ID=$(jq -r '.data.session.id' backlog.json)

Field	Required	Values
`content`	Yes	The prompt. It becomes the first message when the session starts.
`status`	Yes	`backlog`. Leave it out and the session starts at once.
`title`	No	Up to 255 characters. Kosuke writes one from the prompt when you leave it out.
`priority`	No	`urgent`, `high`, `medium`, `low` or `none`.
`ownerId`	No	The user id of the member to assign as the Assignee. Leave it out for an unassigned session. `kosuke workspaces members <workspaceId>` lists each member's `id`.
`model`	No	A model id such as `anthropic:sonnet-5-5__medium`. Without one, the session starts on its Assignee's Default Model.
`startBranch`	No	The branch to start from, when it differs from the project's usual starting branch.

The response answers 201:

{
  "data": {
    "session": { "id": "7a3f0b92-…", "title": "Migrate the jobs table", "status": "backlog", "priority": "high" },
    "shareUrl": "https://app.kosuke.ai/projects/…"
  }
}

shareUrl opens the session on the project's board. To attach files, send the same fields as multipart/form-data with the files, or use --attach with the CLI:

kosuke sessions create "$PROJECT_ID" --content "Move the jobs table to the new schema." \
  --status backlog --priority high --attach schema.png

You can file Backlog sessions while the project deploys, and while the workspace is blocked on billing.

2. Change the prompt before it starts

Rewrite the prompt, the priority, the model or the Assignee while the session is in the Backlog. This request takes multipart/form-data:

curl -s -X PATCH "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions/$SESSION_ID/prompt" \
  -H "Authorization: Bearer $KOSUKE_API_KEY" \
  -F "content=Move the jobs table to the new schema, backfill it, and drop the old columns." \
  -F "priority=urgent"

Field	Values
`content`	The new prompt. Required.
`priority`	`urgent`, `high`, `medium`, `low` or `none`.
`model`	A model id.
`ownerId`	A member's user id, or an empty string to unassign.
`retainedAttachmentIds`	A JSON array of the attachment ids to keep. Attachments you leave out are removed. Leave the field out to keep them all.

With the CLI, run kosuke sessions edit-prompt. A session that has already started answers 400.

3. Start it

curl -s -X POST "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions/$SESSION_ID/activate" \
  -H "Authorization: Bearer $KOSUKE_API_KEY" > start.json

CHAT_JOB_ID=$(jq -r '.data.chatJobId' start.json)

{
  "data": {
    "session": { "id": "7a3f0b92-…", "status": "active" },
    "chatJobId": "d18e5c47-…",
    "jobNumber": 1
  }
}

Kosuke creates the branch, starts a sandbox and runs the saved prompt as the first turn. Starting an unassigned session makes you its Assignee. Follow the turn with chatJobId, as Follow a turn shows.

With the CLI, run kosuke sessions activate <projectId> <sessionId>. The MCP server's ship tool starts a Backlog session when you pass its sessionId.

Starting a session that is already Active or Under Review answers 200 with its latest job.

Errors

Status	Code	Why	What to do
400	`BAD_REQUEST`	The session is Archived or Completed, its prompt is empty, or a turn is running. The Assignee may have no access to the session's model. The workspace may be at its concurrent sandbox limit, or the project's GitHub access may need reconnecting. `error` says which.	Act on `error`. For the sandbox limit, free a slot and start again.
402	`CREDIT_LIMIT_REACHED`	The workspace is blocked on billing.	Stop until an admin sorts out billing.
409	`DEPLOY_IN_PROGRESS`	The project is deploying.	Start the session once the deploy ends.
409	`SESSION_BUSY`	The session is changing, for example because another start is under way.	Try again.
409	`SESSION_CHANGED`	The session changed while it was starting.	Read it again, then try again.

Responses and errors has the full list.

1. Add the session to the Backlog​

2. Change the prompt before it starts​

3. Start it​

Errors​

Next steps​

1. Add the session to the Backlog

2. Change the prompt before it starts

3. Start it

Errors

Next steps