Sessions
Sessions are coding sessions: an AI coding agent plans and builds work from your tasks or bug reports in your repositories, then opens pull requests. Start a session and choose its repositories, have the agent draft a plan and build it, answer its questions or approve its plan, and review, merge or close its pull requests. Read a session's conversation, start or stop its live preview, or let your own coding agent pick up a session, read its context and ask you questions. See Code.
Get the session workflow skill markdown for a workspace
Returns the Productmind workflow skill markdown the agent should follow when working on tasks in this workspace. The markdown describes the workflow protocol and the order in which to call its tools.
path Parameters
workspaceIdWorkspace UUID
Get the session workflow skill markdown for a workspace › Responses
Session workflow skill markdown
Get rendered context for a session's tasks
Returns a markdown document describing the session, feature, and every task in the session, plus recent task and session log entries. Pass the same taskIds you intend to use for start-task-work. All tasks must belong to the same session (or none of them have a session). The response is markdown so the agent can read it directly without parsing JSON.
path Parameters
workspaceIdWorkspace UUID
query Parameters
taskIdsComma-separated list of task UUIDs in the session.
Get rendered context for a session's tasks › Responses
Session context (markdown)
Check whether a coding session would have anything to work in
Call this BEFORE proposing a coding session, and pass what you intend to hand over: the taskIds for a plan session, the bugReportIds for a bug-fix session, neither for a Live session. It answers whether a session created right now would actually clone code: ready is true only when it resolves at least one repository AND a sandbox to run in. When ready is false, each entry in blockers carries a message written for the user - relay it, and do not create the session until it is resolved. applications lists the workspace's applications (repoName null means no repository is connected, so it cannot help); ask the user which ones the work belongs to and pass their ids to the create call as applicationIds. sandboxes is present only when a sandbox still has to be chosen. repositories is what the session would clone, with via saying how each got there. When the workspace has turned Productmind cloud sessions off and the person has no Productmind agent online, ready is false with the no_local_agent blocker: nothing you pass fixes it, so relay its message (they start pm agent on their machine) and do not create the session. Each entry of repositories says whether it is readOnly: an application on it is read-only, so the session would read it for context and never push to it or open a pull request on it.
path Parameters
workspaceIdWorkspace UUID
query Parameters
taskIdsComma-separated task uuids the session would be scoped to — their applications count toward the repositories.
bugReportIdsComma-separated bug report uuids a bug-fix session would be scoped to - their applications count toward the repositories.
applicationIdsComma-separated application uuids to include, as if they had been passed to create-session-with-tasks.
sandboxIdEvaluate against this sandbox instead of the workspace default.
Check whether a coding session would have anything to work in › Responses
What a session created with this scope would reach
Create a new session and atomically attach tasks
Workflow-native session creation. Creates a PLAN session with a deliberately minimal input (taskIds, plus an optional name and description) and atomically attaches every task in taskIds to it. No plan is written for you: the session description holds exactly the description you pass, and stays empty without one. On a handoff (originChatId), pass the agreed plan as description in this call: the plan is drafted during it, so a later write lands after drafting has started. Without originChatId, publish the plan with update-session-description once it is agreed. Never pass a branch name: it is always derived server-side. Omit name and the server derives the whole session from the tasks: the name from their titles, the working branch as task/<slug-of-first-task-title>-<timestamp>, the workspace default sandbox, and the repositories of the Applications those tasks reach (via each task's feature, and via any direct task-to-application relationship) layered on top of the sandbox's. Pass name to keep control of the naming, which also opts out of that repo layering and leaves the branch as session/<slug-of-name>-<timestamp>, except on a handoff, where the sandbox and the repos are always resolved. WHEN YOU PASS originChatId this endpoint REFUSES a session that would reach no repository or no sandbox, because a handoff drafts its plan immediately and would otherwise plan against an empty checkout: call check-session-scope first, relay what it says is missing, and pass the user's answer as applicationIds / sandboxId. A task held by a session that is still open is refused with 409, before anything is created: the message names the task and the session (for example TASK-12 is already in SSID-4 (In Progress)) and is written to be relayed as is, and errors.holderSessionId carries the holding session's id. A finished session (completed, rolled back, failed or cancelled) and a draft still in planning do not hold their tasks: the new session attaches the task beside them. If task attach fails after the session is created, the session is deleted as compensation. With originChatId, a workspace that turned Productmind cloud sessions off refuses the handoff with 409 coding.local_agent_required before anything is created when the person has no Productmind agent online (check-session-scope reports it first as no_local_agent). Pass readOnlyApplicationIds for applications whose repositories the session should only read for context: they are attached read-only, so nothing is ever committed, pushed or opened as a pull request on them.
path Parameters
workspaceIdWorkspace UUID
Create a new session and atomically attach tasks › Request Body
taskIdsTasks to attach to the new session. A task held by a session that is still open (anything but a draft in planning, or a finished session: completed, rolled back, failed or cancelled) is refused with a 409 naming both. The first id also names the working branch (task/<slug-of-its-title>-<timestamp>).
nameHuman-readable session name (e.g. 'Ticket dashboard v1'). Omit to have it derived from the task titles. The branch name is derived server-side either way; do not pass a branch name.
descriptionThe session's description, in markdown: the plan document a person opening the session reads, and the brief a coding agent drafts its plan from. Nothing fills it in for you: it is not copied from the conversation or derived from the tasks, so a session created without it has an empty description. When a plan or approach was agreed, pass it here in full (goal, approach, decisions, constraints, how to tell it is done), opening with a one-line summary. With originChatId this is the only way to hand it over, because the plan is drafted during this call.
originChatId^([0-9a-fA-F]{8}-[0-…The assistant conversation this session is being created FROM — pass the Conversation id from your context whenever you propose a session inside a conversation. Links the session to it (the conversation becomes the coding agent's context and is latched to the session) and drafts the plan immediately.
applicationIdsApplications whose repositories this session should work in, added on top of the ones the sandbox and the tasks already reach. Pass the ids the user pinned in the conversation when check-session-scope said the session would otherwise reach no repository. An application with no connected repository contributes nothing. Each one named here also runs in the session's sandbox, even when another sandbox lists it.
readOnlyApplicationIdsApplications whose repositories this session should READ for context only: each is attached like applicationIds, but read-only in this session, so the coding agent reads its code and nothing is ever committed, pushed or opened as a pull request on it. A repository an application already makes read-only (its Read-only setting) stays read-only in every session, whether or not it is named here. An application in both lists is read-only.
sandboxId^([0-9a-fA-F]{8}-[0-…The sandbox (the container the session runs in) to bind. Omit to use the workspace default - only pass one when check-session-scope reported no default and the user chose.
With originChatId only: where the plan drafted in this call runs, as the person chose it on the hand-off card. Omit it to let the server pick: the person's online Productmind agent, else the cloud.
Create a new session and atomically attach tasks › Responses
The created session, with attached tasks under items
Launch a bug-fix session from bug reports
Creates a BUGFIX session scoped to the given bug reports (attached as bug_report items). Repositories are pre-populated from the workspace default sandbox's applications PLUS the repositories of every Application the bugs are related to, both directly (bug to application) and one hop away (bug to feature to application), deduped. Without originChatId the session is left in in_planning for the user to review and draft. WITH originChatId (a handoff from a conversation) the fix plan is drafted immediately, so pass the agreed approach as description in this call, and the endpoint REFUSES a session that would reach no repository or no sandbox: call check-session-scope with the bugReportIds first, relay what it says is missing, and pass the user's answer as applicationIds / sandboxId. A handoff is also refused with 409 coding.local_agent_required, before anything is created, while the workspace has Productmind cloud sessions turned off and the person has no Productmind agent online. An explicit repository is refused with 409, before anything is created, when its workingBranch is a base, development or production branch of the workspace or of one of its applications, or equals its own base branch (session_working_branch_protected_name); with a session's credential, any workingBranch (session_working_branch_renamed_by_a_person) and a baseBranch that is a production branch (session_working_branch_protected_name) are refused too. Pass readOnlyApplicationIds for applications whose repositories the session should only read for context: they are attached read-only, so nothing is ever committed, pushed or opened as a pull request on them.
path Parameters
workspaceIdWorkspace UUID
Launch a bug-fix session from bug reports › Request Body
bugReportIdsBug reports to attach to the new bug-fix session. Their related Applications' repos are auto-added on top of the default sandbox's. The first id also names the working branch (bugfix/<slug-of-its-title>-<timestamp>).
Sandbox to bind the session to. Omit to use the workspace default - only pass one when check-session-scope reported no default and the user chose.
App only - omit. Explicit repos to attach at create. When provided (even empty) it is honored exactly, overriding BOTH the sandbox-derived repos and the bug-related-Application layering; omit to derive them server-side.
descriptionThe session's description, in markdown: the plan document a person opening the session reads, and the brief a coding agent drafts its plan from. Nothing fills it in for you: it is not copied from the conversation or derived from the tasks, so a session created without it has an empty description. When a plan or approach was agreed, pass it here in full (goal, approach, decisions, constraints, how to tell it is done), opening with a one-line summary. With originChatId this is the only way to hand it over, because the plan is drafted during this call.
originChatId^([0-9a-fA-F]{8}-[0-…The assistant conversation this session is being created FROM - pass the Conversation id from your context whenever you propose a bug-fix session inside a conversation. Links the session to it (the conversation becomes the coding agent's context and is latched to the session) and drafts the fix plan immediately.
applicationIdsApplications whose repositories this session should work in, added on top of the ones the sandbox and the bug reports already reach. Pass the ids the user pinned in the conversation when check-session-scope said the session would otherwise reach no repository. Each one named here also runs in the session's sandbox, even when another sandbox lists it.
readOnlyApplicationIdsApplications whose repositories this session should READ for context only: each is attached like applicationIds, but read-only in this session, so the coding agent reads its code and nothing is ever committed, pushed or opened as a pull request on it. A repository an application already makes read-only (its Read-only setting) stays read-only in every session, whether or not it is named here. An application in both lists is read-only.
With originChatId only: where the plan drafted in this call runs, as the person chose it on the hand-off card. Omit it to let the server pick: the person's online Productmind agent, else the cloud.
Launch a bug-fix session from bug reports › Responses
The created bug-fix session, with attached bug reports under items
Start a code chat
Starts a code chat: a conversation with the coding agent about the code of the applications you pass, and of a feature when featureId names one. Use it when the person wants to dig into the code before deciding anything: how something is built, where a change would go, whether it is feasible, how to approach it technically. Ask first: the call is a hand-off the person approves, and each answer the coding agent gives is a coding run that uses AI credits. Settle the applications with the person before calling (check-session-scope lists them; one whose repoName is null has no repository). The repositories are checked out read-only and no code is ever changed, committed or pushed; when the person asks, the coding agent can create and update tasks, features and bug reports for them, as them. The chat is private to the person. Pass originChatId (the Conversation id in your context): that conversation carries on with the coding agent, which is handed it as context, and it stays private. Write message to stand on its own: the question the coding agent answers first. Once you have called it, stop: the coding agent answers in the same conversation. The chat can later become a plan session: the person asks the coding agent for a plan, or chooses Draft the plan. Refused with a 400 when none of the applications has a repository, and with a 409 (coding.local_agent_required) when cloud sessions are turned off for the workspace and the person has no Productmind agent online. A code chat's own coding agent cannot start another (409).
path Parameters
workspaceIdWorkspace UUID
Start a code chat › Request Body
messageThe first message the coding agent answers, written to stand on its own: what the person wants to understand or decide about the code, in their terms (for example 'How does refund approval work in the code, and could it be split out of checkout?'). The agent also reads the conversation passed as originChatId.
applicationIdsThe applications whose code the chat reads: their repositories are checked out read-only. Pass your best choice from the conversation (check-session-scope lists the workspace's applications; one whose repoName is null has no repository and cannot help): the person confirms or changes them on the hand-off card. With sandboxId, the sandbox's own applications are read too. At least one application read must have a repository.
sandboxId^([0-9a-fA-F]{8}-[0-…The sandbox the chat runs in, and the plan it may become: its own applications' code is read too. Omit it unless the person chose one; a plan drafted from the chat then runs in the workspace's default sandbox.
Where the coding agent runs, as the person chose it: omit it unless they did. The server then picks: their online Productmind agent, else the cloud.
featureId^([0-9a-fA-F]{8}-[0-…The feature or component the discussion is about, when it is about one: the chat is linked to it, its linked applications' code is checked out too, and the agent may propose corrections to its document. Omit it for a question about the code in general.
originChatId^([0-9a-fA-F]{8}-[0-…The conversation this chat continues: the Conversation id in your context. The coding agent is handed that conversation as context, and the conversation carries on with the coding agent. It stays private to the person. Only the conversation's owner may pass it.
attachmentIdsApp only - omit. Images uploaded by the composer against draftChatId, moved onto the new chat.
draftChatId^([0-9a-fA-F]{8}-[0-…App only - omit. The composer's draft conversation the attachmentIds were uploaded against.
clientSessionId^([0-9a-fA-F]{8}-[0-…App only - omit. An id the app minted for the new chat: the session is stored under an id derived from it, and a repeat with the same value answers the chat already started.
clientMessageId^([0-9a-fA-F]{8}-[0-…App only - omit. An id the app minted for the first message: its transcript row is stored under an id derived from it.
Start a code chat › Responses
The code chat already started under this clientSessionId, answered again: nothing is created or sent
Launch a coding session from feature requests
Creates ONE plan session for the given feature requests. A session works on tasks, so each request first becomes a task: a New or In Review request is promoted to a new task (its title, description and priority, under the newest feature the request is linked to, if any), and a request already promoted to a task reuses that task instead of being promoted again. The session is then created as a task launch with no name: its name comes from the task titles, its working branch from the first request's task, and it binds the workspace default sandbox and moves its tasks to In Progress. Besides the sandbox's repositories it attaches the repositories of the applications the requests are linked to, directly or through a linked feature. Every request is checked before anything is written: a request promoted to a feature, a merged or rejected one, or one whose task no longer exists is refused with a 409 naming each refused request, and a reused task held by a session that is still open is refused with a 409 naming the task and the session. When the workspace requires a decision for promoting a request, send it as decision; without it the call is refused with a 400 before anything is written. If the session cannot be created after the requests were promoted, they stay promoted with their tasks, and a retry reuses those tasks. Requires both the session create and the feature request update permissions.
path Parameters
workspaceIdWorkspace UUID
Launch a coding session from feature requests › Request Body
featureRequestIdsFeature requests to launch the session from, in order. Each New or In Review request is promoted to a task; a request already promoted to a task reuses that task. The first request's task names the working branch.
The decision recorded for promoting the requests, when the workspace requires one for that transition. One decision is recorded for each request this call promotes; a request that reuses its task records none.
Launch a coding session from feature requests › Responses
The created session, with the requests' tasks attached under items
List the caller's current sessions
The signed-in user's live work: every session assigned to them (or created by them) that an agent is mid-turn on or that is waiting on them, plus their five most recently updated sessions in any status. Ordered most recently updated first and capped. Returns an empty list for a service-auth caller, which has no user to have work.
path Parameters
workspaceIdWorkspace UUID
List the caller's current sessions › Responses
The caller's current sessions
List where a workspace's sessions run
Every runner the workspace's sessions have run on, each once: Productmind's cloud (cloud), each Productmind agent by its id and the name its most recent session recorded, a coding agent working through MCP (mcp), and sessions not started yet (none). Ordered as the sessions list groups them. A key is a value the list's runner filter takes.
path Parameters
workspaceIdWorkspace UUID
List where a workspace's sessions run › Responses
The runners, in grouping order
List sessions in a workspace
Returns all sessions for a workspace with optional filtering by status, type, date range, or linked item (feature/task).
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
statusFilter by session status (single value or array)
categoryFilter by session category (single value or array)
fromFilter sessions from this date (ISO 8601)
toFilter sessions to this date (ISO 8601)
taskIdFilter sessions containing this task ID
featureIdFilter to the sessions working on this feature or its sub-features: through their tasks, or because they were started from it
unlinkedOnly include sessions with no release linked
tagsComma-separated tag names to filter by
assigneeIdFilter by assignee: a user or team UUID (single value, or a comma-separated list). Only sessions assigned to one of the given users/teams are returned; unassigned sessions are excluded. Over HTTP the literal my-teams stands for every team the caller belongs to, and my-sessions for the caller's own sessions: the ones assigned to them or started by them, assigned or not. for-me adds the views of the caller's teams to that (assigned to the team, started from a feature in its area, or holding a task or bug report in its view): the sidebar's Code counts.
teamIdFilter to a TEAM's area: a team UUID, or a comma-separated list of them (items in the area of ANY listed team match). my-teams stands for every team the caller belongs to. An item is in a team's area when it is assigned to the team, or sits under a feature assigned to it, at any depth: a feature's sub-features, their tasks and sub-tasks, the bug reports linked to those features and tasks, and the coding sessions working on them. Unlike assigneeId, which matches only items assigned directly. A user id matches nothing, and so does my-teams for a caller on no team.
runnerFilter by where a session runs: cloud (Productmind's cloud), mcp (the caller's own coding agent through MCP), none (not started yet), or the UUID of a Productmind agent. One value or a comma-separated list; a session matching any of them is returned. Unknown values are ignored, and a filter with none left returns no sessions.
activityAfter^(?:(?:\d\d[2468][04…Only the items with activity after this ISO 8601 instant (for example 2026-10-26T09:00:00Z): for a session its last activity, or its last update when it has none; for every other list its last update (updatedAt). Send it with limit=1 and read pagination.total to count what changed since then. The response names the instant it applied in filters.activityAfter. A value that is not an ISO 8601 instant is refused with 400.
List sessions in a workspace › Responses
List of sessions
Create a session
Create a new session. Set category to 'plan' (plan-first workflow, the default) or 'live' (build in a running preview, the plan written last). Omit category to default to 'plan'. A 'live' session created with firstMessage, or from a conversation (originChatId), starts its preview at once and sends firstMessage to the coding agent as soon as the preview is ready; it never drafts a plan. That is the handoff for a Live conversation: pass category: "live", originChatId and firstMessage, with no tasks, and featureIds when the session builds a feature. With originChatId or firstMessage the endpoint REFUSES a session that would reach no repository or no sandbox: call check-session-scope first and pass the user's answer as applicationIds / sandboxId. Because such a create starts work at once, it is also refused with 409 coding.local_agent_required, before anything is created, while the workspace has Productmind cloud sessions turned off and the person has no Productmind agent online. A create that starts nothing (no originChatId, no firstMessage) is always allowed. Leave out branchName and each repository's workingBranch unless a person chose them: the working branch is derived. Refused with 409 before anything is created: a working branch that is a base, development or production branch of the workspace or of one of its applications, or that equals its repository's base branch (session_working_branch_protected_name); and, with a session's credential, any branchName or workingBranch at all (session_working_branch_renamed_by_a_person) or a repository baseBranch that is a production branch (session_working_branch_protected_name). Pass readOnlyApplicationIds, or readOnly: true on an entry of repositories, for repositories the session should only read for context: they are attached read-only, so nothing is ever committed, pushed or opened as a pull request on them. A repository whose application is read-only is read-only in every session.
path Parameters
workspaceIdWorkspace UUID
Create a session › Request Body
namecategoryscanObjectivedescriptionThe session's description, in markdown: the plan document a person opening the session reads, and the brief a coding agent drafts its plan from. Nothing fills it in for you: it is not copied from the conversation or derived from the tasks, so a session created without it has an empty description. When a plan or approach was agreed, pass it here in full (goal, approach, decisions, constraints, how to tell it is done), opening with a one-line summary. With originChatId this is the only way to hand it over, because the plan is drafted during this call.
assigneeIdAssign ONE user by UUID (the legacy single-assignee field; defaults to the creator). Use assignees to assign several people or a team.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
branchNametagNameplannedDaterelatedSessionIdreleaseIdrepositoryUrloriginChatId^([0-9a-fA-F]{8}-[0-…The assistant conversation this session is being created FROM (the Conversation id in your context). Links the session to that conversation: its transcript becomes the coding agent's context, the conversation becomes team-visible and is latched to the session, and the session starts at once - a plan session drafts its plan, a live one starts its preview and sends firstMessage when it is up. Only the conversation's owner may pass it. Because the session starts at once, the create is refused (409, coding.local_agent_required) before anything is written when cloud sessions are turned off for the workspace and the person has no Productmind agent online: check-session-scope reports that first as the no_local_agent blocker.
Explicit repos to attach at create (from the quick-create repo picker). When provided (even empty) it is honored exactly and overrides the sandbox-derived repos; omit to derive repos from the sandbox.
applicationIdsApplications whose repositories this session should work in, added on top of the ones the sandbox already reaches. Pass the ids the user pinned in the conversation when check-session-scope said the session would otherwise reach no repository. An application with no connected repository contributes nothing. Each one named here also runs in the session's sandbox, even when another sandbox lists it.
readOnlyApplicationIdsApplications whose repositories this session should READ for context only: each is attached like applicationIds, but read-only in this session, so the coding agent reads its code and nothing is ever committed, pushed or opened as a pull request on it. A repository an application already makes read-only (its Read-only setting) stays read-only in every session, whether or not it is named here. An application in both lists is read-only.
featureIdsFeatures this session builds directly, when no task or bug report scopes it: the feature the user is viewing, or one they named. Links the session to each: it appears on the feature's Sessions tab and in its lineage, and the coding agent is given the feature's specification. Each must be a feature in this workspace. Omit it for a session scoped by tasks or bug reports; it reaches their features through them.
firstMessageCategory live only. The first instruction for the coding agent: what to build or change first, in the user's terms. The session's preview starts at once, and this message is sent to the agent as its first live edit the moment the preview is ready, together with this conversation as context. Required for a Live handoff; refused on any other category. Like originChatId, it starts work in this request, so the create is refused (409, coding.local_agent_required) when cloud sessions are turned off for the workspace and the person has no Productmind agent online.
startPreviewApp only, omit. Category live only. Starts the session's preview in this request with no firstMessage; held to the same checks as firstMessage.
firstMessageAttachmentIdsApp only - omit. Images for firstMessage, uploaded by the composer against its draft conversation (draftChatId) and moved onto the session.
draftChatId^([0-9a-fA-F]{8}-[0-…App only - omit. The composer's draft conversation the firstMessageAttachmentIds were uploaded against. They are moved onto the session when it holds no message, and copied otherwise.
App only - omit. Where a Live session's preview runs, as the composer resolved it. Omitted, the server picks: an online local agent, else the cloud. cloud is refused (409) while cloud sessions are turned off for the workspace.
clientSessionId^([0-9a-fA-F]{8}-[0-…App only - omit. An id the app minted for the new session: the session is stored under an id derived from it, and a repeat with the same value answers the session already made.
clientMessageId^([0-9a-fA-F]{8}-[0-…App only - omit. Category live with firstMessage only. An id the app minted for the first message: it is delivered under an id derived from it.
deferPreviewStartApp only - omit. Category live only. Hold the first message but leave the preview to a preview/start call the app makes next.
Create a session › Responses
The session already created under this clientSessionId, answered again: nothing is created, held or started
Delete multiple sessions in one request
Deletes every session in ids. Deduped and tolerant of ids that are already gone (e.g. removed by a concurrent operation on another tab); other errors still abort so genuine failures are not silently absorbed.
path Parameters
workspaceIdWorkspace UUID
Delete multiple sessions in one request › Request Body
idsDelete multiple sessions in one request › Responses
Sessions deleted
Lookup a session by branch, tag, or display id
Find a session within the workspace matching the provided identifier. Use displayId (the integer behind a SSID-N handle — e.g. displayId=12 for SSID-12) for an exact unique lookup, or branch / tag to match a git ref. Branch/tag matches prioritize active (non-completed) sessions. Returns 404 if no match is found.
path Parameters
workspaceIdWorkspace UUID
query Parameters
branchGit branch name to match
tagGit tag name to match
displayIdSession display id (integer behind SSID-N — e.g. 12 for SSID-12)
Lookup a session by branch, tag, or display id › Responses
Matching session
Get a session by ID
Retrieve a session with full details including linked features and tasks with their names and statuses resolved.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Get a session by ID › Responses
Session details
Update a session
Modify session name, description, git fields, dates, or notes.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Update a session › Request Body
namecategorySet the single USER assignee (legacy field): replaces the session's user assignees with this one, null unassigns every user. Team assignees are left untouched — use assignees to change them.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
Rename the session's working branch. Every attached repository's working branch moves with it, so the next turn pushes the new name (use it when the git host's branch rules refused the old one). Refused (409) once a repository has a pull request or a pushed branch, while a run is in flight, and when clearing it while repositories are attached.
pullRequestUrlsUpdate a session › Responses
Updated session
Add features/tasks to a session
Attach tasks (itemType: task, the default) or bug reports (itemType: bug_report) to a session, in any state except a completed or rolled-back session and a scan, which are refused with 409 session_scope_closed. A task works in one session at a time: a task that another session still at work holds is refused with 409 task_in_active_session, and errors.holderSessionId names that session. Ask the person before retrying with exclusive: true, which moves the task here and takes it out of the other session, whose agent is told it left. A bug report already attached to another unfinished session is refused with 409 unless exclusive is true. Once the session's agent has started, each added task moves forward to the status the session's stage implies (In planning while it plans, else In progress), a bug report added to a bug-fix session moves to In progress, and the agent is told of each item a person adds. The answer's suggestedRepositories lists the applications of the added tasks whose repository the session does not have yet. They are not attached: a person adds a repository from the session page.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Add features/tasks to a session › Request Body
exclusiveWhen true, each item is first detached from every other session it belongs to (same item type) before being attached here - i.e. 'move' instead of 'add'. Without it, a task another started session holds is refused with 409 task_in_active_session (a task works in one session at a time): pass true to move it here, after asking the person.
Add features/tasks to a session › Responses
Items added, with the repositories the added tasks reach that the session does not have yet
List compact task summaries attached to a session
Returns the live set of tasks attached to the session via SessionItem rows. Each entry carries id, displayId (e.g. TASK-12), title, description, and status — just enough scope context for an autonomous coding agent to fold into its planning prompt without round-tripping through get-session-context. Tasks that have been deleted but still have an orphan SessionItem are silently skipped.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List compact task summaries attached to a session › Responses
Attached task summaries
List deduped summaries of the features a session works on
Returns one row per feature the session works on DIRECTLY - deduped, so the same feature isn't repeated when N items share it. Resolved through the one grounding definition the session's .codeflow/knowledge/ files are built from, so this list and those files can never disagree: the features the session was started from (a session that builds a feature directly, with no task or bug report to scope it), the child_of parent feature of every attached task, plus the features the session's LIVE bug reports are related_to or were converted_to. A soft-deleted bug report keeps its edges and is filtered out; an edge pointing at a deleted feature is dropped; an item with no linked feature is silently skipped. Each entry carries id, displayId (FEAT-5, COMP-5, DOM-5), title and description. Features AROUND these - parents, the other components of the same feature, and one uses hop - are deliberately absent here; their specifications are written to disk for a coding session instead of into every prompt. Paired with list-session-tasks / list-session-bug-reports to give an autonomous coding agent the parent-feature background (the 'why') alongside the item-specific scope (the 'what').
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List deduped summaries of the features a session works on › Responses
Feature background for the session's work
List compact bug-report summaries attached to a session
Returns the live set of bug reports attached to the session via SessionItem rows (itemType: bug_report) — the bug-fix counterpart of list-session-tasks. Each entry carries id, displayId (e.g. BUG-7), title, description, severity, status, priority, the reporters who wrote repro details (reporters[].details), and the entities the bug is linked to (relatedEntities — features, applications, tasks). Enough scope for an autonomous coding agent to fold into its planning prompt; use get-bug-report / list-comments for anything deeper. Bug reports that have been deleted but still have an orphan SessionItem are silently skipped.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List compact bug-report summaries attached to a session › Responses
Attached bug-report summaries
List the releases a session's work shipped in
Returns the releases the session's work shipped in, newest first: each release whose preparation matched the session to the release's commits (by the merge commit of the session's pull request, or by a commit that cites the session's ID), and each release that lists the session itself among the work it contains. The release someone set on the session by hand is not included; it is the session's releaseId. A release works this out each time it is prepared or its work items are re-checked. Nothing is changed by reading it.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List the releases a session's work shipped in › Responses
The releases the session's work shipped in
Remove a feature/task from a session
Unlink a task or bug report from a session, in any state except a completed or rolled-back session and a scan, which are refused with 409 session_scope_closed. itemId is the session item's id (the session's items[].id), not the task's. Once the session's agent has started, the item's status goes back to the one it had before this session first moved it, unless it has moved on since (done, closed, or changed by hand) or another unfinished session holds it. A log entry on the task or bug report records the removal either way, and the agent is told. Work already on the branch for it stays as it is.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
itemIdSession item UUID
Remove a feature/task from a session › Responses
Item removed
Build a session's approved plan
Dispatches the build phase to the Productmind agent for a session whose plan a person approved: the session is plan_approved and the approval is recorded (planApprovedAt, planApprovedById). Any other session is refused (400): draft a plan and approve it first. Also refused when the description changed since the plan was approved (re-draft and approve it again), and when no repository is attached. Supports re-runs: per-repo pullRequestUrl + modified are reset before dispatch.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Build a session's approved plan › Responses
Session dispatched
Cancel an autonomous session
Marks the session cancelled (phase cancelling) and closes any orphaned plan-approval or clarifying-question gate, independently of whether a Productmind agent is still alive. Also the Cancel plan action at the plan-approval gate: a cancelled session is not frozen - repositories, bug reports/tasks and the description become editable again, and Draft a new plan starts a fresh agent conversation. Pass discardPlan: true to snapshot the drafted plan into Document history and clear the description; omitted or false leaves the plan in place.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Cancel an autonomous session › Request Body
discardPlanSnapshot the drafted plan into Document history, then clear the session description
Cancel an autonomous session › Responses
Session cancelled
Mark a coding session as completed
Marks the session Completed, exactly as it completes when every one of its pull requests is merged: its tasks move to Done and, in a bug fix session, its bug reports are closed. No pull request is merged or closed. Use it for a session whose work is finished but that no merge will complete, for example one whose pull request was merged before Productmind could record it, or whose work was finished outside the session. Any session can be marked completed except one that is Completed already or was Rolled Back, and only while no agent run is active on it. A run is active while the session is queued, drafting a plan, building, in the middle of a turn, waiting for an answer to a question, or paused. A plan or CI workflow changes waiting for approval are closed. A session that is already Completed is returned unchanged. Answers 409 with the reason when the session was rolled back or an agent run is active. Takes no body.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Mark a coding session as completed › Responses
The completed session
Kick off the plan phase for an autonomous session
Dispatches the plan phase to the Productmind agent. The agent reads the session description, asks clarifying questions via the request-user-decision MCP tool, writes the drafted plan into the description via update-session-description, and finally calls request-plan-approval. No git operations occur during the plan phase. Stamps mode = cloud on the session - refuses (409) when a local coding agent has already claimed the session.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Kick off the plan phase for an autonomous session › Request Body
modeBuild mode to lock in before dispatch (cloud | codeflow_local)
codeflowInstanceIdTarget local Productmind agent instance id (required when mode = codeflow_local)
Kick off the plan phase for an autonomous session › Responses
Plan phase dispatched
Turn a code chat into a plan session
For the coding agent answering a code chat. Turns the chat into a plan session whose plan is drafted from this conversation: the session becomes a plan session, visible to the workspace, and the coding agent drafts the plan, asks what only the person can decide, and requests the plan's approval. Call it once, and only when the person has said yes to a plan or asked for one; then tell them in a sentence that the plan will be drafted, and end your turn. Called during your own turn, it answers scheduled: the plan is drafted as soon as your reply ends, not in it, so do not write the plan yourself. A resting chat (the person's own Draft the plan) answers promoted. Refused with a 400 naming what is missing (no repository, no sandbox, no Productmind agent online while cloud sessions are off, an agent too old, the billing limits), and the chat stays a chat: tell the person what it said. Only the chat's owner, or its own agent, may call it; any other session answers 404.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Turn a code chat into a plan session › Responses
The chat became a plan session (promoted), or will when the turn in flight ends (scheduled)
Re-attempt the run that failed
Re-dispatches a failed session as the same kind of run it was, read from autonomousMetadata.dispatchRunKind (stamped at dispatch): plan, or an absent stamp on an older row, re-drafts the plan; build builds the plan as it reads now, without comparing its text with the plan that was approved (its repository guards still apply), and continues from the work the failed run saved; scan re-runs the readiness scan. A build that failed while publishing its changes (its push was refused, or its pull request could not open) is the exception: it continues the build's own conversation as a publish_retry run, which is told why the push was refused and pushes the changes it kept, under the same guards; a failed publish_retry is retried the same way. A failed fix on an open pull request (for requested changes, or for failing checks) is retried as a revision: the review comments still open are sent again, and with none left the session goes back to In Review. A live_edit turn, a message sent in the session's conversation, is not retryable: the message is not stored in a form that can be run again, so it is sent again in the conversation, which takes the next message after such a turn failed. A retried build or fix continues the failed run's conversation where it stopped; a retried plan or scan runs again from the start. Any other status is refused (400): a cancelled session is resumed instead (POST /sessions/{id}/resume), or its plan drafted again.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Re-attempt the run that failed › Request Body
modeBuild mode to lock in before dispatch (cloud | codeflow_local)
codeflowInstanceIdTarget local Productmind agent instance id (required when mode = codeflow_local)
Re-attempt the run that failed › Responses
Run re-dispatched
Restart a run that stopped responding
Restarts the run in progress when its coding agent has stopped reporting: no report and no output for five minutes, or, before its first report, past the time a run has to start. The run is stopped and the same run starts again from its saved state: its conversation, the session's working branch and the session's notes. A run in the Productmind cloud continues on a new runner; changes it had not pushed are lost, and a live preview on that runner stops. A run on your own Productmind agent starts again there while the agent is connected, keeping its checkout, and otherwise on another of your agents or in the cloud, where it is checked like any new run. Refused (409) when no run is in progress, the run is still reporting, a stop is already on its way, its runner is still starting, or the session is a code chat or a scan; the message says which. GET /sessions/{id}/agent-status answers whether a restart is available and what it would do.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Restart a run that stopped responding › Responses
The run was restarted
Resume a cancelled session
Resumes a cancelled session where there is something to go back to. When at least one of its pull requests is still open (a pull request whose state cannot be read counts as open), the session goes back to In Review with its pull requests; nothing is run, and the job that was cancelled is not started again. When none of its repositories has a pull request yet, the plan's approval is recorded, the plan's wording is unchanged since that approval, and the cancelled run was the build of that plan, the build continues where it stopped, in the same conversation; it is checked like any new run first, and a refusal leaves the session cancelled. Refused (409, code session_not_resumable) otherwise, with a message saying why: the session is not cancelled, every pull request was closed or merged (reopen one to put the session back In Review), the plan changed since it was approved, or the cancelled run was not an approved build (draft a new plan instead). The body optionally carries the build mode, used only by a session that has none yet.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Resume a cancelled session › Request Body
modeBuild mode to lock in before dispatch (cloud | codeflow_local)
codeflowInstanceIdTarget local Productmind agent instance id (required when mode = codeflow_local)
Resume a cancelled session › Responses
The session was resumed
Check whether a session's coding agent is responding
Answers what is known about the coding agent running the session's current run. runner is the machine: for a run in the Productmind cloud its runner's state (waiting for capacity, starting, running, not_responding once it has not been heard from for a minute, lost once its lease expired) and its last heartbeat (lastSeenAt); for a run on your own Productmind agent, the agent's name and whether it is connected (since since) or not_connected; previousRunStopping is true while a restarted run waits on the same agent for the run it replaced to stop. run is the run: its kind, the step it last reported (phase), when it was dispatched, its last report, its last output, whether it is stalled and since when it has been silent. restart says whether POST /sessions/{id}/restart would restart it now, what a restart does for this session, and why it is not available when it is not. Nothing is changed.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Check whether a session's coding agent is responding › Responses
The coding agent's status
Check whether a session's next run would pass the billing checks
Answers whether the session's next run would pass the organization's billing checks right now: re-attempting a run that was refused, or the run an action would start (runKind: plan to draft the plan or answer a question, build to build an approved plan or approve one). The checks are the AI credit check for the run's kind (a scan step's own estimate for a scan), the sandbox check at the size the run would use, and the fee for a session on the customer's own machine, judged where the run would build now: on the caller's own Productmind agent when it would take the run, otherwise in the cloud. For a session with no build mode yet, mode and codeflowInstanceId name the selection the first run would start with. refusal is the check it would fail, with its message and, for a funding refusal, the amounts (requiredCents, balanceCents, suggestedTopupCents); null when ready. pushAccess says, for the same run, whether each of the session's repositories can be pushed to its working branch: the connection's rights and the branch's rules (GitHub rulesets, GitLab protected branches and push rules), with the rule or reason and the fix for each repository that can't. verdict is held when a run that pushes code would be refused, warning for a plan (nothing is held) or for rules that may refuse some changes, and unknown when a repository could not be checked, which never holds anything. It is absent for a scan and for a session with no repository, and answered from the last minute's check unless refresh=true. Nothing is dispatched or charged.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
runKindThe run the action would start: plan (drafting or re-drafting the plan, answering a question, requesting changes) or build (building an approved plan, approving a plan). Omitted, the kind of the session's last run.
modeWhere the first run of a session with no build mode yet would build: cloud, or codeflow_local (a Productmind agent on your machine, named by codeflowInstanceId). Ignored once the session has a build mode.
codeflowInstanceIdThe Productmind agent the first run would build on, with mode set to codeflow_local.
refreshtrue checks push access again instead of answering from the last minute's check (the notice's Check again).
Check whether a session's next run would pass the billing checks › Responses
Whether the session's next run would pass the billing checks now
Get what a coding session has cost
Returns what the session has cost so far, as charged to the organization: the AI credits each turn drew (a plan, build or documentation turn, a pull request review, a live edit) with what they were charged, the sandbox time that has ended with what it was charged, and the fee for a session built on your own machine. Amounts are in cents of currency, exactly as the credit balance was charged when each turn ran, so they do not change when a plan's rate does later. A preview that is still running is charged when it stops. floor is true while a turn is still running or when one ended before reporting its final usage: the totals are then a lower bound. billedByInvoice is true when some of the cost is billed on the organization's invoice instead of its credit balance; those amounts are not included. Nothing is charged by reading it.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Get what a coding session has cost › Responses
What the session has cost so far
Check whose account will open a session's pull requests
For each repository of the session, answers whose account its pull request will be opened by: the session creator's own GitHub, GitLab or Bitbucket account, when they have connected it and it can push to that repository (actor: user), or the workspace's connection (actor: workspace) with the reason: not_connected, reauth_required (reconnect the account), no_access, cannot_push, sso_required (authorize the account for the organization's single sign-on; ssoUrl is the provider's link), different_host, or one that needs no action (unverified, unavailable, platform_hosted, no_creator). accounts lists the creator's connection per provider. The account's handle and the sign-on link are only returned to the session's creator. Nothing is opened or changed.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Check whose account will open a session's pull requests › Responses
Whose account will open each repository's pull request
Claim a session for a local coding agent
MCP-callable. Marks the session as claimed by the calling local coding agent: sets mode = local and stamps claimedByAgentClientId from the calling MCP-issued token's OAuth client id. Idempotent: re-claiming as the same client is a no-op. Call it before any other write into a session you are about to work on. A session the Productmind agent planned or ran, in the cloud or on a person's Productmind agent, can be claimed while nothing of that agent's is live on it: the claim withdraws a pending plan approval, question or repository request (an approval is never approved by it), puts the session at rest (in_review when it has a pull request, otherwise in_planning) and starts nothing; the session cannot be moved back to the Productmind agent afterwards. Refuses (409), changing nothing, while a Productmind run is queued, running or paused on the session, while its cloud runner still holds it after a run, while a live preview is open, and when the session is completed, rolled back, a scan or a code chat; the message says what to do. Refuses (429) a session's first claim when the organization's plan caps the sessions a coding assistant may claim over MCP each billing period and the cap is reached (or the plan does not include them); the error message says which, and the session is left unclaimed. A claim is never charged. After claiming, the agent writes its drafted plan into the description via update-session-description.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Claim a session for a local coding agent › Responses
Session claimed
Request an upload to share your coding agent's conversation
MCP-callable. The first of two steps that add your own coding agent's conversation to the session's conversation: the person's prompts, your replies, your tool calls and their results, and the screenshots your client kept. Supported: Claude Code (CLI, VS Code and JetBrains), Codex (CLI and IDE extension), and GitHub Copilot (the Copilot CLI, and Copilot Chat agent mode in VS Code 1.137 or later). Returns an uploadId, an upload URL valid for 15 minutes and a command. Run the command with your shell tool: it finds this conversation's transcript on the machine (the one file holding uploadId) and uploads it; the person may be asked to approve it, and it needs network access. Then call import-session-transcript with the uploadId. Pass client to search only your client's transcripts, and shell: "powershell" when your shell is Windows PowerShell. Share again at each milestone: every import adds only what is new. Refuses (409) a session the Productmind agent runs, which shares its own conversation already.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Request an upload to share your coding agent's conversation › Request Body
clientThe coding agent you are running in: claude_code (Claude Code), codex (Codex CLI or IDE extension) or copilot (GitHub Copilot CLI, or Copilot Chat agent mode in VS Code). Narrows where the command looks for your transcript; omit it when unsure and every supported location is searched.
shellThe shell your command tool runs: posix (the default: macOS, Linux, WSL, and the Git Bash Claude Code uses on Windows) or powershell (Windows PowerShell or PowerShell 7).
Request an upload to share your coding agent's conversation › Responses
Upload requested
Import your coding agent's shared conversation
MCP-callable. The second step: reads the transcript the command from request-session-transcript-upload uploaded, and adds it to the session's conversation in the order it happened, among the session's own notes. What the session already has from an earlier share is skipped, so share the whole conversation again at each milestone. Screenshots in tool results and images in the person's prompts are stored with the session and appear in its conversation and snippets strip; when images is above zero, do not upload those screenshots again. When complete is false the import stopped at its time limit: call again with the same uploadId until it is true. Errors: 404 transcript_not_uploaded (run the command first), 400 unsupported_transcript_format (your client's transcript cannot be read: report progress with report-task-progress and pass your screenshots' attachment ids instead), 400 transcript_not_this_conversation (the uploaded file is another conversation's), 413 transcript_too_large, and 409 for a session the Productmind agent runs.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
uploadIdThe uploadId request-session-transcript-upload returned
Import your coding agent's shared conversation › Responses
What this call imported
Set the session description
MCP-callable. Replaces the session description (the plan document the session page shows) with the supplied markdown and rebuilds the collaborative Y.Doc CRDT so any connected Lexical editor refreshes via doc:reset. Two callers: the Productmind agent's plan phase, which publishes its drafted engineering plan before calling request-plan-approval; and an MCP client working a session itself, which publishes the plan the user approved (save-task-work-plan never writes the description: it records a plan in the session and task logs only). Once a plan has been approved, changing the description makes Build refuse until the plan is re-approved.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Set the session description › Request Body
markdownThe plan, in full and as markdown, to set as the session description. Replaces the whole description.
Set the session description › Responses
Description updated
List clarifying questions and plan-approval gates on a session
Returns every SessionInteraction raised on the session (pending and historical), ordered newest first.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
statusList clarifying questions and plan-approval gates on a session › Responses
List of interactions
Get the currently-pending interaction on a session (if any)
Returns the one in-flight SessionInteraction for a session, or null if none. Used by the React app to hydrate the question modal / plan-approval panel after a missed WebSocket frame. On a question, awaitsViewer says whether it waits on the caller: the modal opens for the people it waits on and stays closed, still answerable, for everyone else.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Get the currently-pending interaction on a session (if any) › Responses
Pending interaction, or null
Ask the user a clarifying question
MCP-callable by the Productmind agent running the session. Creates a pending SessionInteraction with kind=question carrying the agent's question and 2-8 multiple-choice options (or up to 5 such questions at once in questions), and pauses the session at awaiting_user_input until somebody answers: end your turn once the call succeeds. Every call is a round trip that waits on a person, so collect every decision you need from the user and ask them together in ONE call with questions rather than one at a time; the user sees them all, must answer each one, and submits once. A plan can always ask. A build can ask only before its pull request opens, from the build turn itself, and only for a decision that is the user's alone to make (discarding or redoing work, or a conflict between the approved plan and the code); its work so far is saved to the session's working branch while the question waits. Any other turn (one on an open pull request, a Live-session turn, the documentation step, a scan) is refused with 400: decide for yourself, state the assumption you made, and proceed. The question goes to the people the session waits on: its creator, the person whose own coding agent runs it, its assignees and every member of an assigned team (every workspace member when none of them is still in the workspace). They get the question modal on the session page and a toast and bell row elsewhere; anyone else can still answer it from the session. When the user responds, the agent is dispatched again ONCE with every answer, each keyed to its question, and continues the same conversation: a plan keeps drafting, and a build carries on to its pull request. The dialog ALWAYS appends its own free-text "Other" choice to every question, so do not author one yourself - list only real alternatives, your recommendation first. An answer may therefore come back as the user's own words rather than one of your options; treat that free text as authoritative when it does. Set recommended: true on the option you recommend (put it first). The app labels it Recommended and picks it in advance, so the user can accept it with one click. Omit it when you have no recommendation; on a single-choice question flag at most one (more is refused with 400). Only a coding agent asks: a person's own sign-in is refused (403), and a session's own token reaches its own session only.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Ask the user a clarifying question › Request Body
phaseThe phase asking: 'plan' while drafting the plan, 'build' while building. The session's run in progress decides it; this value counts only when the session records none (defaults to 'plan')
questionA single clarifying question (use questions instead to ask several). Lead with the ask itself in plain words a non-technical reader can answer: its first sentence is what they answer, and its first 240 characters are the text of the "Agent needs your input" notification and email. Put any detail after it, never ahead of it. Pass either question + options or questions, never both.
With question: the 2-8 multiple-choice options the user picks from, your recommendation first. Set recommended: true on the option you recommend: the app labels it Recommended and picks it in advance. Omit it when you have no recommendation; on a single-choice question flag at most one. Option values must be unique.
multiSelectWith question: whether the user can pick more than one option
Up to 5 questions asked together, in the order the user should read them, most important first. The user answers every one in a single submission, and you resume once with all the answers, keyed to each question by position (q1, q2, ...). Pass either this or question + options, never both.
claudeSessionIdClaude Code session id to resume - captured by the Productmind agent from the first stream-json system/init frame
Ask the user a clarifying question › Responses
Pending interaction created
Gate the session on user approval of the drafted plan
MCP-callable from the Productmind agent's plan phase. Creates a pending SessionInteraction with kind=plan_approval, transitioning the session to awaiting_plan_approval. The React app renders an inline approval panel beside the description; the user either clicks Approve (which flips the session to plan_approved and unlocks the Build button) or Request changes (which gathers their unresolved inline comments and resumes the agent via --resume). Only a coding agent asks: a person's own sign-in is refused (403), and a session's own token reaches its own session only.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Gate the session on user approval of the drafted plan › Request Body
summaryOne sentence under 200 characters for a non-technical reader: what will change for them once the plan is built, with no file names, code or jargon. It is the text of the "Plan ready for review" notification and email.
claudeSessionIdClaude Code session id to resume on request_changes
Gate the session on user approval of the drafted plan › Responses
Pending plan-approval interaction created
Ask the user to add a repository to the session
MCP-callable by the Productmind agent running the session. Asks a person to add a repository the work truly needs and the session does not have, the way request-user-decision asks a question and under the same rules on when you may ask: a plan can always ask; a build only before its pull request opens, from the build turn itself; any other turn is refused with 400 (decide for yourself, state the assumption you made, and carry on without the repository). Only a repository a workspace application is on can be asked for: name it by its full name (owner/name) or by the id of an application on it, as get-session-context and list-application-features show them. One repository per call. The call creates a pending SessionInteraction with kind=repository_request and pauses the session at awaiting_user_input: end your turn once it succeeds. The people a question goes to see the repository, its applications and your reason, and choose Add, Add read-only or Decline, with an optional note; pass readOnly: true when you only need to read it. An approval adds the repository as the person who approved it (their access and the workspace's branch rules apply). You are then dispatched again ONCE, in the same conversation, with the answer: on an approval where the repository is checked out, on which branch and whether you may change it; on a decline, carry on without it. A repository a person is removing from the session can be asked for too: approving keeps it. A code chat cannot pause: the call is refused (409) and you ask in your reply instead. Errors: 400 for a repository no workspace application is on (the refusal names the closest repositories; when none is the one you need, ask the person in your reply to add it from the session page) and for a turn that cannot pause; 409 for a repository the session already has, a code chat, a finished session, and agent_update_required when the Productmind agent running the session is too old to resume with the answer (name the repository in your reply instead). Only a coding agent asks: a person's own sign-in is refused (403), and a session's own token reaches its own session only.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Ask the user to add a repository to the session › Request Body
reasonWhy you need it, in one or two sentences a person can decide on: what in the task needs code or context from that repository. It follows the ask in the "The agent asks to add a repository" notification and email.
repositoryThe repository to add, by its full name as the workspace's applications record it (owner/name, matched ignoring case). Pass this or applicationId, not both.
applicationId^([0-9a-fA-F]{8}-[0-…The id of the workspace application whose repository you need (from get-session-context or list-application-features). Pass this or repository, not both.
readOnlytrue when you only need to READ the repository for context and will not change it. The person can still choose either way.
phaseThe phase asking: 'plan' while drafting the plan, 'build' while building. The session's run in progress decides it; this value counts only when the session records none (defaults to 'plan')
claudeSessionIdYour coding agent's session id, to resume once the person answers
Ask the user to add a repository to the session › Responses
Pending repository request created
User responds to a pending session interaction
User-callable. For kind=question pass answers, one entry per question keyed by the question's key ({ "q1": { "selected": ["a"] }, "q2": { "selected": ["__other__"], "customText": "..." } }): every question must be answered and no other key is accepted. A question row that asks a single question also takes selected with the picked option value(s); one that asks several refuses it (400). For kind=plan_approval pass decision: "approve" | "request_changes". For kind=repository_request pass decision: "approve" | "decline", with readOnly: true to add the repository read-only and an optional note the agent reads with the answer: an approval adds it as you, before the answer is recorded, so a refusal (a protected working branch, say) leaves the request pending to answer again, read-only or declined; either answer resumes the agent. The server marks the row answered, emits session:interaction:resolved, and routes the answer back into the codeflow pipeline (resume Claude on question / request_changes; flip the session to plan_approved on approve).
The dialog always offers a free-text "Other" choice that the agent never authored, so selected may carry the sentinel __other__ even though it is absent from the row's stored options - the endpoint accepts that one value by rule. It requires a non-blank customText alongside it (400 otherwise) and ignores customText when the sentinel is not selected; each entry of answers follows the same rule.
A kind=ci_change_approval row is not answered here (409 use_ci_change_respond): it has its own route, POST /sessions/{id}/ci-changes/{interactionId}/respond.
A person answers: the session's own token is refused (403), so a coding agent never answers its own question or approves its own plan.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
interactionIdSessionInteraction UUID
User responds to a pending session interaction › Request Body
selectedcustomTextdecisionreadOnlynoteUser responds to a pending session interaction › Responses
Interaction answered
Ask the session's agent again to answer questions on its plan
User-callable, on a plan waiting for its approval. A comment on the plan that mentions @pm is a question to the session's own coding agent, which answers it in the comment's thread without changing the plan. This sends the question threads still waiting for an answer to the agent again: those asked or replied to since the plan last asked for approval, and the ones named in commentIds whenever they were asked. One answer runs at a time: while one runs, the running one is returned. While it runs, approving the plan and requesting changes are held (409).
Refusals: 409 when the plan is not waiting for its approval or nothing is waiting for an answer, and the run's own refusals (a Productmind agent too old to answer, the session's billing limits).
A person answers: the session's own token is refused (403).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Ask the session's agent again to answer questions on its plan › Request Body
commentIdsAsk the session's agent again to answer questions on its plan › Responses
The answer that is running
Turn a question on a session's plan into a change request
User-callable, on a plan waiting for its approval. A question to the session's agent (a comment on the plan that mentions @pm) never counts as a change to the plan. This makes it an ordinary comment: it then counts toward Request changes and is sent, with its thread, into the plan's revision. Answers the updated comment. 404 when the comment is not on this session, 409 when it is not a question or the plan is not waiting for its approval. A person decides: the session's own token is refused (403).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
commentIdThe question's comment UUID
Turn a question on a session's plan into a change request › Responses
The comment, now a change request
Ask the session's agent again to answer questions on its pull request
User-callable, on a session in review. A comment on a line of the session's pull request that mentions @pm is a question to the session's own coding agent, which reads the code and answers it in the comment's thread, or, when the comment asks for a change, puts it in the review queue for Apply code revisions. This sends the question threads on the pull request still waiting for an answer to the agent again, the ones named in commentIds among them. One answer runs at a time: while one runs, the running one is returned. While it runs, Apply code revisions is held (409).
Refusals: 409 when the session is not in review, another run is in progress or nothing is waiting for an answer, and the run's own refusals (a Productmind agent too old to answer, the session's billing limits).
A person answers: the session's own token is refused (403).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Ask the session's agent again to answer questions on its pull request › Request Body
commentIdsAsk the session's agent again to answer questions on its pull request › Responses
The answer that is running on the pull request
Turn a question on a session's pull request into a review change
User-callable. A question to the session's agent on its pull request (a comment on a line of the diff that mentions @pm) is not part of the review queue. This makes it an ordinary review comment: it then counts toward Apply code revisions and is sent, with its thread, in the next revision. Answers the updated comment. 404 when the comment is not on this session, 409 when it is not a question on the pull request or the agent is answering it right now. A person decides: the session's own token is refused (403).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
commentIdThe question's comment UUID
Turn a question on a session's pull request into a review change › Responses
The comment, now in the review queue
Queue a change a reviewer asked for on the pull request
MCP-callable by the Productmind agent while it answers the @pm comments on its session's pull request. Call it for a comment that asks for a change to the code, instead of answering it and instead of changing anything now: your reply (content, plain text: what you will change) is posted in the comment's thread, and the thread joins the review queue, which the reviewers send with Apply code revisions, in order with the other review comments. Never edit, commit or push in this turn. For a question, answer with add-comment (kind agent_response, parentCommentId the comment's id) instead. Answers your reply. Refused (403) to anything but the session's own agent, during its turn on the questions, for a comment that turn was sent; 409 when the comment is not a question on the pull request.
path Parameters
workspaceIdWorkspace UUID
idSession UUID: the session whose pull request was commented on
commentIdThe id of the @pm comment that heads the thread (its commentId in your instructions)
Queue a change a reviewer asked for on the pull request › Request Body
contentYour reply in the thread, plain text (no markdown): one to three short lines saying what you will change. It is posted as your answer, and the thread joins the review queue that Apply code revisions sends.
Queue a change a reviewer asked for on the pull request › Responses
Your reply, posted in the thread
List a coding session's run errors
Returns every error the session's runs hit, newest first: what went wrong (title, message), what to do (fix), where (stage, repoName, applicationIds), in which run (runKind) and when, with severity fatal for an error that stopped its run. total and fatal count them; lastRunStopped is whether the session's last run stopped on one. details (the deciding line and a preview of the output) and body (whether the full output is stored, and its size) are returned only to a caller who may read the session's logs; anyone else gets them null, with detailsHidden true where there was something to see.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List a coding session's run errors › Responses
The session's run errors, newest first, with their counts
Get a run error's full output
Answers a URL valid for 15 minutes to download the full output of one of the session's run errors (an install's output, the coding agent's error output), as plain text, and its size in bytes. Needs permission to read the session's logs. Answers 404 with code run_error_body_missing ("The full output wasn't saved") when no full output was stored for the error, and a retryable 503 when storage could not be reached.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
errorIdRun error UUID
Get a run error's full output › Responses
The presigned download
Launch a bug fix session from a run error
Turns one of the session's run errors into a tracked fix in one call. It files a bug report from the error: its title, a description holding the error's message, its hint and, for a caller who may read the session's logs, its output in a code block, then the error's category, phase, severity, code, time, runner, repository and branch, and a link back to the error. The report has severity major, the caller as its reporter, and links to the error's applications (else the session's) and to the features the session works on. It then creates a bug-fix session holding that report, with this session's sandbox, repositories (each on its base branch, on a new working branch) and applications, left in planning for review: no plan is drafted and nothing runs. Answers 201 with the report and the new session. An error that already has both answers 200 with them and created: false, and nothing is written. Refusals: 404 (no such session or error here); 409 with code run_error_bug_fix_scope_blocked when the session would reach no repository or no sandbox, with the reasons in the message and nothing written; and, when the report was filed but its session could not be created, the session step's status with code run_error_bug_fix_session_failed and the report's id under errors.bugReportId: the report is kept, and calling again creates only the session.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
errorIdRun error UUID
Launch a bug fix session from a run error › Responses
The error already had its bug report and bug fix session: they are answered, and nothing is written
List a coding session's sub-agents
Returns every sub-agent the session's coding agent started, running ones first, then the newest: its name and agentType, the coding agent that ran it (provider), the one that started it (parentId, null for the main agent), its status (running, reported_back, failed or stopped, with endReason), when it started and ended, and its usage. running and total count them. availability says whether the session's latest run can start sub-agents (available; on_request, only when asked to in a message, the repository's AGENTS.md or a skill; unavailable, with its reason), null before a run has said.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List a coding session's sub-agents › Responses
The session's sub-agents, with their counts and availability
Get a coding session's sub-agent
Returns one sub-agent of the session with its settings, as far as its coding agent exposes them: model, effort (effortSource inherited when it runs at the main agent's effort), instructions (the full prompt it was given), tools (toolsSource defined, observed for the tools it was seen using, or inherited for the main agent's), and whether it ran in the background; its final report (summary, markdown) and, when it failed, its error.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
subagentIdSub-agent UUID
Get a coding session's sub-agent › Responses
The sub-agent and its settings
List a sub-agent's transcript
Returns a sub-agent's transcript, read-only and oldest first, in the shape of the session's own messages (kind, content, payload). Without after, page 1 holds the newest limit rows (default 200, at most 500) and page 2 the ones before them. With after, only the rows stored after that ISO 8601 instant, less a 5-second overlap: send the newest updatedAt you hold and merge the answer by id. A value of after that is not an ISO 8601 instant is refused with 400.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
subagentIdSub-agent UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
after^(?:(?:\d\d[2468][04…Only the rows stored after this ISO 8601 instant, less a 5-second overlap: send the newest updatedAt you hold and merge the answer by id. A value that is not an ISO 8601 instant is refused with 400.
List a sub-agent's transcript › Responses
The transcript rows, oldest first
Approve or decline a session's CI workflow changes
A person's own login only: a session credential, an MCP client and a service principal are refused. approve commits every open entry's stored content onto its branch in this request (fast-forward only); an entry that cannot be applied goes failed with lastApplyError and the approval returns to pending, so it can be approved again. decline leaves the pull requests without the changes. Answers the interaction DTO with each entry's status; 409 interaction_not_pending when it was already answered.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
interactionIdSessionInteraction UUID (kind ci_change_approval)
Approve or decline a session's CI workflow changes › Request Body
decisionapprove commits every open entry onto its branch; decline leaves the pull request without them
Approve or decline a session's CI workflow changes › Responses
The approval, with each repository's entry status
Attach a repository to a session
Attach a workforce-known repository to a session. The body carries the workforce identity (workforceConnectorId, externalRepoId) plus display fields (repoName, repoUrl, provider) which are snapshotted onto the session row. Used by autonomous runs when autonomous=true. workingBranch is auto-derived from the session id when omitted. A session credential is refused with 403: only a person chooses the repositories a session pushes to and their branches. A working branch, given or derived, that is a base, development or production branch of the workspace or of one of its applications, or that equals the repository's base branch, is refused with 409 session_working_branch_protected_name. Pass readOnly: true to attach it for context only: read-only in this session, never committed, pushed or opened as a pull request on, and its working branch is not checked. A repository whose application is read-only is read-only whatever this says. A repository may be attached while the coding agent works: it is copied next to the agent's work and the agent is told. Attaching a repository that is leaving the session keeps it. Refused with 409 session_scope_closed for a completed, rolled back or scan session.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Attach a repository to a session › Request Body
workforceConnectorIdexternalRepoIdrepoNamerepoUrlproviderbaseBranchworkingBranchreadOnlytrue attaches the repository for context only: read-only in this session, never committed, pushed or opened as a pull request on. Leave it out to inherit: a repository is read-only anyway when an application on it is.
Attach a repository to a session › Responses
Repository attached
Attach applications' repositories to a session
Attach the repository of each named application to a session that already exists, read from the application itself. A session takes repositories from its tasks' applications when it is created; use this when it should work in an application's repository it did not reach then, for example after its task was moved under that application. An application that is not in this workspace is refused with 404, one with no repository connected with 400, and a repository the session already has is skipped, so calling it again attaches nothing. A session credential is refused with 403: only a person chooses the repositories a session pushes to. Pass readOnly: true to attach them for context only (read-only in this session); a repository the session already has is then marked read-only too.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Attach applications' repositories to a session › Request Body
applicationIdsApplications in this workspace whose repositories the session should work in. Each must have a repository connected; a repository the session already has is skipped. Each one also runs in the session's sandbox, even when another sandbox lists it.
readOnlytrue attaches these repositories for context only: read-only in this session, never committed, pushed or opened as a pull request on. Leave it out to inherit each application's own Read-only setting.
Attach applications' repositories to a session › Responses
The repositories this call attached, empty when the session already had them all
Detach a repository from a session
Remove a repository from a session. Before the coding agent has started, it is simply detached. Once the agent has started, the repository leaves when the step in progress ends: its unsaved changes are saved to the session's working branch with no pull request, then its copy is deleted, and the agent is told. An open pull request stays open on the provider but is no longer tracked by the session. A session credential is refused with 403. Refused with 409 session_scope_closed for a completed, rolled back or scan session, with 409 agent_update_required when the person's own Productmind agent working the session is too old to save and remove it, and with 409 when one of the sandbox's own applications runs from the repository.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
repoIdSessionGitRepository UUID
Detach a repository from a session › Responses
Repository detached, or leaving when the step in progress ends
Update an attached repository's branches
Change an attached repository's base branch or working branch (a null workingBranch derives it again). A session credential is refused with 403: only a person chooses where a session pushes. A working branch that is a base, development or production branch of the workspace or of one of its applications, or that equals the repository's base branch, is refused with 409 session_working_branch_protected_name. readOnly sets the session's own read-only mark: true makes the repository read-only in this session (the coding agent reads it, and nothing is ever committed, pushed or opened as a pull request on it), false makes it writable again and checks its working branch as an attach does, and null clears the mark. A repository whose application is read-only stays read-only: false on it is refused with 409 session_repository_read_only_locked. Changing it while a run is in flight is refused with 409, except on a repository attached during the run that has not been copied yet. Refused with 409 session_scope_closed for a completed, rolled back or scan session.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
repoIdSessionGitRepository UUID
Update an attached repository's branches › Request Body
baseBranchThe session's own read-only mark: true makes the repository read-only in this session, false makes it writable again, null clears the mark. A repository an application on it makes read-only stays read-only: false is refused there.
Update an attached repository's branches › Responses
Updated attachment
Keep a repository that is leaving a session
Cancel the removal of a repository that was removed from a session after its coding agent started and has not left yet: it stays in the session as it was, with its pull request tracked again, and the agent is told it stays. Attaching the same repository again does the same. A session credential is refused with 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
departingIdThe departing repository's id, from the session's departingRepositories
Keep a repository that is leaving a session › Responses
The repository, attached again
Remove a leaving repository without saving its changes
For a repository leaving a session whose unsaved changes could not be saved to its working branch (its state is failed): delete its copy without saving them. The changes are lost. A session credential is refused with 403; any other state is refused with 409 session_departing_repository_state.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
departingIdThe departing repository's id, from the session's departingRepositories
Remove a leaving repository without saving its changes › Responses
Its copy is deleted at the next step, its changes unsaved
List enriched pull requests for a session
Resolves the session's stored pull-request URLs (both auto-detected per-repo and manually attached) into canonical PR rows with diff statistics. Calls the workforce get_pull_request action against the matching connector instance for each URL; URLs that don't map to an attached repo fall back to URL-parsed metadata with an enrichmentError string. 60s in-memory cache per (workspace, URL).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List enriched pull requests for a session › Responses
Enriched pull requests
List per-file diffs for one of a session's pull requests
Fetches the files changed in a pull request with their unified-diff patches via the workforce get_pull_request_files action. Pass the PR URL as the url query parameter. Patches are null for binary / very large files. 60s in-memory cache per (workspace, URL).
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlPull request URL
List per-file diffs for one of a session's pull requests › Responses
Per-file diffs
List CI check statuses for one of a session's pull requests
Fetches the CI check statuses attached to the pull request's head commit via the workforce get_pull_request_checks action. Pass the PR URL as the url query parameter. Returns a rollup (success | failure | pending | neutral | none) plus one row per check with status, conclusion and links. 20s in-memory cache per (workspace, URL). Pass headSha with the head commit you hold for the pull request, and a cached result that describes a different commit is read again from the provider.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlPull request URL
headShaThe pull request's head commit SHA as you last read it. A cached checks result that describes another commit is not returned; the checks are read again instead. Ignored unless it is a commit SHA of 7 to 40 hexadecimal characters.
List CI check statuses for one of a session's pull requests › Responses
PR check statuses
List the deployment jobs of one of a session's merged pull requests
The CI jobs that deployed one merged pull request of the session, as the Deployments list shows them for that merge: the jobs of the cloud deploy run at its merge commit when one exists (scope: run), else every check on the merge commit (scope: commit). The merge is the deployment the session recorded when the pull request merged into a branch an environment maps: its commit and that environment, named in environment. Read live from the provider (a cached result may be up to 20 s old) and never persisted. Answers 404 when no deployment is recorded for the URL (the pull request is not merged, or merged into a branch no environment maps). These jobs are shown, never counted in the pull request's own checks.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlThe merged pull request's URL
List the deployment jobs of one of a session's merged pull requests › Responses
The merge's deployment jobs
List why the failing CI checks of a session's pull request failed
Reads, from the pull request's Git provider, why the failing CI checks on its head commit failed. Only the first failures to finish are described, a few per pull request: on a broken base the later ones usually fail because of them. GitHub gives each failed check run's failed step, the errors it located (annotations) and the end of the job's log; GitLab each failed job of a failed pipeline, with GitLab's failure reason and the end of the job's trace; Bitbucket each failed step of a failed Pipelines run, with its log. A log is cut to its last lines (logTruncated). externalId is the check run's id on GitHub and the pipeline's on GitLab, as in the checks list, so one pipeline can carry several failures; on Bitbucket it is the Pipelines run's id, which no listed check carries. A check another CI service posted has no log the provider can serve and is left out, so an empty list is a normal answer; unavailableReason says when the provider refused a read. Pass the PR URL as url, and headSha with the head commit you hold: an answer that describes another commit is read again. Nothing is stored, and a short in-memory cache holds an answer for 20 seconds. A person's own login only: an API key or a service principal gets 401, and Productmind support access gets 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlPull request URL
headShaThe pull request's head commit SHA as you last read it. A cached answer that describes another commit is not returned; the failures are read again instead. Ignored unless it is a commit SHA of 7 to 40 hexadecimal characters.
List why the failing CI checks of a session's pull request failed › Responses
Why the pull request's failing checks failed
List the commits of one of a session's pull requests
Fetches the commits a pull request carries via the workforce list_pull_request_commits action, newest first, each with its title (the message's first line), body, author and link. Pass the PR URL as the url query parameter. One page: up to 250 commits on GitHub, 100 on GitLab and Bitbucket. Not available to a support principal.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlPull request URL
List the commits of one of a session's pull requests › Responses
The pull request's commits
Read the description of one of a session's pull requests
Reads the pull request's description (markdown) from its Git provider as it is now, never from a cache. Pass the PR URL as the url query parameter; it must be one of the session's pull requests (404 otherwise). editedAt and editedBy say when and by whom the description was last saved in Productmind: while they are set, the coding agent's later summaries no longer replace it.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
urlHTML URL of the pull request whose description to read
Read the description of one of a session's pull requests › Responses
The pull request's description
Edit the description of one of a session's pull requests
Writes the pull request's description on its Git provider through the workspace's connection, and records who saved it: from then on the coding agent's later summaries no longer replace it. baseBody is the description the edit started from. When the provider's description has changed since (line endings aside), nothing is written and the answer is a 409 with code pull_request_description_changed carrying the current description in errors.currentBody; saving again against it replaces it. A provider that refuses the edit is a 403 with code pull_request_description_edit_refused quoting the provider. A description over 65,536 characters is a 400. A person's own login only: a session credential and a support principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Edit the description of one of a session's pull requests › Request Body
urlHTML URL of the pull request whose description to write
bodyThe new description (markdown). An empty string clears it.
baseBodyThe description the edit started from, as it was read. When the pull request's description has changed since, nothing is written and the answer is a 409 carrying the current description.
Edit the description of one of a session's pull requests › Responses
The description the provider now holds
Send PR-review comments to the agent for a fix run
Collects the session's unresolved PR-diff-anchored comments and resumes the build run so the autonomous agent applies the requested fixes and pushes new commits to the existing pull request branch (no new PR is opened). Transitions the session back to building. Refused with 402 or 429 when the credit check refuses the run; the session is left as it was.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Send PR-review comments to the agent for a fix run › Responses
Revision dispatched
Approve and merge a session's pull request
Submits an approving review on the named pull request (via the matching provider's workforce connector: GitHub, GitLab, or Bitbucket), then merges it using a merge commit, then returns the canonical SessionPullRequestDTO reflecting the post-merge state. Busts the 60s enrichment cache for that URL so subsequent reads pick up the new state. Refused with 409 while the pull request's CI checks are still running or failing, which force overrides; a rollup the provider will not or cannot report does not block. When the person merging pushed the latest changes to that repository with their own git account (in a workspace that pushes as each session's creator), it merges without the approving review, so the provider's own review rules decide; a provider that wants an approval first answers 409 session_last_pusher_needs_review, and someone else must approve on the provider. A person's own login only, or a Productmind Architect on a support request that allows merging: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Approve and merge a session's pull request › Request Body
urlHTML URL of the pull request to act on
forceMerge even when the pull request's checks are not green. Skips the CI gate but NOT the provider's own branch protection — a merge the provider refuses still fails.
headSha^[0-9a-f]{7,40}$The head commit SHA of the pull request as you reviewed it. When given, the merge is refused (409) if the pull request's head has moved since, and the provider is asked to merge exactly that commit. Required for Productmind support access.
Approve and merge a session's pull request › Responses
PR merged
Close a session's pull request without merging
Closes the named pull request via the matching provider's workforce connector (on Bitbucket this is a decline). Returns the canonical SessionPullRequestDTO with state=closed. Busts the 60s enrichment cache.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Close a session's pull request without merging › Request Body
urlHTML URL of the pull request to act on
Close a session's pull request without merging › Responses
PR closed
Update a session's pull request branch from its target branch
Brings the named pull request's head branch up to date with its target branch via the matching provider's workforce connector: GitHub MERGES the target in, GitLab REBASES (rewriting the branch's published history). Bitbucket Cloud has no equivalent endpoint: its rows report syncSupported: false and the drift without an action. Refused with 409 while the session has a run in flight, because updating the branch under the agent's warm checkout makes its final non-force push fail. The update is asynchronous on both providers, so the returned SessionPullRequestDTO reports the re-measured behindBy actually observed, which may still be non-zero. A person's own login only: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Update a session's pull request branch from its target branch › Request Body
urlHTML URL of the pull request to act on
Update a session's pull request branch from its target branch › Responses
Branch update requested
Re-run one failed check of a session's pull request
Re-runs ONE failed CI check of the named pull request on its Git provider, never the whole pull request: on GitHub the Actions job behind the check run (GitHub also re-runs the jobs that depend on it), on GitLab the failed jobs of the merge request's head pipeline. externalId is the externalId of a row from the pull request's checks list; only rows reporting rerunSupported: true can be re-run, and Bitbucket checks never can (400). The provider ACCEPTS the re-run here; the checks list shows the new run on a later read. Refused with 409 when the check is not one that may be re-run now (the pull request is not open, the check is not on its head commit, did not fail, or belongs to another CI service), and when the provider refuses (a missing Actions: Read & write permission, a GitLab token without the api scope); the message says why. On a repository Productmind hosts whose environment deploys to a cloud account, a check that can deploy or destroy that environment is refused with 409 deployment_check_rerun_refused: a deploy run of the environment's branch, any destroy run, and a deploy run that names no branch. An environment's deploy is run again from its deploys, with Retry; a deploy run of any other branch re-runs as before. When Productmind cannot confirm that such a repository's check is not one of these, it answers 503: try again in a few minutes. Busts the 20s checks cache for that URL. A person's own login only: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Re-run one failed check of a session's pull request › Request Body
urlHTML URL of the pull request to act on
externalId^\d{1,20}$ · requiredThe check to re-run: the externalId of a row from the pull request's checks list (a GitHub check-run id or a GitLab pipeline id).
Re-run one failed check of a session's pull request › Responses
Re-run accepted
Merge a session pull request's target branch into it
Starts a new turn of the session that brings one of its own pull requests up to date with the branch it targets, by merging that branch into the pull request's branch and pushing a merge commit (existing commits are never rewritten). Already up to date does nothing, and a clean merge is pushed without the coding agent. When the merge conflicts, resolveConflicts: true has the coding agent resolve the conflicts in that turn; false ends the turn with nothing pushed and the conflicted files listed on the session. Only a pull request the session opened qualifies, and it must still be open on its working branch. Refused with 409 while a run is in flight, and with 400 on a failed or cancelled session. A session credential is refused with 403, and cannot start one by retrying a failed merge turn either. Returns the session, now building.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Merge a session pull request's target branch into it › Request Body
urlHTML URL of the pull request to act on
resolveConflictstrue: if merging the target branch in conflicts, the agent resolves the conflicts in a new turn and pushes a merge commit. false: a conflict ends the turn with nothing pushed and the conflicted files listed.
Merge a session pull request's target branch into it › Responses
Merge turn dispatched
Open a pull request for an autonomous session's repository
Opens a pull request on the repository's git provider (GitHub, GitLab or Bitbucket) for one repository in an autonomous session. The head branch is the session's working branch for that repository, which must already be pushed, and the base is its base branch. Pass the repository name (without owner) exactly as it appears in the session's repositories. A session's own coding agent cannot call this: the session pushes its branch when each turn ends and opens the pull request itself (a Live session's opens from Open PR), so a call with the session's credential is refused with 409 session_runner_opens_pull_requests. A repository that is read-only in the session is refused with 409 session_repository_read_only: nothing is pushed to it, so no pull request is opened on it.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Open a pull request for an autonomous session's repository › Request Body
repoNameRepository name (matches a session repo)
titlePull request title
bodyPull request body (markdown)
Open a pull request for an autonomous session's repository › Responses
Pull request opened
List KB documentation proposals bound to a session
The documentation proposals a session's build drafted before opening its PR — the PR activity rail's combined review list.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List KB documentation proposals bound to a session › Responses
Proposals
List feature description proposals bound to a session
The specification proposals a session's build drafted for the features it worked on before opening its PR — the PR activity rail's feature review list, settled history included.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List feature description proposals bound to a session › Responses
Proposals
Merge a session's Documentation pull request
Applies every APPROVED documentation proposal the session drafted - writing each document through the versioned save path, creating the ones proposed into existence, and broadcasting doc:reset. Rows still awaiting review are never applied, and a document edited since approval is vetoed and counted in skipped. Send approve to approve rows first (Approve & merge all): each is approved exactly as its own approve would, and the first refusal fails the request before anything is merged. The code pull request is not consulted and is not changed.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Merge a session's Documentation pull request › Request Body optional
Merge a session's Documentation pull request › Responses
How many proposals were approved first, how many were applied, and how many the drift veto left behind
Close a session's Documentation pull request
Dismisses every documentation proposal still awaiting review or approved-but-unmerged. Nothing is written and no scan baseline is advanced; the rows stay listed, and their diffs readable, with a dismissed status.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Close a session's Documentation pull request › Responses
How many proposals were dismissed
Merge a session's Feature specifications pull request
The specification twin of merge-session-doc-proposals: applies every APPROVED specification proposal the session drafted, behind the same drift veto, and broadcasts doc:reset for each feature document written. Send approve to approve rows first (Approve & merge all), each held to its feature's own edit access.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Merge a session's Feature specifications pull request › Request Body optional
Merge a session's Feature specifications pull request › Responses
How many proposals were approved first, how many were applied, and how many the drift veto left behind
Close a session's Feature specifications pull request
Dismisses every specification proposal still awaiting review or approved-but-unmerged. Nothing is written; the rows stay listed with a dismissed status.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Close a session's Feature specifications pull request › Responses
How many proposals were dismissed
What a session's pre-PR documentation turn evaluates against
The indented DOC-N/id/title index of the KB documentation linked to the session's grounding scope (markdown, for agent grounding — empty when none), plus the session's applications (resolved from its repositories by repo identity, each with whether it has technical documentation and its own doc-tree index), its primary features (each with whether a specification exists), and the tenant's drafting instructions. Additive over the index-only shape.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
purposedocumentation_turn when the pre-PR documentation turn asks: answered only while the run could still pay for a coding turn
What a session's pre-PR documentation turn evaluates against › Responses
Documentation context
Record a session deployment
Record a deployment for a session with deployment metadata. Creates a deployment record. Cascades: linked features are set to 'released', linked tasks are set to 'done'.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Record a session deployment › Request Body
commitShaenvironment^[a-z](?:-?[a-z0-9])…The environment's key: development, production, or one of the workspace's own environments.
deployedBybuildUrlnotesRecord a session deployment › Responses
Session deployment recorded
Read a coding session's conversation as a markdown transcript
The coding agent's conversation for a session — the user's messages, the agent's prose, its tool calls with truncated output — rendered oldest-first as markdown, so you can read what happened in a session without parsing events. Use it when a conversation you are in lists linked coding sessions and the user refers to what the session did, decided or changed. Bounded: on a very long session the tail is kept and truncated is true.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Read a coding session's conversation as a markdown transcript › Responses
The session's conversation (markdown)
List the messages on a session's conversation stream
path Parameters
workspaceIdWorkspace UUID
idSession UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
after^(?:(?:\d\d[2468][04…Only the messages stored after this ISO 8601 instant (for example 2026-10-26T09:00:00Z), less a 5-second overlap. A message's updatedAt is compared, never its createdAt, so a message stored later with an earlier time is still returned. Send the newest updatedAt among the messages you already hold, and merge the answer into them by id: the overlap returns some of them again. With it, pagination.total is the number of messages returned, not the conversation's, so an answer holding limit messages may have left older ones out: read again without after. The response names the instant it applied in filters.after. A value that is not an ISO 8601 instant is refused with 400.
List the messages on a session's conversation stream › Responses
List of messages
List deployment events for a session
Returns all deployment events for a session, ordered by most recent first.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
List deployment events for a session › Responses
List of deployments
Record a deployment event
Record a deployment event for a session. New records default to status 'unknown' unless a status is provided. Cascade to linked features/tasks only fires when status is 'deployed' on the production environment.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Record a deployment event › Request Body
environment^[a-z](?:-?[a-z0-9])… · requiredThe environment's key: development, production, or one of the workspace's own environments.
commitShatagNamedeployedBydeployedAtstatusbuildUrlpullRequestUrlnotesRecord a deployment event › Responses
Deployment recorded
Update a session deployment
Update a session deployment's status, deployedAt timestamp, buildUrl, or notes. Transitioning to 'deployed' on production cascades linked task statuses forward. Other transitions are presentation-only.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
deploymentIdDeployment UUID
Update a session deployment › Request Body
statusUpdate a session deployment › Responses
Updated deployment
Get the current live-preview status for a session
Returns the session's active live preview (long-lived sandbox), or the most recent terminal one, or null. Used by the React app to hydrate the Preview tab after a missed session:preview:updated WebSocket frame.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Get the current live-preview status for a session › Responses
Current preview, or null
Start a long-lived live preview of the session container
Brings up the session's workspace container on its working branch, runs the sandbox's dev command, and exposes the dev server at productmind.dev/{sessionId}/{port} via a reverse tunnel. Idempotent - returns the existing active preview when one is already running. Requires at least one attached repository.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Start a long-lived live preview of the session container › Request Body
sandboxIdttlSecondsidleTimeoutSecondsmodecodeflowInstanceIdStart a long-lived live preview of the session container › Responses
Preview started
Mint a cross-origin preview handshake token
Mints a short-lived (5 min) token the signed-in viewer exchanges at the preview host's handshake for a viewer pass cookie, which every request to the preview then carries. Scoped to one session and workspace with scope preview:view.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Mint a cross-origin preview handshake token › Responses
Preview handshake token
Get a session preview's public link
Whether the session's live preview is shared through a public link, and its expiry, the app it opens and whether outside viewers may comment and get AI replies. The link itself is returned only to a caller who may update the session, while it is on. available and unavailableReason say whether a link can be turned on now.
path Parameters
workspaceIdWorkspace UUID
idSession UUID
Get a session preview's public link › Responses
The preview's public link
Summarize a workspace's coding errors
Answers where the workspace's coding sessions went wrong over the last 7, 30 or 90 days (days, 30 by default): how many errors, failed runs, sessions and applications they touched (totals); every day of the period split into errors that stopped a run and the others (daily, zeros included); the most frequent errors (topCodes); where they happened (byStage, byRepository); and, for the whole workspace, each application's errors, stopped runs, most frequent error and last error (byApplication, the errors of no application last). Each error counts once for the workspace; with applicationId, only the errors of that application count, and byApplication is empty. Workspace managers only (an organization Owner or Admin, the workspace's owner or one of its admins); anyone else gets 403.
path Parameters
workspaceIdWorkspace UUID
query Parameters
daysThe period, in days: 7, 30, 90 (default 30)
applicationId^([0-9a-fA-F]{8}-[0-…Only the errors attributed to this application
Summarize a workspace's coding errors › Responses
The period's coding errors, summarized
List a workspace's coding errors
Returns one page of the errors the workspace's coding sessions hit over the last 7, 30 or 90 days (days, 30 by default), newest first, each with its session, optionally only one application's (applicationId), one error code's (code) or one stage's (stage). Send nextCursor back as cursor for the next page; it is null on the last. limit is 50 by default, at most 100. An error's details and whether its full output is stored are returned only to a caller who may read the sessions' logs. Workspace managers only (an organization Owner or Admin, the workspace's owner or one of its admins); anyone else gets 403.
path Parameters
workspaceIdWorkspace UUID
query Parameters
daysThe period, in days: 7, 30, 90 (default 30)
applicationId^([0-9a-fA-F]{8}-[0-…Only the errors attributed to this application
code^[a-z0-9_]+$Only the errors with this code
stageOnly the errors of this stage
cursor^[0-9]{1,15}\.[0-9a-…The previous page's nextCursor
limitErrors per page, at most 100 (default 50)
List a workspace's coding errors › Responses
One page of the period's coding errors, newest first