Productmind API

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

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/skill

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.

Get the session workflow skill markdown for a workspace › path Parameters

workspaceId
​string · required

Workspace UUID

Get the session workflow skill markdown for a workspace › Responses

200

Session workflow skill markdown

​SessionSkillDTO · required

Get rendered context for a session's tasks

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/context

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.

Get rendered context for a session's tasks › path Parameters

workspaceId
​string · required

Workspace UUID

Get rendered context for a session's tasks › query Parameters

taskIds
​string · required

Comma-separated list of task UUIDs in the session.

Get rendered context for a session's tasks › Responses

200

Session context (markdown)

​SessionContextDTO · required

Check whether a coding session would have anything to work in

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/scope-preflight

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.

Check whether a coding session would have anything to work in › path Parameters

workspaceId
​string · required

Workspace UUID

Check whether a coding session would have anything to work in › query Parameters

taskIds
​string

Comma-separated task uuids the session would be scoped to — their applications count toward the repositories.

bugReportIds
​string

Comma-separated bug report uuids a bug-fix session would be scoped to - their applications count toward the repositories.

applicationIds
​string

Comma-separated application uuids to include, as if they had been passed to create-session-with-tasks.

sandboxId
​string

Evaluate against this sandbox instead of the workspace default.

Check whether a coding session would have anything to work in › Responses

200

What a session created with this scope would reach

​SessionScopePreflight · required

Create a new session and atomically attach tasks

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/with-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.

Create a new session and atomically attach tasks › path Parameters

workspaceId
​string · required

Workspace UUID

Create a new session and atomically attach tasks › Request Body

taskIds
​string[] · minItems: 1 · required

Tasks 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>).

name
​string · minLength: 1 · maxLength: 200

Human-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.

description
​string

