​

Projects API

• sessions still execute work
• runs still represent concrete execution
• channels still hold public conversation

​

Endpoint inventory

• GET /v1/projects
• POST /v1/projects
• GET /v1/projects/{project_id}
• PUT /v1/projects/{project_id}
• DELETE /v1/projects/{project_id}

• GET /v1/projects/{project_id}/members
• POST /v1/projects/{project_id}/members
• DELETE /v1/projects/{project_id}/members/{member_id}

• GET /v1/projects/{project_id}/channels
• POST /v1/projects/{project_id}/channels
• DELETE /v1/projects/{project_id}/channels/{channel_id}

• GET /v1/projects/{project_id}/tasks
• POST /v1/projects/{project_id}/tasks
• GET /v1/projects/{project_id}/tasks/{task_id}
• PUT /v1/projects/{project_id}/tasks/{task_id}
• DELETE /v1/projects/{project_id}/tasks/{task_id}
• POST /v1/projects/{project_id}/tasks/{task_id}/start

​

List projects

• query
• status
• member_session_id
• channel_id

• active
• paused
• completed
• archived

​

Create a project

• project_id optional stable caller-selected identifier
• display_name required
• description optional
• status optional, defaulting to active
• members optional initial project members
• channel_links optional initial linked channels
• metadata optional caller metadata

{
  "project_id": "release-2026-q2",
  "display_name": "Release 2026 Q2",
  "description": "Coordinate the release across reviewer and implementer sessions.",
  "members": [
    {
      "member_id": "implementer",
      "member_kind": "session",
      "display_name": "Implementer",
      "session_id": "impl-session",
      "role": "implementation",
      "expertise_tags": ["rust"]
    },
    {
      "member_id": "release-manager",
      "member_kind": "human_actor",
      "display_name": "Release manager",
      "actor_id": "release-manager",
      "role": "operator"
    }
  ],
  "channel_links": [
    {
      "channel_id": "release-room",
      "role": "coordination",
      "default_for_new_tasks": true,
      "mirror_members": true
    }
  ]
}

• display_name is required
• channel ids must already exist
• one project cannot register the same session twice under different member ids

​

Project members

• member_id required stable identifier inside the project
• member_kind required: human_actor or session
• display_name required
• session_id optional for session members
• agent_id optional for session members
• actor_id optional for human_actor members
• role optional
• expertise_tags optional
• metadata optional

• session_id and agent_id are mutually exclusive
• omitting both on a session member falls back to member_id
• task ownership is only valid for session-backed members
• one session cannot appear twice in the same project under different member ids

​

Linked channels

• channel_id required existing daemon channel id
• role optional semantic label
• default_for_new_tasks optional boolean
• mirror_members optional boolean
• metadata optional

• at most one linked channel is kept as default_for_new_tasks=true
• when mirror_members=true, project members are mirrored into the linked channel
• mirrored channel member ids are namespaced as project:{project_id}:{member_id}
• if the current default link is removed and another link remains, the first remaining link becomes the new default

​

Project tasks

• project_task_id
• project_id
• title
• description
• status
• assignee_member_id
• primary_session_id
• latest_run_id
• discussion
• blocked_by
• output
• created_at_ms
• updated_at_ms
• metadata

• pending
• in_progress
• blocked
• completed
• failed
• cancelled

​

List project tasks

• query
• status
• assignee_member_id

​

Create a project task

• project_task_id optional stable caller-selected identifier
• title required
• description optional
• status optional, defaulting to pending
• assignment
• discussion_channel_id
• discussion_thread_root_message_id
• blocked_by
• latest_run_id
• output
• metadata

• assignee_member_id
• assignee_session_id
• assignee_agent_id

• the project must be active
• title is required
• assignments resolve to an existing project member
• only session-backed members can be task assignees
• discussion_channel_id and discussion_thread_root_message_id must be provided together
• explicit discussion channels must already be linked to the project
• latest_run_id, when set, must belong to the assignee session
• dependency ids must already exist in the same project
• self-dependency and dependency cycles are rejected

{
  "project_task_id": "review-routing",
  "title": "Review route-file changes",
  "description": "Inspect the release routing before rollout.",
  "assignment": {
    "assignee_member_id": "implementer"
  },
  "blocked_by": ["collect-release-notes"]
}

​

Update a project task

• title
• description
• status
• assignment
• clear_assignment
• discussion_channel_id
• discussion_thread_root_message_id
• clear_discussion
• blocked_by
• latest_run_id
• output
• clear_output
• metadata

• assignment still accepts exactly one of member/session/agent id
• latest_run_id is validated against the effective assignee session
• replacing blocked_by re-runs dependency validation and cycle checks

​

Delete a project task

​

Start a project task

• provider optional route override
• model optional model override
• kickoff_message optional replacement kickoff text when the daemon creates a new discussion thread
• metadata optional caller metadata attached to the spawned run

• the project must be active
• the task must be assigned
• the assignee must be a session-backed project member
• every dependency must already be completed
• terminal tasks must be reopened before start
• a second start is rejected while latest_run_id still points at a non-terminal run

1. if the task already has a valid linked discussion thread, the daemon reuses it
2. otherwise, if the project has one linked default channel, the daemon can create a kickoff thread there
3. otherwise, the run still starts without a public discussion thread
4. the daemon submits a normal input run in the assignee session
5. the task stores the new latest_run_id

• the created RunView

• queued run -> task stays pending
• every other current run state -> task becomes in_progress

​

Operational notes

• DELETE /v1/projects/{project_id} is rejected while the project still has tasks
• deleting a channel is rejected while any project still links it
• ending a session is rejected while it is still a project member
• ending a session is also rejected while it still owns non-terminal project tasks

​

Related reading

• Projects and project tasks
• Channels API
• Sessions and runs API