Releases
A release ships your code: for each application, Productmind compares the development branch with the production branch, lists the commits and opens a pull request. Create a release and prepare it, follow its checks, draft the release notes, curate the work it contains, then ship it to merge every pull request and tag the result. When your deployment pipeline records a production deployment, the release becomes Released and the features it shipped move to Stable. See Releases.
List releases in a workspace
Returns all releases in the workspace. Filterable by status (planned, in_progress, released: every application merged, deployed: every merged application's production deployment completed, archived). Releases group features into coherent deliverables for go-to-market tracking.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
statusFilter by release status (single value or array)
tagsComma-separated tag names to filter by
List releases in a workspace › Responses
List of releases
Create a release
Create a new release. Supply the applications to release; the release identifies itself by its generated REL-n display id and is named after it, so name is optional and normally omitted — the release-notes draft titles it from the actual commits. Passing applicationIds also starts the background prepare.
path Parameters
workspaceIdWorkspace UUID
Create a release › Request Body
nameOptional human label, e.g. "November ship" or "Checkout revamp". Normally left empty — the release names itself after its generated REL-n display id, and the release-notes draft replaces that with a title derived from the actual commits. Supply one only when you already know what this release is called.
descriptionRelease notes (markdown). Normally left empty — the prepare job drafts these from the actual commits and the user edits them afterwards.
statusapplicationIdsIDs of the Applications to release. Supplying them here links the applications AND starts the background prepare (diff production vs development, list the commits, open a pull request per application, draft the notes). Each application must have a connected git repository.
Create a release › Responses
Created release
Get where the in-progress releases stand
The workspace's In Progress releases, newest first, split in two. readyToMerge: every application still to merge has an open pull request the Release button would merge (prepared, not closed, no provider merge block, checks neither failing nor running) and its checks were read. beingPrepared: every other In Progress release, with how many of its applications are ready and why it is waiting, in the ship gate's own words. Releases in any other status are in neither list. Backs the Releases entry's sidebar counts (releasesReadyToMerge, releasesBeingPrepared in the work counts).
path Parameters
workspaceIdWorkspace UUID
Get where the in-progress releases stand › Responses
The In Progress releases, ready to merge or being prepared
Get a release by ID
Retrieve a release with full details including items (features), deployments, and computed progress (task completion percentages).
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Get a release by ID › Responses
Release details
Update a release
Update a release's name, release notes (description), or status.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Update a release › Request Body
nameRelease notes (markdown). Pushed into every pull-request body at ship time.
statusUpdate a release › Responses
Updated release
List what a release shipped
The units of work this release shipped - Tasks, Bug reports, and Sessions that carry neither - grouped by the Feature each rolls up to. Resolved from the release's actual commits at prepare time (a commit SHA matching a coding session's deployment, or a BUG-/TASK-/SSID- display ID CITED by a commit - in its subject, on a Fixes:/Refs:-style trailer line, or at the start or end of a body line. A display ID merely mentioned mid-sentence, or quoted inside a code span, is not a citation and does not attach the work), so it is evidence rather than a plan. A Bug report linked to several Features is returned under each of them. Work that belongs to no Feature is returned in a group whose feature is null. commitsTruncated is true when an application's recorded commits are only the newest of its range (preparing a very large release stops reading at a time budget), so work cited only by older commits is not listed.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
List what a release shipped › Responses
Shipped work, grouped by feature
itemCountcommitsTruncatedRe-resolve what a release shipped
Re-runs the work-item resolution over the commits ALREADY RECORDED for this release, and returns the rebuilt list in the shape GET /shipped uses. It does NOT re-diff the repositories and does NOT change the commit list — unlike prepare-release, which re-compares the live branches and would rewrite a shipped release's frozen range. Safe at any status, because it reads only persisted rows and needs no repository access. Rows a human added by hand (derived: false) are left alone; every derived row is rebuilt, which is the only way an item the matcher should never have attached comes off a release.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Re-resolve what a release shipped › Responses
The re-resolved shipped work, grouped by feature
itemCountcommitsTruncatedAdd work to a release
Put a task, bug report or session on a release by hand, for work the commit matcher did not find (a commit that named nothing, or a merge that predates the tracking). These rows carry derived: false, which is what makes them survive every re-prepare — the prepare job rebuilds only the rows it derived itself. A feature cannot be added: it appears automatically as the group header for whatever tasks and bug reports point at it. Items already on the release are silently skipped.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Add work to a release › Request Body
The work to put on this release. An item already on the release is silently skipped, so this is safe to retry.
Add work to a release › Responses
The edges created — an item already on the release yields no row
Remove hand-added work from a release
Take a hand-added item back off a release. Only works on curated rows: an item DERIVED from the release's commits is rebuilt on the next prepare, so removing it would silently undo itself, and the request is refused with a 400 instead.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
relationshipIdThe shipped-item id, as returned by curatedItems[].relationshipId on GET /shipped
Remove hand-added work from a release › Responses
Removed
Add features to a release
Add one or more features to a release. Provide an array of feature IDs. Duplicate features are silently skipped.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Add features to a release › Responses
Created items
Update a release item
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
itemIdRelease Item UUID
Update a release item › Responses
Updated item
Reorder release items
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Reorder release items › Responses
Reordered items
List deployments for a release
Returns all deployment records for a release, ordered by date (most recent first).
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
List deployments for a release › Responses
List of deployments
Record a deployment for a release
Record a deployment event for a release. A production deployment recorded as 'deployed' moves the release to 'deployed'. On a release curated by hand (no applications) it also sets the release date and cascades its features to 'stable'. On a release with applications it waits until every application has merged, which makes the release 'released' and its features 'stable'; the release becomes 'deployed' once every merged application's production deployment completed, which a deployment recorded here at an application's merge commit reports.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Record a deployment for a release › Request Body
environment^[a-z](?:-?[a-z0-9])… · requiredThe environment's key: development, production, or one of the workspace's own environments.
commitShapullRequestUrltagNamedeployedByIddeployedAtstatusbuildUrlnotesRecord a deployment for a release › Responses
Created deployment
Update a release deployment
Update a deployment's status, deployedAt timestamp, buildUrl, or notes. Transitioning to 'deployed' on production moves release.status to 'deployed': at once, with its features 'stable', for a release curated by hand; for a release with applications once every application has merged and every merged application's production deployment completed. Until then the deployment is updated and the release waits. Other transitions are presentation-only.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
deploymentIdDeployment UUID
Update a release deployment › Request Body
statusUpdate a release deployment › Responses
Updated deployment
Get the session lineage for a release
Reverse-lookup view of features that were emergently touched by sessions linked to this release. Sessions → their task items → tasks → features, grouped by feature with nested sessions and tasks. Informational only — it is independent from the curated release items used for artifact generation. Features may overlap with the release's explicit items.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Get the session lineage for a release › Responses
Session lineage grouped by feature
Link sessions to a release
Assign one or more sessions to a release by setting each session's releaseId. Sessions already linked to this release are silently skipped; sessions linked to a different release will be re-assigned.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Link sessions to a release › Responses
Updated sessions now linked to the release
Unlink a session from a release
Clear the session's releaseId so it is no longer linked to this release. The session itself is not deleted.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
sessionIdSession UUID
Unlink a session from a release › Responses
Unlinked
List artifacts for a release
Returns all generated artifacts for a release, such as changelogs, release notes, marketing announcements, etc.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
List artifacts for a release › Responses
List of artifacts
Generate an artifact for a release
Generate an AI-powered artifact (e.g., changelog, release notes, marketing announcement) for a release. Uses the release's lineage data (features, tasks, customer feedback) as context. If an artifact of the specified type already exists, it will be overwritten.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Generate an artifact for a release › Request Body
typeGenerate an artifact for a release › Responses
Generated artifact
Get a release artifact by ID
Retrieve a single release artifact with its content.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
artifactIdArtifact UUID
Get a release artifact by ID › Responses
Artifact details
Update a release artifact
Update the content or status (draft, reviewed, published) of a release artifact.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
artifactIdArtifact UUID
Update a release artifact › Responses
Updated artifact
List the applications in a release
Returns each application being released with its production-vs-development diff (commit count), its pull request, the CI check rollup, and blockReason: why it is not ready to ship, or null when it is. status is skipped for an application with no commits ahead: that is not an error, it simply has nothing to release. commitCount is the true total unless commitCountCapped is true. Then the provider counted only the commits it returned, and the count is a lower bound.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
List the applications in a release › Responses
Applications in the release
Add applications to a release
Attach applications to a release, snapshotting each one's repository and branch pair. Does NOT diff or open pull requests — call prepare-release for that. Rejects an application with no connected repository, and one already in another unshipped release.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Add applications to a release › Request Body
applicationIdsIDs of the Applications to include in this release. Each must have a connected git repository — an application with no repository is rejected.
Add applications to a release › Responses
Applications in the release
Remove an application from a release
Detaches the application and discards its recorded commits. Any pull request already opened for it is left alone on the provider.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
Remove an application from a release › Responses
Removed
List the commits an application is releasing
The commits between the production and development branches for one application in the release, newest first, as recorded at prepare time. commitsTruncated means the list holds only the newest commits of the range: preparing a very large release stops reading at a time budget. commitCount is the true total unless commitCountCapped is true. Then the provider counted only the commits it returned, and the count is a lower bound.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
List the commits an application is releasing › Responses
The application with its commits
List the individual check runs on one application's pull request
The live per-check detail for one application in the release — check names, workflow names, status/conclusion and details URLs — proxied straight from the provider (a cached response may be up to 20 s old) and never persisted. The persisted rollup the ship gate reads is refreshed by get-release-checks instead. unavailableReason is set when the provider refused the read, which is not the same as a pull request with no checks at all.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
List the individual check runs on one application's pull request › Responses
The pull request's individual check runs
List the deployment jobs of one merged application
The CI jobs that deploy one merged application of the release to production, as the Deployments list shows them for its merge: the jobs of the cloud deploy run at the merge commit when one exists (scope: run), else every check on the merge commit (scope: commit). Read live from the provider (a cached result may be up to 20 s old) and never persisted. A GET that writes: once every merged application's production deployment completed without a failure, the release moves from released to deployed. These jobs are shown, never counted in the pull request's checks or the release gate. Answers 404 for an application that is not on the release, and 400 for one that has not merged.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
List the deployment jobs of one merged application › Responses
The merged application's deployment jobs
List the changed files of one application's pull request
The files one application's pull request changes, each with its unified diff (patch, null for a binary or very large file) and a risk rating from the application's risk rules, or the default rules when it has none. Read live from the provider (a cached response may be up to 5 s old) and never persisted. truncated is true when the provider returned only part of the list, and totalChangedFiles says how many files the pull request changes. Answers 400 for an application with no pull request.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
List the changed files of one application's pull request › Responses
The pull request's changed files
Read the description of one application's pull request
The description (markdown) of one application's release pull request, read from the Git provider as it is now, never from a cache. editedAt and editedBy say when and by whom it was last saved in Productmind: while they are set, releasing keeps this description instead of writing the release notes into it. Answers 409 for an application with no pull request yet.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
Read the description of one application's pull request › Responses
The pull request's description
Edit the description of one application's pull request
Writes the description of one application's release pull request on the Git provider through the workspace's connection, and records who saved it: releasing then retitles the pull request but keeps this description, and the release notes stay on the release. 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; an application with no pull request yet is a 409. A session credential is refused with 403.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
releaseApplicationIdRelease-application UUID — the row linking one application to this release, NOT the Application's own id
Edit the description of one application's pull request › Request Body
bodyThe new description (markdown). An empty string clears it.
baseBodyThe description the edit started from, as it was read. When the pull request's description has changed since, nothing is written and the answer is a 409 carrying the current description.
Edit the description of one application's pull request › Responses
The description the provider now holds
Diff, list commits and open the pull requests
For each application in the release: compares the production branch against the development branch, records the commits, and opens a pull request titled with the release id (REL-n — name) (adopting an existing one if the branch pair already has an open PR). A new pull request is opened as the calling person when they have connected their own GitHub, GitLab or Bitbucket account and it can push to the repository, and as the workspace's connection otherwise. Then derives which features are shipping and queues an AI draft of the release notes. Safe to re-run: this is also the refresh action, because the development branch keeps moving. An application whose own pull request was closed gets it re-opened where the provider allows it, and a new one otherwise; applications already merged are left alone. Failures are reported per application, not as a whole-request error. Refused with 409 when every pull request of the release is closed: re-opening the release is what brings them back.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Diff, list commits and open the pull requests › Responses
The prepared release
Close every open pull request of a release
Closes, without merging, the pull request of every application in the release whose pull request is open. Applications with no pull request (no changes, or not prepared yet) and merged ones are left alone. Each pull request is closed through the workspace's git connection and independently: a provider that refuses one does not stop the others, and the response names what closed and, with the provider's own message, what did not. A pull request the provider reports as already closed counts as closed. Nothing is merged or deleted, branches included, and the release keeps its status and its applications; re-open the release to bring the pull requests back. Checks already running keep running on the provider. Refused with 409 while the release is being prepared and when none of its pull requests is open. A person's own login only: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Close every open pull request of a release › Responses
What closed and what did not
Re-open a release's closed pull requests and refresh it
Brings back every closed pull request of the release, then refreshes the release as prepare-release does: compares the branches again, records the commits, derives the work that shipped and queues a new draft of the release notes. Each application's own pull request is re-opened when the provider allows it, keeping its number, its link and its history. Where it cannot be re-opened, a new pull request is opened from the same branches in its place and the response says which, and why: always on Bitbucket, which never re-opens a declined pull request, and on GitHub or GitLab when the head branch was deleted or rewritten, or another pull request is open for the same branches. Applications are handled independently and reported one by one. Refused with 409 while the release is being prepared and when none of its pull requests is closed. A person's own login only: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Re-open a release's closed pull requests and refresh it › Responses
What came back, what was replaced, and what failed
Refresh the CI check status of every pull request in the release
Re-reads each open pull request's checks and mergeability from the provider, persists the rollup on each application row, and returns the updated applications. A GET that writes: it is the only thing that refills checksState / checksUpdatedAt.
Poll it while any application's checksState is pending, and call it once when a settled rollup has gone stale — a success or failure never changes on its own, so nothing else will ever re-read it.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
query Parameters
forceDrop the 20 s cached provider response before reading. Omit it when polling — the cache exists to absorb the poll. Pass it for a human-triggered refresh or any read that gates a merge, where the caller already knows something changed and a 20 s old answer is simply wrong.
Refresh the CI check status of every pull request in the release › Responses
Applications with refreshed check rollups
Re-draft the release notes from the recorded commits
Queues an AI re-draft of the release notes built from the commits already recorded on the release, held as a reviewable proposal. On blank notes the draft auto-applies; otherwise a release:proposal:updated frame surfaces a diff to review. Never overwrites existing notes without an explicit apply.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Re-draft the release notes from the recorded commits › Responses
The queued release-notes proposal
List a release's notes proposals
Returns AI-drafted release-notes proposals for a release. Pass activeOnly=true for the single in-flight / awaiting-review proposal.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
query Parameters
activeOnlyList a release's notes proposals › Responses
Release-notes proposals
Apply a release-notes proposal
Write the reviewer-composed markdown (accepted diff blocks) to the release notes and settle the proposal.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
proposalIdRelease-notes proposal UUID
Apply a release-notes proposal › Request Body
descriptionApply a release-notes proposal › Responses
The applied proposal
Dismiss a release-notes proposal
Reject the drafted notes wholesale, leaving the current release notes unchanged.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
proposalIdRelease-notes proposal UUID
Dismiss a release-notes proposal › Responses
The dismissed proposal
Cancel an in-flight release-notes draft
Stop a queued or running draft run, releasing the one-active-proposal slot.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
proposalIdRelease-notes proposal UUID
Cancel an in-flight release-notes draft › Responses
The cancelled proposal
Release: update the pull request bodies, merge, and tag
Writes the release notes into every pull request (a pull request whose description a person edited in Productmind is only retitled: its description is kept), merges them, tags the merged commit with the release id (REL-n), and records a production deployment per application. With releaseApplicationId, only that application is released: its pull request alone is merged, tagged and recorded, so only its repository's CI/CD runs, and the other applications are left as they are; an application that is not on the release is a 404, one already released a 409, and one with no changes a 400. Each pull request is merged as the calling person when they have connected their own GitHub, GitLab or Bitbucket account and the provider lets that account merge it, and as the workspace's connection otherwise; each application records which identity merged it. Blocked unless every application released by the call is checks-green and mergeable, which force overrides. Refused with 409 while a pull request it would merge is closed, force or not: re-open the release first. Applications ship independently: a provider that refuses one merge does not stop the others, and the response reports exactly what merged, what failed and what is still to merge. The release becomes released, and its features stable, once no application is left to merge, whichever call merged the last one; it becomes deployed once every merged application's production deployment completed. A person's own login only: a session credential, an MCP client and a service principal are refused with 403.
path Parameters
workspaceIdWorkspace UUID
idRelease UUID
Release: update the pull request bodies, merge, and tag › Request Body
forceMerge every application whose pull request the provider will accept, even when checks are not green. Skips the CI gate but NOT the provider's own branch protection — a merge the provider refuses still fails and is reported per application.
releaseApplicationId^([0-9a-fA-F]{8}-[0-…Release this application only: the release-application id, as the release's applications list returns it. Only its pull request is merged and tagged, so only its repository's CI/CD runs, and the other applications are left as they are. The release stays in_progress until every application has merged. Omitted, every application not merged yet is released.
Release: update the pull request bodies, merge, and tag › Responses
What merged, what failed, and whether the release is now released