The 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
​string · uuid · pattern: ^([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.

applicationIds
​string[] · maxItems: 20

Applications 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.

readOnlyApplicationIds
​string[] · maxItems: 20

Applications 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
​string · uuid · pattern: ^([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.

​SessionTransportChoice

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

​SessionDTO · required

Launch a bug-fix session from bug reports

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/with-bugs

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.

Launch a bug-fix session from bug reports › path Parameters

workspaceId
​string · required

Workspace UUID

Launch a bug-fix session from bug reports › Request Body

bugReportIds
​string[] · minItems: 1 · required

Bug 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.

​AutonomousSessionRepoInput[]

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.

description
​string

The 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
​string · uuid · pattern: ^([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.

applicationIds
​string[] · maxItems: 20

Applications 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.

readOnlyApplicationIds
​string[] · maxItems: 20

Applications 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.

​SessionTransportChoice

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

​SessionDTO · required

Start a code chat

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/code-chats

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).

Start a code chat › path Parameters

workspaceId
​string · required

Workspace UUID

Start a code chat › Request Body

message
​string · minLength: 1 · maxLength: 20000 · required

The 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.

applicationIds
​string[] · maxItems: 20

The 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.

Default: []
sandboxId
​string · uuid · pattern: ^([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.

​SessionTransportChoice

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
​string · uuid · pattern: ^([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
​string · uuid · pattern: ^([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.

attachmentIds
​string[] · maxItems: 10

App only - omit. Images uploaded by the composer against draftChatId, moved onto the new chat.

draftChatId
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

App only - omit. The composer's draft conversation the attachmentIds were uploaded against.

clientSessionId
​string · uuid · pattern: ^([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
​string · uuid · pattern: ^([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

​CodeChatDTO · required

Launch a coding session from feature requests

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/with-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.

Launch a coding session from feature requests › path Parameters

workspaceId
​string · required

Workspace UUID

Launch a coding session from feature requests › Request Body

featureRequestIds
​string[] · minItems: 1 · required

Feature 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.

​InlineStatusDecision

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

​SessionDTO · required

List the caller's current sessions

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/my-work

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.

List the caller's current sessions › path Parameters

workspaceId
​string · required

Workspace UUID

List the caller's current sessions › Responses

200

The caller's current sessions

​SessionMenuItemDTO[] · required

List where a workspace's sessions run

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/runners

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.

List where a workspace's sessions run › path Parameters

workspaceId
​string · required

Workspace UUID

List where a workspace's sessions run › Responses

200

The runners, in grouping order

​SessionRunnerDTO[] · required

List sessions in a workspace

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions

Returns all sessions for a workspace with optional filtering by status, type, date range, or linked item (feature/task).

List sessions in a workspace › path Parameters

workspaceId
​string · required

Workspace UUID

List sessions in a workspace › query Parameters

page
​number

Page number (1-indexed, default 1)

limit
​number

Items per page (default 50)

sortBy
​string · enum

Field to sort by

Enum values:
name
category
status
plannedDate
createdAt
updatedAt
assignee
activity
sortOrder
​string · enum

Sort direction (default desc)

Enum values:
asc
desc
search
​string

Full-text search across searchable fields

status
​

Filter by session status (single value or array)

category
​

Filter by session category (single value or array)

from
​string

Filter sessions from this date (ISO 8601)

to
​string

Filter sessions to this date (ISO 8601)

taskId
​string

Filter sessions containing this task ID

featureId
​string

Filter to the sessions working on this feature or its sub-features: through their tasks, or because they were started from it

unlinked
​boolean

Only include sessions with no release linked

tags
​string

Comma-separated tag names to filter by

assigneeId
​

Filter 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.

teamId
​string

Filter 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.

runner
​

Filter 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
​string · date-time · pattern: ^(?:(?:\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

200

List of sessions

​SessionDTO[] · required
​object
​object

Create a session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions

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.

Create a session › path Parameters

workspaceId
​string · required

Workspace UUID

Create a session › Request Body

name
​string · minLength: 1 · maxLength: 200
category
​string · enum
Enum values:
plan
live
scan
bugfix
scanObjective
​string · enum
Enum values:
application_detection
application_agentic_readiness
application_technical_documentation
application_architecture
feature_discovery
feature_discovery_deterministic
feature_deep_read
component_deep_read
description
​string

The 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.

assigneeId
​string

Assign ONE user by UUID (the legacy single-assignee field; defaults to the creator). Use assignees to assign several people or a team.

​AssignmentTargetInput[] · maxItems: 20

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.

branchName
​string · maxLength: 256
tagName
​string
plannedDate
​string
relatedSessionId
​string
releaseId
​string
​
repositoryUrl
​string
originChatId
​string · uuid · pattern: ^([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.

​AutonomousSessionRepoInput[]

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.

applicationIds
​string[] · maxItems: 20

Applications 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.

readOnlyApplicationIds
​string[] · maxItems: 20

Applications 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.

featureIds
​string[] · maxItems: 20

Features 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.

firstMessage
​string · minLength: 1

Category 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.

startPreview
​boolean

App only, omit. Category live only. Starts the session's preview in this request with no firstMessage; held to the same checks as firstMessage.

firstMessageAttachmentIds
​string[] · maxItems: 10

App only - omit. Images for firstMessage, uploaded by the composer against its draft conversation (draftChatId) and moved onto the session.

draftChatId
​string · uuid · pattern: ^([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.

​object

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
​string · uuid · pattern: ^([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
​string · uuid · pattern: ^([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.

deferPreviewStart
​boolean

App 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

​SessionDTO · required

Delete multiple sessions in one request

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/sessions

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.

Delete multiple sessions in one request › path Parameters

workspaceId
​string · required

Workspace UUID

Delete multiple sessions in one request › Request Body

ids
​string[] · minItems: 1 · required

Delete multiple sessions in one request › Responses

200

Sessions deleted

​object · required

Lookup a session by branch, tag, or display id

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/lookup

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.

Lookup a session by branch, tag, or display id › path Parameters

workspaceId
​string · required

Workspace UUID

Lookup a session by branch, tag, or display id › query Parameters

branch
​string

Git branch name to match

tag
​string

Git tag name to match

displayId
​integer · max: 9007199254740991

Session display id (integer behind SSID-N — e.g. 12 for SSID-12)

Lookup a session by branch, tag, or display id › Responses

200

Matching session

​SessionDTO · required

Get a session by ID

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}

Retrieve a session with full details including linked features and tasks with their names and statuses resolved.

Get a session by ID › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Get a session by ID › Responses

200

Session details

​SessionDTO · required

Update a session

PUT
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}

Modify session name, description, git fields, dates, or notes.

Update a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Update a session › Request Body

name
​string · minLength: 1 · maxLength: 200
category
​string · enum
Enum values:
plan
live
scan
bugfix
​

Set 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.

​AssignmentTargetInput[] · maxItems: 20

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.

​
pullRequestUrls
​string[]
​
​
​
​
​

Update a session › Responses

200

Updated session

​SessionDTO · required

Delete a session

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}

Permanently delete a session in any status. Linked tasks and features are unlinked (not deleted) and receive a log entry.

Delete a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Delete a session › Responses

200

Session deleted

No data returned

Add features/tasks to a session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/items

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.

Add features/tasks to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Add features/tasks to a session › Request Body

​object[] · minItems: 1 · required
exclusive
​boolean

When 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

​AddSessionItemsResult · required

List compact task summaries attached to a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/tasks

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.

List compact task summaries attached to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List compact task summaries attached to a session › Responses

200

Attached task summaries

​SessionTaskDTO[] · required

List deduped summaries of the features a session works on

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/features

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').

List deduped summaries of the features a session works on › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List deduped summaries of the features a session works on › Responses

200

Feature background for the session's work

​SessionFeatureDTO[] · required

List compact bug-report summaries attached to a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/bug-reports

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.

List compact bug-report summaries attached to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List compact bug-report summaries attached to a session › Responses

200

Attached bug-report summaries

​SessionBugReportDTO[] · required

List the releases a session's work shipped in

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/releases

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.

List the releases a session's work shipped in › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List the releases a session's work shipped in › Responses

The releases the session's work shipped in

​ReleaseDTO[] · required

Remove a feature/task from a session

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/items/{itemId}

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.

Remove a feature/task from a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

itemId
​string · required

Session item UUID

Remove a feature/task from a session › Responses

Item removed

No data returned

Build a session's approved plan

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/run

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.

Build a session's approved plan › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Build a session's approved plan › Responses

Session dispatched

​SessionDTO · required

Cancel an autonomous session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/cancel

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.

Cancel an autonomous session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Cancel an autonomous session › Request Body

discardPlan
​boolean

Snapshot the drafted plan into Document history, then clear the session description

Cancel an autonomous session › Responses

Session cancelled

​SessionDTO · required

Mark a coding session as completed

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/complete

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.

Mark a coding session as completed › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Mark a coding session as completed › Responses

The completed session

​SessionDTO · required

Kick off the plan phase for an autonomous session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/draft-plan

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.

Kick off the plan phase for an autonomous session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Kick off the plan phase for an autonomous session › Request Body

mode
​string · enum

Build mode to lock in before dispatch (cloud | codeflow_local)

Enum values:
cloud
local
codeflow_local
codeflowInstanceId
​string

Target local Productmind agent instance id (required when mode = codeflow_local)

Kick off the plan phase for an autonomous session › Responses

Plan phase dispatched

​SessionDTO · required

Turn a code chat into a plan session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/code-chat/draft-plan

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.

Turn a code chat into a plan session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Turn a code chat into a plan session › Request Body

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)

​DraftPlanFromChatResponse · required

Re-attempt the run that failed

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/retry

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.

Re-attempt the run that failed › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Re-attempt the run that failed › Request Body

mode
​string · enum

Build mode to lock in before dispatch (cloud | codeflow_local)

Enum values:
cloud
local
codeflow_local
codeflowInstanceId
​string

Target local Productmind agent instance id (required when mode = codeflow_local)

Re-attempt the run that failed › Responses

Run re-dispatched

​SessionDTO · required

Restart a run that stopped responding

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/restart

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.

Restart a run that stopped responding › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Restart a run that stopped responding › Request Body

Restart a run that stopped responding › Responses

The run was restarted

​SessionDTO · required

Resume a cancelled session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/resume

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.

Resume a cancelled session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Resume a cancelled session › Request Body

mode
​string · enum

Build mode to lock in before dispatch (cloud | codeflow_local)

Enum values:
cloud
local
codeflow_local
codeflowInstanceId
​string

Target local Productmind agent instance id (required when mode = codeflow_local)

Resume a cancelled session › Responses

The session was resumed

​SessionDTO · required

Check whether a session's coding agent is responding

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/agent-status

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.

Check whether a session's coding agent is responding › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Check whether a session's coding agent is responding › Responses

The coding agent's status

​SessionAgentStatus · required

Check whether a session's next run would pass the billing checks

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/dispatch-readiness

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.

Check whether a session's next run would pass the billing checks › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Check whether a session's next run would pass the billing checks › query Parameters

runKind
​string · enum

The 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.

Enum values:
plan
build
mode
​string · enum

Where 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.

Enum values:
cloud
codeflow_local
codeflowInstanceId
​string

The Productmind agent the first run would build on, with mode set to codeflow_local.

refresh
​string · enum

true checks push access again instead of answering from the last minute's check (the notice's Check again).

Enum values:
true
false

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

​SessionDispatchReadiness · required

Get what a coding session has cost

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/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.

Get what a coding session has cost › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Get what a coding session has cost › Responses

What the session has cost so far

​SessionCostDTO · required

Check whose account will open a session's pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/git-identity

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.

Check whose account will open a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Check whose account will open a session's pull requests › Responses

Whose account will open each repository's pull request

​SessionGitIdentity · required

Claim a session for a local coding agent

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/claim

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.

Claim a session for a local coding agent › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Claim a session for a local coding agent › Request Body

Claim a session for a local coding agent › Responses

Session claimed

​SessionDTO · required

Request an upload to share your coding agent's conversation

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/transcript-uploads

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.

Request an upload to share your coding agent's conversation › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Request an upload to share your coding agent's conversation › Request Body

client
​string · enum

The 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.

Enum values:
claude_code
codex
copilot
shell
​string · enum

The 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).

Enum values:
posix
powershell

Request an upload to share your coding agent's conversation › Responses

Upload requested

​SessionTranscriptUploadDTO · required

Import your coding agent's shared conversation

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/transcript-uploads/{uploadId}/import

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.

Import your coding agent's shared conversation › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

uploadId
​string · required

The uploadId request-session-transcript-upload returned

Import your coding agent's shared conversation › Request Body

Import your coding agent's shared conversation › Responses

What this call imported

​SessionTranscriptImportResultDTO · required

Set the session description

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/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.

Set the session description › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Set the session description › Request Body

markdown
​string · required

The plan, in full and as markdown, to set as the session description. Replaces the whole description.

Set the session description › Responses

200

Description updated

​SessionDTO · required

List clarifying questions and plan-approval gates on a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions

Returns every SessionInteraction raised on the session (pending and historical), ordered newest first.

List clarifying questions and plan-approval gates on a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List clarifying questions and plan-approval gates on a session › query Parameters

status
​string · enum
Enum values:
pending
answered
cancelled
superseded

List clarifying questions and plan-approval gates on a session › Responses

200

List of interactions

​SessionInteractionDTO[] · required
​object
​object

Get the currently-pending interaction on a session (if any)

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions/pending

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.

Get the currently-pending interaction on a session (if any) › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Get the currently-pending interaction on a session (if any) › Responses

200

Pending interaction, or null

​required

Ask the user a clarifying question

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions/request-decision

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.

Ask the user a clarifying question › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Ask the user a clarifying question › Request Body

phase
​string · enum

The 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')

Enum values:
plan
build
Default: plan
question
​string · minLength: 1 · maxLength: 4000

A 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.

​SessionInteractionOption[] · minItems: 2 · maxItems: 8

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.

multiSelect
​boolean

With question: whether the user can pick more than one option

​object[] · minItems: 1 · maxItems: 5

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.

claudeSessionId
​string

Claude 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

​SessionInteractionDTO · required

Gate the session on user approval of the drafted plan

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions/request-plan-approval

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.

Gate the session on user approval of the drafted plan › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Gate the session on user approval of the drafted plan › Request Body

summary
​string · maxLength: 2000

One 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.

claudeSessionId
​string

Claude Code session id to resume on request_changes

Gate the session on user approval of the drafted plan › Responses

Pending plan-approval interaction created

​SessionInteractionDTO · required

Ask the user to add a repository to the session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions/request-repository

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.

Ask the user to add a repository to the session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Ask the user to add a repository to the session › Request Body

reason
​string · minLength: 1 · maxLength: 2000 · required

Why 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.

repository
​string · minLength: 1 · maxLength: 500

The 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
​string · uuid · pattern: ^([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.

readOnly
​boolean

true when you only need to READ the repository for context and will not change it. The person can still choose either way.

phase
​string · enum

The 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')

Enum values:
plan
build
claudeSessionId
​string

Your 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

​SessionInteractionDTO · required

User responds to a pending session interaction

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/interactions/{interactionId}/respond

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.

User responds to a pending session interaction › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

interactionId
​string · required

SessionInteraction UUID

User responds to a pending session interaction › Request Body

selected
​string[]
customText
​string · maxLength: 4000
​object
decision
​string · enum
Enum values:
approve
request_changes
decline
readOnly
​boolean
note
​string · maxLength: 2000

User responds to a pending session interaction › Responses

200

Interaction answered

​SessionInteractionDTO · required

Ask the session's agent again to answer questions on its plan

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/plan-questions/answer

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).

Ask the session's agent again to answer questions on its plan › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Ask the session's agent again to answer questions on its plan › Request Body

commentIds
​string[] · maxItems: 50

Ask the session's agent again to answer questions on its plan › Responses

200

The answer that is running

​PlanQuestionDispatchDTO · required

Turn a question on a session's plan into a change request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/plan-questions/{commentId}/promote

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).

Turn a question on a session's plan into a change request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

commentId
​string · required

The question's comment UUID

Turn a question on a session's plan into a change request › Request Body

Turn a question on a session's plan into a change request › Responses

200

The comment, now a change request

​CommentDTO · required

Ask the session's agent again to answer questions on its pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pr-questions/answer

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).

Ask the session's agent again to answer questions on its pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Ask the session's agent again to answer questions on its pull request › Request Body

commentIds
​string[] · maxItems: 50

Ask the session's agent again to answer questions on its pull request › Responses

200

The answer that is running on the pull request

​PlanQuestionDispatchDTO · required

Turn a question on a session's pull request into a review change

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pr-questions/{commentId}/promote

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).

Turn a question on a session's pull request into a review change › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

commentId
​string · required

The question's comment UUID

Turn a question on a session's pull request into a review change › Request Body

Turn a question on a session's pull request into a review change › Responses

200

The comment, now in the review queue

​CommentDTO · required

Queue a change a reviewer asked for on the pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pr-questions/{commentId}/queue

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.

Queue a change a reviewer asked for on the pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID: the session whose pull request was commented on

commentId
​string · required

The 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

content
​string · minLength: 1 · maxLength: 4000 · required

Your 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

200

Your reply, posted in the thread

​CommentDTO · required

List a coding session's run errors

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/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.

List a coding session's run errors › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List a coding session's run errors › Responses

The session's run errors, newest first, with their counts

​SessionRunErrorList · required

Get a run error's full output

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/run-errors/{errorId}/body

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.

Get a run error's full output › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

errorId
​string · required

Run error UUID

Get a run error's full output › Responses

The presigned download

​SessionRunErrorBodyAccess · required

Launch a bug fix session from a run error

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/run-errors/{errorId}/bug-fix-session

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.

Launch a bug fix session from a run error › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

errorId
​string · required

Run error UUID

Launch a bug fix session from a run error › Request Body

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

​SessionRunErrorBugFix · required

List a coding session's sub-agents

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/subagents

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.

List a coding session's sub-agents › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List a coding session's sub-agents › Responses

The session's sub-agents, with their counts and availability

​SessionSubagentList · required

Get a coding session's sub-agent

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/subagents/{subagentId}

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.

Get a coding session's sub-agent › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

subagentId
​string · required

Sub-agent UUID

Get a coding session's sub-agent › Responses

The sub-agent and its settings

​SessionSubagentDetail · required

List a sub-agent's transcript

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/subagents/{subagentId}/messages

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.

List a sub-agent's transcript › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

subagentId
​string · required

Sub-agent UUID

List a sub-agent's transcript › query Parameters

page
​number

Page number (1-indexed, default 1)

limit
​number

Items per page (default 50)

after
​string · date-time · pattern: ^(?:(?:\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

​SessionSubagentMessage[] · required

Approve or decline a session's CI workflow changes

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/ci-changes/{interactionId}/respond

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.

Approve or decline a session's CI workflow changes › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

interactionId
​string · required

SessionInteraction UUID (kind ci_change_approval)

Approve or decline a session's CI workflow changes › Request Body

decision
​string · enum · required

approve commits every open entry onto its branch; decline leaves the pull request without them

Enum values:
approve
decline

Approve or decline a session's CI workflow changes › Responses

200

The approval, with each repository's entry status

​SessionInteractionDTO · required

Attach a repository to a session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/repositories

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.

Attach a repository to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Attach a repository to a session › Request Body

workforceConnectorId
​string · minLength: 1 · required
externalRepoId
​string · minLength: 1 · required
repoName
​string · minLength: 1 · required
repoUrl
​string · minLength: 1 · required
provider
​string
baseBranch
​string · minLength: 1
workingBranch
​string · maxLength: 256
readOnly
​boolean

true 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

​SessionGitRepositoryDTO · required

Attach applications' repositories to a session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/applications

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.

Attach applications' repositories to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Attach applications' repositories to a session › Request Body

applicationIds
​string[] · minItems: 1 · maxItems: 20 · required

Applications 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.

readOnly
​boolean

true 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

​SessionGitRepositoryDTO[] · required

Detach a repository from a session

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/repositories/{repoId}

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.

Detach a repository from a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

repoId
​string · required

SessionGitRepository UUID

Detach a repository from a session › Responses

Repository detached, or leaving when the step in progress ends

No data returned

Update an attached repository's branches

PATCH
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/repositories/{repoId}

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.

Update an attached repository's branches › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

repoId
​string · required

SessionGitRepository UUID

Update an attached repository's branches › Request Body

baseBranch
​string · minLength: 1
​
​

The 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

200

Updated attachment

​SessionGitRepositoryDTO · required

Keep a repository that is leaving a session

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/departing-repositories/{departingId}/keep

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.

Keep a repository that is leaving a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

departingId
​string · required

The departing repository's id, from the session's departingRepositories

Keep a repository that is leaving a session › Request Body

Keep a repository that is leaving a session › Responses

The repository, attached again

​SessionGitRepositoryDTO · required

Remove a leaving repository without saving its changes

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/departing-repositories/{departingId}/discard

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.

Remove a leaving repository without saving its changes › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

departingId
​string · required

The departing repository's id, from the session's departingRepositories

Remove a leaving repository without saving its changes › Request Body

Remove a leaving repository without saving its changes › Responses

Its copy is deleted at the next step, its changes unsaved

No data returned

List enriched pull requests for a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests

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).

List enriched pull requests for a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List enriched pull requests for a session › Responses

200

Enriched pull requests

​SessionPullRequestDTO[] · required

List per-file diffs for one of a session's pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/files

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).

List per-file diffs for one of a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List per-file diffs for one of a session's pull requests › query Parameters

url
​string · required

Pull request URL

List per-file diffs for one of a session's pull requests › Responses

200

Per-file diffs

​PullRequestFilesResultDTO · required

List CI check statuses for one of a session's pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/checks

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.

List CI check statuses for one of a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List CI check statuses for one of a session's pull requests › query Parameters

url
​string · required

Pull request URL

headSha
​string

The 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

200

PR check statuses

​PullRequestChecksResultDTO · required

List the deployment jobs of one of a session's merged pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/deployment-checks

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.

List the deployment jobs of one of a session's merged pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List the deployment jobs of one of a session's merged pull requests › query Parameters

url
​string · required

The merged pull request's URL

List the deployment jobs of one of a session's merged pull requests › Responses

200

The merge's deployment jobs

​MergeDeploymentChecksDTO · required

List why the failing CI checks of a session's pull request failed

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/checks/failures

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.

List why the failing CI checks of a session's pull request failed › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List why the failing CI checks of a session's pull request failed › query Parameters

url
​string · required

Pull request URL

headSha
​string

The 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

200

Why the pull request's failing checks failed

​PullRequestCheckFailuresResultDTO · required

List the commits of one of a session's pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/commits

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.

List the commits of one of a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List the commits of one of a session's pull requests › query Parameters

url
​string · required

Pull request URL

List the commits of one of a session's pull requests › Responses

200

The pull request's commits

​PullRequestCommitsResultDTO · required

Read the description of one of a session's pull requests

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/description

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.

Read the description of one of a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Read the description of one of a session's pull requests › query Parameters

url
​string · uri · required

HTML URL of the pull request whose description to read

Read the description of one of a session's pull requests › Responses

200

The pull request's description

​PullRequestDescriptionDTO · required

Edit the description of one of a session's pull requests

PUT
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/description

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.

Edit the description of one of a session's pull requests › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Edit the description of one of a session's pull requests › Request Body

url
​string · uri · required

HTML URL of the pull request whose description to write

body
​string · maxLength: 65536 · required

The new description (markdown). An empty string clears it.

baseBody
​string · maxLength: 1048576 · required

The 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

200

The description the provider now holds

​PullRequestDescriptionDTO · required

Send PR-review comments to the agent for a fix run

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/request-pr-changes

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.

Send PR-review comments to the agent for a fix run › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Send PR-review comments to the agent for a fix run › Responses

200

Revision dispatched

​SessionDTO · required

Approve and merge a session's pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/approve

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.

Approve and merge a session's pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Approve and merge a session's pull request › Request Body

url
​string · uri · required

HTML URL of the pull request to act on

force
​boolean

Merge 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
​string · pattern: ^[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

200

PR merged

​SessionPullRequestDTO · required

Close a session's pull request without merging

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/close

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.

Close a session's pull request without merging › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Close a session's pull request without merging › Request Body

url
​string · uri · required

HTML URL of the pull request to act on

Close a session's pull request without merging › Responses

200

PR closed

​SessionPullRequestDTO · required

Update a session's pull request branch from its target branch

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/sync

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.

Update a session's pull request branch from its target branch › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Update a session's pull request branch from its target branch › Request Body

url
​string · uri · required

HTML URL of the pull request to act on

Update a session's pull request branch from its target branch › Responses

200

Branch update requested

​SessionPullRequestDTO · required

Re-run one failed check of a session's pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/checks/rerun

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.

Re-run one failed check of a session's pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Re-run one failed check of a session's pull request › Request Body

url
​string · uri · required

HTML URL of the pull request to act on

externalId
​string · pattern: ^\d{1,20}$ · required

The 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

​SessionPullRequestCheckRerunResultDTO · required

Merge a session pull request's target branch into it

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/pull-requests/merge-target

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.

Merge a session pull request's target branch into it › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Merge a session pull request's target branch into it › Request Body

url
​string · uri · required

HTML URL of the pull request to act on

resolveConflicts
​boolean · required

true: 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

200

Merge turn dispatched

​SessionDTO · required

Open a pull request for an autonomous session's repository

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/open-pull-request

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.

Open a pull request for an autonomous session's repository › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Open a pull request for an autonomous session's repository › Request Body

repoName
​string · minLength: 1 · required

Repository name (matches a session repo)

title
​string · minLength: 1 · required

Pull request title

body
​string

Pull request body (markdown)

Open a pull request for an autonomous session's repository › Responses

200

Pull request opened

​OpenPullRequestResponse · required

List KB documentation proposals bound to a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/doc-proposals

The documentation proposals a session's build drafted before opening its PR — the PR activity rail's combined review list.

List KB documentation proposals bound to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List KB documentation proposals bound to a session › Responses

200

Proposals

​KnowledgeBaseDocumentProposalDTO[] · required
​object
​object

List feature description proposals bound to a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/feature-proposals

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.

List feature description proposals bound to a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List feature description proposals bound to a session › Responses

200

Proposals

​FeatureDescriptionProposalDTO[] · required
​object
​object

Merge a session's Documentation pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/doc-proposals/merge

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.

Merge a session's Documentation pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Merge a session's Documentation pull request › Request Body optional

​object[] · maxItems: 100

Merge a session's Documentation pull request › Responses

200

How many proposals were approved first, how many were applied, and how many the drift veto left behind

​object · required

Close a session's Documentation pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/doc-proposals/close

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.

Close a session's Documentation pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Close a session's Documentation pull request › Responses

200

How many proposals were dismissed

​object · required

Merge a session's Feature specifications pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/feature-proposals/merge

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.

Merge a session's Feature specifications pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Merge a session's Feature specifications pull request › Request Body optional

​object[] · maxItems: 100

Merge a session's Feature specifications pull request › Responses

200

How many proposals were approved first, how many were applied, and how many the drift veto left behind

​object · required

Close a session's Feature specifications pull request

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/feature-proposals/close

Dismisses every specification proposal still awaiting review or approved-but-unmerged. Nothing is written; the rows stay listed with a dismissed status.

Close a session's Feature specifications pull request › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Close a session's Feature specifications pull request › Responses

200

How many proposals were dismissed

​object · required

What a session's pre-PR documentation turn evaluates against

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/documentation-context

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.

What a session's pre-PR documentation turn evaluates against › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

What a session's pre-PR documentation turn evaluates against › query Parameters

purpose
​string · enum

documentation_turn when the pre-PR documentation turn asks: answered only while the run could still pay for a coding turn

Enum values:
documentation_turn

What a session's pre-PR documentation turn evaluates against › Responses

Documentation context

​SessionDocumentationContextDTO · required

Record a session deployment

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/deploy

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'.

Record a session deployment › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Record a session deployment › Request Body

commitSha
​string
environment
​string · minLength: 2 · maxLength: 16 · pattern: ^[a-z](?:-?[a-z0-9])…

The environment's key: development, production, or one of the workspace's own environments.

deployedBy
​string
buildUrl
​string
notes
​string

Record a session deployment › Responses

200

Session deployment recorded

​SessionDTO · required

Read a coding session's conversation as a markdown transcript

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/conversation

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.

Read a coding session's conversation as a markdown transcript › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Read a coding session's conversation as a markdown transcript › Responses

200

The session's conversation (markdown)

​SessionConversationDTO · required

List the messages on a session's conversation stream

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/messages

List the messages on a session's conversation stream › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List the messages on a session's conversation stream › query Parameters

page
​number

Page number (1-indexed, default 1)

limit
​number

Items per page (default 50)

sortBy
​string · enum

Field to sort by

Enum values:
createdAt
updatedAt
sortOrder
​string · enum

Sort direction (default desc)

Enum values:
asc
desc
search
​string

Full-text search across searchable fields

after
​string · date-time · pattern: ^(?:(?:\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

200

List of messages

​ChatMessageDTO[] · required
​object
​object

List deployment events for a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/deployments

Returns all deployment events for a session, ordered by most recent first.

List deployment events for a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

List deployment events for a session › Responses

200

List of deployments

​SessionDeploymentDTO[] · required

Record a deployment event

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/deployments

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.

Record a deployment event › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Record a deployment event › Request Body

environment
​string · minLength: 2 · maxLength: 16 · pattern: ^[a-z](?:-?[a-z0-9])… · required

The environment's key: development, production, or one of the workspace's own environments.

commitSha
​string
tagName
​string
deployedBy
​string
deployedAt
​string
status
​string · enum
Enum values:
merged
pending
deployed
failed
skipped
rolled_back
buildUrl
​string
pullRequestUrl
​string
notes
​string

Record a deployment event › Responses

Deployment recorded

​SessionDeploymentDTO · required

Update a session deployment

PATCH
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/deployments/{deploymentId}

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.

Update a session deployment › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

deploymentId
​string · required

Deployment UUID

Update a session deployment › Request Body

status
​string · enum
Enum values:
merged
pending
deployed
failed
skipped
rolled_back
​
​
​

Update a session deployment › Responses

200

Updated deployment

​SessionDeploymentDTO · required

Get the current live-preview status for a session

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/preview

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.

Get the current live-preview status for a session › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Get the current live-preview status for a session › Responses

200

Current preview, or null

​required

Start a long-lived live preview of the session container

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/preview/start

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.

Start a long-lived live preview of the session container › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Start a long-lived live preview of the session container › Request Body

sandboxId
​string
ttlSeconds
​integer · min: 300 · max: 28800
idleTimeoutSeconds
​integer · min: 0 · max: 28800
mode
​string · enum
Enum values:
cloud
local
codeflow_local
codeflowInstanceId
​string

Start a long-lived live preview of the session container › Responses

Preview started

​SessionPreviewDTO · required

Stop the session's live preview

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/preview/stop

Tears down the session's live preview container and frees the session to start a fresh one.

Stop the session's live preview › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Stop the session's live preview › Responses

200

Preview stopped (or null when none was active)

​required

Mint a cross-origin preview handshake token

POST
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/preview-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.

Mint a cross-origin preview handshake token › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Mint a cross-origin preview handshake token › Responses

200

Preview handshake token

​SessionPreviewTokenResponse · required

GET
https://api.productmind.ai
/workspaces/{workspaceId}/sessions/{id}/preview/share

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.

Get a session preview's public link › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Session UUID

Get a session preview's public link › Responses

200

The preview's public link

​SessionPreviewShareDTO · required

Summarize a workspace's coding errors

GET
https://api.productmind.ai
/workspaces/{workspaceId}/coding-errors/summary

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.

Summarize a workspace's coding errors › path Parameters

workspaceId
​string · required

Workspace UUID

Summarize a workspace's coding errors › query Parameters

days
​number

The period, in days: 7, 30, 90 (default 30)

Default: 30
applicationId
​string · uuid · pattern: ^([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

​CodingErrorsSummary · required

List a workspace's coding errors

GET
https://api.productmind.ai
/workspaces/{workspaceId}/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.

List a workspace's coding errors › path Parameters

workspaceId
​string · required

Workspace UUID

List a workspace's coding errors › query Parameters

days
​number

The period, in days: 7, 30, 90 (default 30)

Default: 30
applicationId
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Only the errors attributed to this application

code
​string · maxLength: 64 · pattern: ^[a-z0-9_]+$

Only the errors with this code

stage
​string · enum

Only the errors of this stage

Enum values:
dispatch
runner
workspace
clone
checks
install
agent
publish
cursor
​string · pattern: ^[0-9]{1,15}\.[0-9a-…

The previous page's nextCursor

limit
​integer · min: 1 · max: 100

Errors per page, at most 100 (default 50)

Default: 50

List a workspace's coding errors › Responses

One page of the period's coding errors, newest first

​CodingErrorsList · required