Productmind API

Features are your product catalog: a tree of what your product does, where each feature has a specification. Create, update, move and search features, link them to the applications that implement them and to the features they depend on, and read their business rules and document history. Have Productmind draft a specification, refresh it from the linked code for your review or suggest tasks, and find the features that own the files a change touched. See Features.


List product features in a workspace

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

Returns the feature catalog for a workspace. Features represent product capabilities organized in a hierarchy with parent/child relationships. Returns: id, displayId, title, priority, status, parentFeatureId, parentFeature (a lean ancestry breadcrumb), subFeatureCount, sortOrder. Descriptions are NOT included — a workspace of fully-specified features runs to megabytes, which exceeds what one tool call can return; read a specific feature's markdown with get-feature, or search across them with search-features. Pass ?includeDescription=true only if you genuinely need every description at once.

List product features in a workspace › path Parameters

workspaceId
​string · required

Workspace UUID

List product features 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:
title
priority
status
createdAt
updatedAt
relevance
sortOrder
​string · enum

Sort direction (default desc)

Enum values:
asc
desc
search
​string

Full-text search across searchable fields

parentFeatureId
​string

Parent feature UUID, or 'all' for all features

kind
​

Filter by tier (single value or array). component returns only the code-owning leaves — the rows that carry business rules and that a component read scans; feature returns the business capabilities above them; domain returns only the hand-curated collections above THOSE, which own no code and are never scanned. feature does NOT include domains, so enumerating "everything above components" means passing both.

priority
​

Filter by priority (single value or array)

status
​

Filter by status (single value or array)

ownerId
​string

Filter by assignee (historically 'owner'): a user or team UUID, or a comma-separated list of them (features assigned to ANY listed user/team match). my-teams stands for every team the caller belongs to, and for-me for the features FOR the caller: assigned to them, or in the area of a team they are on (assigned to the team or anywhere under a feature that is). for-me is the sidebar's Features 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. This list returns root features unless parentFeatureId is given: pass parentFeatureId=all for the team's whole area, sub-features included. The sub-feature listing does not apply it.

externalSource
​string

Filter by externalSource marker (e.g. 'system_generated' to surface agent-suggested starter features).

tags
​string

Comma-separated tag names to filter by

application
​string

Filter by LINKED APPLICATION: a single application UUID, or a comma-separated list of them (features linked to ANY listed application match). The link is the feature's own depends_on → application edge — a parent whose CHILDREN are linked does not match. Top-level rows only; the sub-feature listing does not apply it.

codeSurface
​string · enum

Filter by whether a CODE SURFACE is recorded on the feature's application links. recorded: at least one linked application carries code paths or entry points (from a scan or added by hand). missing: no linked application carries any — which includes features with no application link at all. Top-level rows only; the sub-feature listing does not apply it.

Enum values:
recorded
missing
deepScan
​

Filter by DEEP SCAN status (single value or array; a feature matching ANY listed value is returned). scanned: a scan of the code wrote the feature's specification (a later scan that is queued, running, failed or dismissed does not change that). awaiting_review: a scan's draft is waiting for review, even when an earlier scan already wrote one. not_scanned: no scan has written one yet, which includes a first scan still queued or running, one that failed or was dismissed, and features no scan can read (domains, and features with no linked repository). A specification update proposed by a coding session is not a scan. The sub-feature listing does not apply it.

specificationProposal
​string · enum

Filter by whether a SPECIFICATION PROPOSAL is pending. pending: the feature has a drafted rewrite of its specification waiting for review, or one approved in a pull request and not yet applied, from any source (a deep dive, a refresh, a composition, discovery, a coding session, review mode or a code chat). awaiting_review: only the drafts still waiting for someone to review them, from any source; an approved one waiting for its pull request is left out. in_progress: a run still queued or running, from any source (no draft exists yet). Not counted by any of them: an applied, dismissed or failed proposal, and a structure proposal (a proposed split, not a specification). pending and awaiting_review are wider than deepScan=awaiting_review, which counts only drafts from a scan of the code. The sub-feature listing does not apply it.

Enum values:
pending
awaiting_review
in_progress
codePath
​string · maxLength: 500

Filter by a CODE PATH recorded on the feature's own application links: which features use this file or folder. A repository-relative path such as src/booking/booking.service.ts, or a folder ending in / such as src/booking/. By default the match is lenient, to find the owner of a file a scan may have recorded under a wrong or old folder: letter case is ignored, a recorded path matches when it is the same path, a folder holding it or a file inside the given folder, and, for a file, when the recorded FILE NAME contains the given file name, in any folder of any application (src/booking/booking.service.ts finds lib/legacy/booking.service.ts; booking.contr finds booking.controller.ts). A folder is never matched by name. Pass codePathExact=true to match only that exact path. Counted: the paths a scan recorded (less those a person hid), the paths added by hand, and the files entry points name. A feature matches through its own links, never a child's. Pass parentFeatureId=all to include sub-features: components are sub-features, and they carry most code paths. To map a change set (the files a diff touched) to features, use find-features-by-code-paths instead. The sub-feature listing does not apply it.

codePathExact
​string · enum

With codePath: true matches only that exact path, letter case included, with no folder containment and no file-name match. A leading ./, a trailing / and a #symbol suffix still name the same path. Defaults to false, the lenient match described on codePath. Ignored without codePath. The sub-feature listing does not apply it.

Enum values:
true
false
ids
​string

Comma-separated feature UUIDs, at most 100: return only these features. Pass parentFeatureId=all to include sub-features. An id that no longer exists, or that the caller may not see, is simply absent from the answer. The sub-feature listing does not apply it.

includeDescription
​string · enum

Opt in to receive each feature's full markdown description. Defaults to false: a catalog of fully-specified features runs to megabytes, past what a single tool call can return. Read the ones you need with get-feature instead.

Enum values:
true
false

List product features in a workspace › Responses

200

List of features

​FeatureListItemDTO[] · required
​object
​object

Create a product feature

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

Add a new feature to the product catalog. Features can be organized hierarchically using parentFeatureId. Titles at every level are short sentence-case noun phrases in the business's own vocabulary — see the title field. Status: backlog, planned, in_development, stable, deprecated.

Create a product feature › path Parameters

workspaceId
​string · required

Workspace UUID

Create a product feature › Request Body

title
​string · minLength: 1 · required

A short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.

parentFeatureId
​string
kind
​string · enum

component for a unit that owns code and therefore owns business rules — a screen, a service module, a background worker, or the shared code a domain's capabilities have in common. feature for the business capability above it, whose description is composed from its components. domain ONLY for a named collection that organises features: it is purely organisational, owns no code, composes nothing and is never scanned. A person makes one; a catalogue scan makes one only when its instructions say the workspace's catalogue shape is domains, features and capabilities. In every other case a scan must never mint one, and when cataloguing you should treat every container as a feature. A child may not be broader than its parent (nothing above a component, no domain under a feature). When in doubt, ask whether a deep read of this row alone would have specific files to open — if not, it is a feature.

Enum values:
domain
feature
component
description
​string

Markdown, at most 200,000 characters.

priority
​string · enum
Enum values:
low
high
critical
requestingAccountId
​string
requestingContactId
​string
ownerId
​string

Assign ONE user by UUID (legacy single-assignee field, historically the feature's 'owner'). 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.

estimatedEffort
​string · enum
Enum values:
__none__
xs
s
m
l
xl
targetDate
​string
sortOrder
​number
position
​string · enum

Where to place the feature among its siblings (same parent) when sortOrder is not supplied. end appends it below the last sibling, start puts it above the first. Ignored when an explicit sortOrder is given.

Enum values:
start
end
externalSource
​string
externalId
​string
externalSourceUrl
​string · uri

Create a product feature › Responses

Created feature

​FeatureDTO · required

Which features own the files a change touched

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/by-code-paths

The reverse of a feature's code surface. Pass the files you changed, per repository (git diff --name-only <base> plus untracked files, as repos[].paths; name each repository the way your environment lists it — the short name or the full owner/repo, both match). Returns the features whose RECORDED code surface covers them — the paths a scan attributed to the feature or a person added by hand — with, per feature and application, which surface entries matched, which of your files they covered, and whether the entry came from a scan (codePaths) or a person (manualCodePaths); most-covered first. unmatched lists your changed files no feature claims; unknownRepos the repositories no application here is attached to. A feature returned here is a CANDIDATE to check against your diff, not a verdict: a surface is a set of files, and a refactor inside one changes no observable behaviour. Read the candidate's specification (get-feature) and decide whether what a user can observe changed; if it did, propose the update with propose-feature-description.

Which features own the files a change touched › path Parameters

workspaceId
​string · required

Workspace UUID

Which features own the files a change touched › Request Body

​object[] · minItems: 1 · maxItems: 20 · required

One entry per repository you changed. One call covers every repository.

Which features own the files a change touched › Responses

200

Candidate features, the changed files nothing claims, and the repositories nothing is attached to

​FindFeaturesByCodePathsResult · required

Bulk create product features

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

Create multiple features at once (e.g., from Jira import). Maximum 200 features per request.

Bulk create product features › path Parameters

workspaceId
​string · required

Workspace UUID

Bulk create product features › Request Body

​CreateFeatureBody[] · minItems: 1 · maxItems: 200 · required

Bulk create product features › Responses

Created features

​FeatureDTO[] · required

List sub-features of a parent feature

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

Returns child features nested under a parent feature in the hierarchy. Excludes the heavy Lexical CRDT payload and audit fields.

List sub-features of a parent feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Parent feature UUID

List sub-features of a parent feature › 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:
title
priority
status
createdAt
updatedAt
relevance
sortOrder
​string · enum

Sort direction (default desc)

Enum values:
asc
desc
search
​string

Full-text search across searchable fields

parentFeatureId
​string

Parent feature UUID, or 'all' for all features

kind
​

Filter by tier (single value or array). component returns only the code-owning leaves — the rows that carry business rules and that a component read scans; feature returns the business capabilities above them; domain returns only the hand-curated collections above THOSE, which own no code and are never scanned. feature does NOT include domains, so enumerating "everything above components" means passing both.

priority
​

Filter by priority (single value or array)

status
​

Filter by status (single value or array)

ownerId
​string

Filter by assignee (historically 'owner'): a user or team UUID, or a comma-separated list of them (features assigned to ANY listed user/team match). my-teams stands for every team the caller belongs to, and for-me for the features FOR the caller: assigned to them, or in the area of a team they are on (assigned to the team or anywhere under a feature that is). for-me is the sidebar's Features 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. This list returns root features unless parentFeatureId is given: pass parentFeatureId=all for the team's whole area, sub-features included. The sub-feature listing does not apply it.

externalSource
​string

Filter by externalSource marker (e.g. 'system_generated' to surface agent-suggested starter features).

tags
​string

Comma-separated tag names to filter by

application
​string

Filter by LINKED APPLICATION: a single application UUID, or a comma-separated list of them (features linked to ANY listed application match). The link is the feature's own depends_on → application edge — a parent whose CHILDREN are linked does not match. Top-level rows only; the sub-feature listing does not apply it.

codeSurface
​string · enum

Filter by whether a CODE SURFACE is recorded on the feature's application links. recorded: at least one linked application carries code paths or entry points (from a scan or added by hand). missing: no linked application carries any — which includes features with no application link at all. Top-level rows only; the sub-feature listing does not apply it.

Enum values:
recorded
missing
deepScan
​

Filter by DEEP SCAN status (single value or array; a feature matching ANY listed value is returned). scanned: a scan of the code wrote the feature's specification (a later scan that is queued, running, failed or dismissed does not change that). awaiting_review: a scan's draft is waiting for review, even when an earlier scan already wrote one. not_scanned: no scan has written one yet, which includes a first scan still queued or running, one that failed or was dismissed, and features no scan can read (domains, and features with no linked repository). A specification update proposed by a coding session is not a scan. The sub-feature listing does not apply it.

specificationProposal
​string · enum

Filter by whether a SPECIFICATION PROPOSAL is pending. pending: the feature has a drafted rewrite of its specification waiting for review, or one approved in a pull request and not yet applied, from any source (a deep dive, a refresh, a composition, discovery, a coding session, review mode or a code chat). awaiting_review: only the drafts still waiting for someone to review them, from any source; an approved one waiting for its pull request is left out. in_progress: a run still queued or running, from any source (no draft exists yet). Not counted by any of them: an applied, dismissed or failed proposal, and a structure proposal (a proposed split, not a specification). pending and awaiting_review are wider than deepScan=awaiting_review, which counts only drafts from a scan of the code. The sub-feature listing does not apply it.

Enum values:
pending
awaiting_review
in_progress
codePath
​string · maxLength: 500

Filter by a CODE PATH recorded on the feature's own application links: which features use this file or folder. A repository-relative path such as src/booking/booking.service.ts, or a folder ending in / such as src/booking/. By default the match is lenient, to find the owner of a file a scan may have recorded under a wrong or old folder: letter case is ignored, a recorded path matches when it is the same path, a folder holding it or a file inside the given folder, and, for a file, when the recorded FILE NAME contains the given file name, in any folder of any application (src/booking/booking.service.ts finds lib/legacy/booking.service.ts; booking.contr finds booking.controller.ts). A folder is never matched by name. Pass codePathExact=true to match only that exact path. Counted: the paths a scan recorded (less those a person hid), the paths added by hand, and the files entry points name. A feature matches through its own links, never a child's. Pass parentFeatureId=all to include sub-features: components are sub-features, and they carry most code paths. To map a change set (the files a diff touched) to features, use find-features-by-code-paths instead. The sub-feature listing does not apply it.

codePathExact
​string · enum

With codePath: true matches only that exact path, letter case included, with no folder containment and no file-name match. A leading ./, a trailing / and a #symbol suffix still name the same path. Defaults to false, the lenient match described on codePath. Ignored without codePath. The sub-feature listing does not apply it.

Enum values:
true
false
ids
​string

Comma-separated feature UUIDs, at most 100: return only these features. Pass parentFeatureId=all to include sub-features. An id that no longer exists, or that the caller may not see, is simply absent from the answer. The sub-feature listing does not apply it.

includeDescription
​string · enum

Opt in to receive each feature's full markdown description. Defaults to false: a catalog of fully-specified features runs to megabytes, past what a single tool call can return. Read the ones you need with get-feature instead.

Enum values:
true
false

List sub-features of a parent feature › Responses

200

List of sub-features

​FeatureListItemDTO[] · required
​object
​object

Count what deleting a feature would remove

GET
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/delete-impact

Counts what DELETE /features/{id} would remove with the feature: its sub-features at any depth, and the distinct tasks (subtasks included) linked to the feature or to any of them. Computed from the same closure the delete runs, and removes nothing. Returns counts only. Requires feature:delete.

Count what deleting a feature would remove › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Count what deleting a feature would remove › Responses

200

Sub-feature and task counts for a delete of this feature

​FeatureDeleteImpactDTO · required

Get feature requests promoted to this feature

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

Returns all feature requests that have been promoted to this feature via entity relationships.

Get feature requests promoted to this feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Get feature requests promoted to this feature › Responses

200

List of promoted feature requests

​FeatureRequestDTO[] · required

Update feature status

PATCH
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/status

Transition a feature between statuses: backlog, planned, in_development, stable, deprecated.

Update feature status › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Update feature status › Request Body

status
​string · enum · required
Enum values:
backlog
planned
in_development
stable
deprecated

Update feature status › Responses

200

Feature status updated

No data returned

Move a feature under a different parent, or reorder it among its siblings

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

Re-parents a feature and positions it among its new siblings — the same operation as dragging a row in the Features tree. Pass a feature id as parentFeatureId to nest it, null to promote it to the top level, or omit the key to reorder within the current parent. The server re-indexes both the old and the new sibling lists, and rejects a move that would make a feature its own ancestor. The workspace feature map uses this to GROUP an existing flat catalogue under the domains it creates: move only features a scan created (never a row a person placed), never past the maximum hierarchy depth, and report every move in the run's movedFeatureIds. It changes placement only — never the title, description, status or links.

Move a feature under a different parent, or reorder it among its siblings › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID (the feature being moved)

Move a feature under a different parent, or reorder it among its siblings › Request Body

sortOrder
​number · required

Position among the new siblings, 0-based. The server re-indexes the rest of that sibling list around it, and re-indexes the old siblings too when the parent changes.

​

Where the feature lands: a feature id nests it under that parent, null promotes it to the top level, and omitting the key leaves the current parent alone. A move that would make a feature its own ancestor is rejected.

Move a feature under a different parent, or reorder it among its siblings › Responses

200

The moved feature

No data returned

List logs on a feature

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

Returns log entries for a feature, newest first.

List logs on a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List logs on a feature › Responses

200

List of logs

​FeatureLogDTO[] · required
​object
​object

Add a log entry to a feature

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/logs

Post a new log entry on a feature.

Add a log entry to a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Add a log entry to a feature › Request Body

content
​string · minLength: 1 · required

Add a log entry to a feature › Responses

Log added

​FeatureLogDTO · required

Delete a log entry from a feature

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/logs/{logId}

Remove a log entry from a feature.

Delete a log entry from a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

logId
​string · required

Log UUID

Delete a log entry from a feature › Responses

200

Log deleted

No data returned

Update a log entry on a feature

PATCH
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/logs/{logId}

Edit your own log entry on a feature.

Update a log entry on a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

logId
​string · required

Log UUID

Update a log entry on a feature › Request Body

content
​string · minLength: 1 · required

Update a log entry on a feature › Responses

200

Log updated

No data returned

Get who can see and edit a feature

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

Returns the feature's access list: the teams that may see it and whether each may view or edit it, or, when the feature has no list of its own, the list it inherits from a private feature above it. A feature with no list anywhere above it is open to everyone in the workspace. Also returns what the caller may do with the feature.

Get who can see and edit a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Get who can see and edit a feature › Responses

200

The feature's access list

​FeatureAccessDTO · required

Get a feature by ID

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

Retrieve a single product feature with full details including hierarchy info, status, and linked feature requests. Pass ?includeLexical=true to also receive the Lexical CRDT payload (only the collaborative editor needs it).

Get a feature by ID › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Get a feature by ID › query Parameters

includeLexical
​string · enum

Opt in to receive the Lexical CRDT payload alongside markdown. Defaults to false — only the collaborative editor needs it.

Enum values:
true
false

Get a feature by ID › Responses

200

Feature details

​FeatureDTO · required

Update a product feature

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

Modify feature title, description, type, or priority.

Update a product feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Update a product feature › Request Body

kind
​string · enum

component for a unit that owns code and therefore owns business rules — a screen, a service module, a background worker, or the shared code a domain's capabilities have in common. feature for the business capability above it, whose description is composed from its components. domain ONLY for a named collection that organises features: it is purely organisational, owns no code, composes nothing and is never scanned. A person makes one; a catalogue scan makes one only when its instructions say the workspace's catalogue shape is domains, features and capabilities. In every other case a scan must never mint one, and when cataloguing you should treat every container as a feature. A child may not be broader than its parent (nothing above a component, no domain under a feature). When in doubt, ask whether a deep read of this row alone would have specific files to open — if not, it is a feature.

Enum values:
domain
feature
component
​

Which plane a COMPONENT's code sits in. Derived from the node's FILES by a catalogue run — do not guess it: leave the field out unless you are mirroring a scan's own classification or a human's explicit choice. Null clears it, which is correct for a container that owns no code and for any feature (a feature spans layers and carries no layer, ever).

title
​string

A short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.

description
​string

Markdown, at most 200,000 characters. Replaces the whole description: send it only with the complete new text. To change part of the description, send descriptionEdits instead.

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

Change PART of the description without resending it: a list of exact find-and-replace edits the server applies to the stored description, in order, all or none. Each find must be copied exactly (same characters, spacing and line breaks) from the description as it stands, and must occur exactly once there at that point: include enough surrounding text to make it unique. replace is the new text (an empty string deletes the passage). Everything outside the passages is kept as it is. Prefer this over description for any change to a long description, and always when your read of the description was cut. Cannot be sent together with description.

priority
​string · enum
Enum values:
low
high
critical
status
​string · enum
Enum values:
backlog
planned
in_development
stable
deprecated
​
​
​
​

Set the single USER assignee (legacy 'owner' field): replaces the feature'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.

​
​
sortOrder
​number

Update a product feature › Responses

200

Updated feature

​FeatureDTO · required

Delete a product feature

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

Permanently remove a feature from the catalog.

Delete a product feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Delete a product feature › Responses

200

Feature deleted

No data returned

Generate suggested tasks for a feature

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/generate-tasks

Break a feature down into a suggested set of tasks using the AI task generator. The breakdown factors in the feature's title/description, its promoted feature requests (via PROMOTED_TO), the associated customer interests, and sibling features. Returns the suggested tasks WITHOUT creating them — the caller reviews the list and decides which to create (e.g. via create-task).

Generate suggested tasks for a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Generate suggested tasks for a feature › Responses

200

Suggested tasks (empty array if generation failed)


Generate an AI description for a feature

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/generate-description

Generate a template-structured description for a feature using the current title, description, and any linked feature requests (via PROMOTED_TO). Returns the generated markdown without persisting — the caller decides whether to apply it.

Generate an AI description for a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Generate an AI description for a feature › Responses

200

Generated feature description (description may be null if generation failed)

​required

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

Combines lexical and semantic search over features. Runs an indexed full-text search over every feature's title and whole description first: a match in the title ranks above a match in the description, and the best matches come first. Each hit carries match-highlighted snippets as plain-text segments (snippets[].segments[], each carrying match: true|false) for its title and for the opening of its description; a match further into a long description still finds the feature, without a body snippet. When the keyword query has no match and is longer than 5 characters, it falls back to semantic search over the knowledge base, so paraphrases still resolve (e.g. 'sign in flow' matches a feature titled 'Google SSO login'). Each result carries matchType: fulltext for the full-text path, semantic for knowledge-base fallback hits, whose scores are absolute semantic similarity, comparable across queries. Semantic hits below the server-side noise floor are filtered out, so an empty semantic fallback genuinely means no match.

Find a feature by name or topic (combined lexical + semantic search) › path Parameters

workspaceId
​string · required

Workspace UUID

Find a feature by name or topic (combined lexical + semantic search) › query Parameters

q
​string · required

Search query

limit
​integer · min: 1 · max: 50

Max results (default 20, cap 50)

Find a feature by name or topic (combined lexical + semantic search) › Responses

200

Ranked feature matches with snippets and matchType

​FeatureSearchResult[] · required

List version history for a feature document

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

Returns the version history of a feature document — every persisted snapshot, newest first. Use this to inspect prior wording, attribute changes to specific authors, or pick a version to restore.

List version history for a feature document › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List version history for a feature document › query Parameters

featureId
​string · required

Feature UUID

page
​number

Page number (1-indexed, default 1)

limit
​number

Items per page (default 50)

search
​string

Full-text search across searchable fields

List version history for a feature document › Responses

200

List of feature versions

​FeatureVersionDTO[] · required
​object
​object

Get a single feature document version

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

Fetch one historical version including its Lexical JSON state and the markdown projection. Useful for diff-rendering a snapshot or previewing before restore.

Get a single feature document version › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

versionId
​string · required

Version UUID

Get a single feature document version › Responses

200

Feature version detail

​FeatureVersionDetailDTO · required

Name a feature document version

PATCH
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/versions/{versionId}

Attach (or clear) a human-readable summary to a version so it surfaces nicely in the history panel.

Name a feature document version › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

versionId
​string · required

Version UUID

Name a feature document version › Request Body

​required

Name a feature document version › Responses

200

Renamed feature version

​FeatureVersionDTO · required

Restore a feature document to a historical version

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/versions/{versionId}/restore

Roll a feature document back to a prior version. Creates a new snapshot that mirrors the chosen version, writes it to the live feature, and broadcasts a doc:reset to any connected editors so they reload.

Restore a feature document to a historical version › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

versionId
​string · required

Version UUID

Restore a feature document to a historical version › Responses

200

Restored feature

​FeatureDTO · required

List the KB documents linked to a feature

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

Returns the knowledge base documents that document this feature (kb_document documents feature), with hierarchy fields so callers can render them as a tree.

List the KB documents linked to a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List the KB documents linked to a feature › Responses

200

Linked KB documents

​LinkedDocumentDTO[] · required

List the applications a feature depends on

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

Returns the applications linked to this feature (feature depends_on application). Each row carries the application id, display id (APP-N), name, repository name, and how much code surface the link records as two counts - codePathCount and entryPointCount, scan-recorded and hand-added together. The paths themselves are on get-feature-code-surface. For a monorepo application, services names the services of that application this feature lives in, as mapped by the architecture scan: source: folder when the feature's code paths sit inside the service's folder (matchedPath is the first one that does), source: manual when a person linked it by hand. An empty services means no service matched.

List the applications a feature depends on › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List the applications a feature depends on › Responses

200

Linked applications

​LinkedApplicationDTO[] · required

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

Creates a feature depends_on application link (idempotent — re-linking an existing pair is a no-op) and records the CODE SURFACE for the pair: the files that implement the feature (codePaths), the entry points attributed to it (entryPoints) and a handover note (capabilityNotes). The per-feature deep dive opens exactly that surface first, so a repository map pass must call this once per feature it touches, with the full lists. Each key is merged individually — passing a key replaces the stored value, omitting it leaves the stored value untouched. Returns the MERGED surface as it now stands, which is the outcome of that merge and not what you sent: totals is exact, and it supersedes the surface you were handed at dispatch. Write every statement about which files this component owns from these numbers rather than from the manifest, and state them in your specification's Code surface receipt.

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

applicationId
​string · minLength: 1 · required
codePaths
​string[] · maxItems: 200

Repository-relative paths that implement this feature, most important first: entry-point files, service/domain logic, validators and guards, the constants holding literal values, the data model, UI surfaces and the tests that pin the behaviour. A directory is fine when the whole directory implements the capability; narrow a shared file with a symbol (src/routes/api.ts#createBooking). Five to forty entries is normal — src/ alone is worse than useless. Passing this key REPLACES the stored list; omitting it leaves the stored list untouched.

entryPoints
​string[] · maxItems: 200

Exactly the entry points attributed to this feature, one per array entry, each as " — path:line" (POST /bookings — src/booking/booking.routes.ts:42, cron: reap-previews — src/jobs/reaper.ts:18). A path is not an entry point: the deep dive checks that every entry point listed here appears as its own contract block in the spec it writes. Passing this key REPLACES the stored list.

layer
​string · enum

Which layer this feature occupies IN THIS application — frontend, backend, data or external. Set by the workspace feature map, which is the only pass that sees several repositories at once and can therefore say a feature starts in a web app and ends in a database. Passing this key REPLACES the stored value; omitting it leaves it untouched, so a plain UI link can never blank it.

Enum values:
frontend
backend
data
external
capabilityNotes
​string · maxLength: 2000

One to three sentences the deep-dive agent reads before it starts: whether this is a domain parent and which cross-cutting concerns it owns, where the rule-dense code is, which feature it is easily confused with, and anything surprising noticed but not pursued. A handover note, not a summary — do not repeat the description here.

200

The merged code surface as it now stands, with exact totals

​LinkFeatureApplicationResult · required

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/applications/{applicationId}

Removes the feature depends_on application link. Returns the updated list of linked applications.

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

applicationId
​string · required

Application UUID

200

Updated linked applications

​LinkedApplicationDTO[] · required

PUT
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/applications/{applicationId}/surface

Writes the HUMAN-owned lists on one feature<->application link - manualCodePaths and manualEntryPoints, hiddenCodePaths (paths a scan recorded that a person replaced with a corrected one), and the link's services: manualSystemComponentIds (services of this application linked by hand) and hiddenSystemComponentIds (services matched by folder that a person hid). A key that is present replaces the stored list (send the whole edited list; remove an entry by omitting it); a key that is absent is left untouched. Kept apart from the scan's codePaths / entryPoints (link-feature-application) under keys no scan writes, so a hand-added entry, and a correction, survives every rescan. Every reader - the deep read, the spec audit, the reverse lookup, the rail - sees the union, and none of them sees a hidden path. To correct a path a scan recorded, add the corrected path to manualCodePaths and the old one to hiddenCodePaths in one request. Whenever either code-path list is sent, hiddenCodePaths keeps only the paths the scan's own list still holds and that are not on manualCodePaths, so adding a hidden path back by hand brings it back. Entries are trimmed, a leading ./ or / stripped, duplicates dropped, and the lists capped like the scan's. A service id you add must be a service of this application, or the request is refused with 400; adding a service by hand also un-hides it, and an id whose service no longer exists is dropped. A rewrite of the list already stored is a no-op. Returns the link's whole surface as it now stands, with its services and the application's services to choose from.

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

applicationId
​string · required

Application UUID

manualCodePaths
​string[] · maxItems: 200
manualEntryPoints
​string[] · maxItems: 200
hiddenCodePaths
​string[] · maxItems: 200
manualSystemComponentIds
​string[] · maxItems: 50
hiddenSystemComponentIds
​string[] · maxItems: 50

The link's code surface as it now stands — scan ∪ manual, with the manual lists beside it

​FeatureCodeSurfaceDTO · required

List a feature's dependency edges, both directions

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

Returns every feature-to-feature dependency edge touching this feature: direction "uses" rows are features this one builds on, "used_by" rows are features that build on this one. Each row carries the other feature (id, COMP-N/FEAT-N, title, kind, status) plus the recorded rationale and file:line evidence.

List a feature's dependency edges, both directions › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List a feature's dependency edges, both directions › Responses

200

Dependency edges

​FeatureDependencyLinkDTO[] · required

Record that this feature depends on another feature

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/dependencies

Creates a directed feature uses feature edge: this feature calls the target's API, consumes a queue it fills, or reads data it owns. Mutual coupling is two calls, one per direction. Idempotent — re-linking an existing pair merges the new rationale/evidence onto the stored edge instead of duplicating it. Never link a parent to its own child (the hierarchy already carries that), and never record 'both touch the same repository' trivia: an edge needs a mechanism. A feature holds at most 12 outgoing edges; past that the call is rejected and the coupling belongs on the parent feature. Returns the updated edge list.

Record that this feature depends on another feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID (the feature that USES the target)

Record that this feature depends on another feature › Request Body

targetFeatureId
​string · minLength: 1 · required

The feature this one builds on — the direction is <this feature> uses <target>: it calls the target's API, consumes a queue the target fills, or reads data the target owns. Mutual coupling is two separate calls, one in each direction. Linking an already-linked pair is safe and REPLACES the stored rationale/evidence.

rationale
​string · maxLength: 500

One sentence naming the MECHANISM of the dependency ("reads the bookings table BookingLedger owns", "calls POST /payments on checkout") — never a restatement that the two are related. Rendered to humans curating the map.

evidence
​string[] · maxItems: 20

Code locations proving the edge, each as "/:" — repo-prefixed because the two features usually live in different repositories.

Record that this feature depends on another feature › Responses

200

Updated dependency edges

​FeatureDependencyLinkDTO[] · required

Remove a feature dependency edge

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/dependencies/{targetFeatureId}

Removes the feature uses feature edge. Returns the updated edge list.

Remove a feature dependency edge › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID (the edge's source)

targetFeatureId
​string · required

Feature UUID (the edge's target)

Remove a feature dependency edge › Responses

200

Updated dependency edges

​FeatureDependencyLinkDTO[] · required

List a component's business rules, or roll them up over a feature

GET
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/business-rules

Returns business rules as rows, ordered for reading. Each carries the rule text, the literal values it compares against, where it is enforced, what happens when it is broken, the verbatim evidence quote and the code citations behind it. A feature owns no rules directly — its components do, so pass ?rollUp=true on a feature to get the union over every component beneath it, each row naming the component it came from. On a component, the default is its own applied set. ?proposalId= reads the rows a legacy markdown proposal parsed (which may not be applied yet) and ?batchId= reads one submit wave.

List a component's business rules, or roll them up over a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List a component's business rules, or roll them up over a feature › query Parameters

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

Return the rules parsed for this description proposal (the review overlay's case — rows that may not be current yet). Omit for the feature's current applied rule set.

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

Return one submit wave's rules, promoted or not. Omit for the current applied set.

rollUp
​string · enum

Return the applied rules of this feature's component descendants instead of its own. This is how a feature answers 'what are my business rules' — a feature owns none directly; its components do. Each row carries the component it belongs to.

Enum values:
true
false

List a component's business rules, or roll them up over a feature › Responses

200

Business rules, ordered by component then reading order

​FeatureBusinessRuleDTO[] · required

Write a wave of business rules against a component

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/business-rules

Records business rules on a component — the code-owning leaf of the feature tree. Call it repeatedly as you write, a wave at a time, with the same batchId; check each wave's evidence while the files you cited are still open, and set final: true on the last one to make the whole batch the component's applied rule set. Waves are cumulative and re-sending a batch replaces it, so a lost response is safe to retry. This replaces writing rules into a specification's ## Business Rules section: a document is capped at 200,000 characters and one message at 64,000 output tokens, and rules were half of it. Rejected on a feature — submit against the component whose code enforces the rule, and the feature's roll-up picks it up.

Write a wave of business rules against a component › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Component feature UUID

Write a wave of business rules against a component › Request Body

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

A UUID you mint for this submit wave and reuse on a retry. Re-sending the same batch replaces it rather than doubling it, which is what makes a lost response safe to repeat.

​object[] · minItems: 1 · maxItems: 40 · required

Up to 40 rules. Submit in waves as you write them, checking each wave's evidence while the files are still open, rather than accumulating the whole set for one call.

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

The scan session producing these rules, when there is one.

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

The description proposal these rules accompany, when there is one.

final
​boolean

True on the last wave. Promotes every wave of this batch to the component's applied rule set in one step, so a partial submit never half-replaces what is live.

Write a wave of business rules against a component › Responses

200

What the wave wrote, and whether the batch was promoted

​SubmitBusinessRulesResult · required

Make a submitted batch the component's applied rule set

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/business-rules/promote

Promotes one batchId to the component's applied rules, replacing the previous applied set written by the same kind of writer. Only needed when a run submitted its waves without final: true — the ordinary path promotes on the last wave.

Make a submitted batch the component's applied rule set › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Component feature UUID

Make a submitted batch the component's applied rule set › Request Body

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

The batch to make this component's applied rule set.

Make a submitted batch the component's applied rule set › Responses

200

How many rules became current

​object · required

Scan the feature's linked application repos and propose an updated description

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/refresh-description

Starts a background Productmind agent scan of every application repository linked to this feature. The agent surfaces the business/product logic in the code into a proposed replacement description, submitted as a FeatureDescriptionProposal the user reviews as a block diff before anything lands. Delta-aware: repos carry the last-scanned commit so subsequent scans focus on what changed. What is dispatched depends on the tier: a component, or a feature with no components, is read as one document and the queued proposal is returned; a feature that HAS components is never read as one document - a component read is started for each descendant that needs one and proposal comes back null. The parent's own specification is composed from them afterwards: call this again once nothing is left to read (it then composes and returns the composition proposal), or call compose-feature-description, which also composes around components that have no specification. The composition is not started automatically when the components finish. Returns 202 either way.

Scan the feature's linked application repos and propose an updated description › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Scan the feature's linked application repos and propose an updated description › Responses

What the call dispatched — either a queued proposal (which doubles as the scan run tracker) or the components it fanned out to

​FeatureRefreshDispatchDTO · required

Compose the feature's specification from its components

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/compose

Starts a background Productmind agent run that writes this feature's specification from its components' specifications and business rules, without reading any code. Components with no specification yet (never read, or their read failed) are named as gaps in the result rather than blocking it, and are returned in skippedComponents, but at least one component must have something to compose from: when none has a specification or a business rule yet, the request is refused (refresh the feature to read its components first). Only a feature with components can be composed; refresh a feature without components to read its code instead. Refused while any component is still being read, and while another description proposal is in progress for this feature. Uses AI credits (one user-hosted session when it runs on your own machine); a billing refusal is returned as that error (402 or 429). Returns 202 with the queued composition proposal.

Compose the feature's specification from its components › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Compose the feature's specification from its components › Responses

The queued composition proposal (it doubles as the run tracker; failed when the dispatch could not start for a reason other than billing) and the components composed around as gaps

​FeatureRefreshDispatchDTO · required

Revise the feature's specification from its open review comments

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/revise-from-comments

Sends the open comments on passages of this feature or component document to a background Productmind agent, which reads each comment and the code it concerns in the linked application repositories (for a feature composed from components, theirs), revises only the passages the comments point at, replies in every thread, and submits the result as a description proposal that is reviewed block by block before anything changes. The agent never resolves a thread: applying the proposal resolves the threads it was sent, and dismissing it leaves them open. At most the 50 oldest open threads are sent. Refused for a domain, when no linked application has a repository, when the document has no open comments, and while another description proposal is in progress for this feature. Uses AI credits (one user-hosted session when it runs on your own machine); a billing refusal is returned as that error (402 or 429), and nothing is started when no agent can run it. Returns 202 with the queued proposal.

Revise the feature's specification from its open review comments › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature or component UUID

Revise the feature's specification from its open review comments › Responses

The queued review proposal, which doubles as the run tracker

​FeatureReviewRevisionDTO · required

The files and entry points a scan recorded for this feature

GET
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/code-surface

Returns one entry per linked application carrying the code surface recorded on that link: codePaths (repository-relative paths that implement the feature), entryPoints ("<kind> <identifier> — <path:line>") and capabilityNotes. Both lists are the UNION of what the last scan recorded and what people added by hand, less the scan paths a person replaced; manualCodePaths / manualEntryPoints beside them are the hand-added lists as stored, and hiddenCodePaths the replaced paths as stored, which set-feature-application-surface edits and no scan ever touches. This is the same handover a per-feature deep read is scoped by, and it exists for EVERY catalogued node — including the capabilities the deterministic graph attaches no decision slice to. Empty arrays for a link made by hand with nothing added yet, or predating the two-phase discovery split; an application with no repository is listed with repoName null.

The files and entry points a scan recorded for this feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

The files and entry points a scan recorded for this feature › Responses

200

One recorded code surface per linked application

​FeatureCodeSurfaceDTO[] · required

How the feature's linked repos compare to their last scan baselines

GET
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/refresh-status

Counts the commits on each linked application repo's base branch since that link's last-scanned commit (via the git provider's compare API). Drives the feature doc's Refresh control: new_commits shows the 'N new commits' pill, up_to_date disables the button, unknown (never scanned / provider error / service auth) keeps it enabled with no notice. Results are cached ~60s per repo+baseline.

How the feature's linked repos compare to their last scan baselines › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

How the feature's linked repos compare to their last scan baselines › Responses

200

Aggregate freshness plus one entry per linked application

​FeatureRefreshStatusDTO · required

List description proposals for a feature

GET
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals

Returns the feature's scan-driven description proposals, newest first. Pass ?activeOnly=true for the single in-flight proposal (queued/running/awaiting_review), if any — the feature document page polls this to drive the refresh control.

List description proposals for a feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

List description proposals for a feature › query Parameters

status
​string · enum

Filter by status

Enum values:
queued
running
awaiting_review
approved
applied
dismissed
failed
activeOnly
​boolean

Only the active proposal, if any

List description proposals for a feature › Responses

200

Description proposals

​FeatureDescriptionProposalDTO[] · required

Propose an updated description for an existing feature

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals

Submit a FULL replacement markdown description for an existing feature as a reviewable proposal. This REPLACES update-feature for every scan-driven description change: the proposal is shown to a human as a block-by-block diff (accept/reject per block) and only lands after they apply it - EXCEPT a deep-dive proposal (a feature the repository map pass just created, whose description is still the untouched one-paragraph stub), which applies immediately; a user edit mid-scan drops it back to human review. Pass the scan session id (from your Session context) as sessionId so the proposal is bound to your run. Returns 409 when a proposal is already pending for the feature - skip it and note the conflict in your final report. CALL THIS ONCE. The reply is a receipt, not the document, and any auditResult findings on it are ADVISORY - they are recorded for the reviewer and never block, so a finding is not a reason to submit again: submitting a corrected document over one that already landed does not replace it, it opens a SECOND proposal that parks the applied work behind review and takes the feature's only proposal slot. Retry only a call that failed to land (transport error, timeout, 5xx). If the Productmind agent's productmind-mcp server is available, prefer its submit_feature_spec, which sends the document from a file instead of re-typing it. From a CODING session, call this in the pre-PR documentation turn when the change altered what a user can observe (find the candidates with find-features-by-code-paths): the proposal is reviewed in the session's PR rail beside the documentation proposals and lands when the pull request merges.

Propose an updated description for an existing feature › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

Propose an updated description for an existing feature › Request Body

proposedDescriptionMarkdown
​string · minLength: 1 · maxLength: 200000 · required

The FULL replacement description markdown for the feature. Code citations are link tokens — path/to/file.ext:line @ — never wrapped in backticks; the sha is the HEAD of the clone you read.

summary
​string · maxLength: 8000

One-paragraph summary of what changed and why

sessionId
​string

The scan session id (from the Context section of your instructions)

​

REQUIRED by the deep-read instructions: either the Knowledge Base document ids you created for this feature's technical architecture (API contracts, data layers, databases, queues, execution models, state managers), or an explicit reason none was needed.

commentId
​string

When you answer a comment thread on this feature's document (your turn input names it): the thread's id, exactly as given. The suggestion is then linked to the thread, and applying it resolves the thread. Only the thread you were asked to answer, while you answer it; omit it otherwise.

Propose an updated description for an existing feature › Responses

Receipt for the submitted proposal — status, whether it applied, and any advisory audit findings. It deliberately does NOT echo the description back: you just sent it, and on a second submit the echo (which carries the previously applied text as well) grows past what a tool result can carry.


Apply a reviewed description proposal

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals/{proposalId}/apply

Writes the user-composed markdown (accepted diff blocks applied onto the current description) to the feature via the standard versioned update path (a restorable FeatureVersion snapshot is taken first), broadcasts doc:reset to connected editors, marks the proposal applied, and stamps the scanned commits onto the feature↔application links as the next scan's delta baseline.

Apply a reviewed description proposal › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

proposalId
​string · required

Proposal UUID

Apply a reviewed description proposal › Request Body

description
​string · minLength: 1 · maxLength: 200000 · required
draftVersion
​integer · min: 0 · max: 9007199254740991

Apply a reviewed description proposal › Responses

200

Applied proposal

​FeatureDescriptionProposalDTO · required

Approve a session's description proposal without applying it

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals/{proposalId}/approve

The PR-rail review of a session proposal: freezes the user-composed markdown (accepted diff blocks applied onto the current description) as approvedDescriptionMarkdown and re-freezes the base to the live description, so the PR-merge webhook writes exactly what was approved and can veto on drift. Does NOT write the feature — that happens when the pull request merges (or on the feature page, where apply accepts an approved proposal). Only an awaiting_review proposal from a coding session can be approved.

Approve a session's description proposal without applying it › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

proposalId
​string · required

Proposal UUID

Approve a session's description proposal without applying it › Request Body

description
​string · minLength: 1 · maxLength: 200000 · required
draftVersion
​integer · min: 0 · max: 9007199254740991

Approve a session's description proposal without applying it › Responses

Approved proposal

​FeatureDescriptionProposalDTO · required

Dismiss a description proposal

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals/{proposalId}/dismiss

Rejects the proposal wholesale. The scan baseline on the feature↔application links is NOT advanced, so the next refresh re-scans from the last applied baseline.

Dismiss a description proposal › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

proposalId
​string · required

Proposal UUID

Dismiss a description proposal › Responses

200

Dismissed proposal

​FeatureDescriptionProposalDTO · required

Cancel an in-flight description scan

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/description-proposals/{proposalId}/cancel

Stops a queued/running refresh scan: settles the proposal (failed/'Cancelled', releasing the one-active-per-feature slot) and best-effort cancels the backing scan session so the agent stops. A proposal already awaiting review cannot be cancelled - dismiss it instead. The scan baseline is never advanced. Only the person who started the scan, or someone who manages the workspace (an organization Owner or Admin, the workspace's owner or one of its admins), can stop it.

Cancel an in-flight description scan › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

proposalId
​string · required

Proposal UUID

Cancel an in-flight description scan › Responses

Cancelled proposal

​FeatureDescriptionProposalDTO · required

Propose splitting a flat feature into a parent + subfeatures (human-reviewed)

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/structure-proposals

Use this (instead of create-feature / propose-feature-description) when an EXISTING flat feature should become a high-level domain PARENT with new detailed subfeatures — e.g. turning one 'Finance — payment ledger & invoicing' feature into a 'Finance' parent with 'Payment ledger' and 'Invoicing' children. Optionally retitle/redescribe THIS feature as the parent (parentTitle/parentDescriptionMarkdown), list the ordered NEW children, and/or re-parent THIS feature under an existing one (moveUnderParentId). A human reviews the proposed split before anything is created/re-parented. Pass your scan session id as sessionId. Returns 409 when a proposal is already pending for the feature — skip it and note the conflict. Only propose a split for a feature that has NO existing children.

Propose splitting a flat feature into a parent + subfeatures (human-reviewed) › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID (the subject that becomes the parent)

Propose splitting a flat feature into a parent + subfeatures (human-reviewed) › Request Body

parentTitle
​string · minLength: 1 · maxLength: 300

New title for THIS feature, retitled as a high-level domain parent (e.g. 'Finance'). Omit to keep the current title. A short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.

parentDescriptionMarkdown
​string · maxLength: 200000

New HIGH-LEVEL description for THIS feature as the domain parent — what the domain does and the sub-capabilities it contains. Omit to keep the current description.

​object[] · maxItems: 20

Ordered NEW subfeatures to create under this feature, each with its own full detailed spec.

Default: []
​

Optionally re-parent THIS feature. Pass an existing feature id to move it under that parent, or null to promote it to a ROOT feature (use this for a domain wrongly filed under an era/technology bucket). Omit the key entirely to leave it where it is — null and omitted mean different things.

summary
​string · maxLength: 8000

One-paragraph summary of the proposed restructure and why.

sessionId
​string

The scan session id (from the Context section of your instructions).

Propose splitting a flat feature into a parent + subfeatures (human-reviewed) › Responses

Structure proposal awaiting review

​FeatureDescriptionProposalDTO · required

Apply a reviewed structure proposal

POST
https://api.productmind.ai
/workspaces/{workspaceId}/features/{id}/structure-proposals/{proposalId}/apply

Performs the reviewer-edited restructure atomically: snapshots + retitles/redescribes the subject feature (broadcasting doc:reset to connected editors, with a restorable FeatureVersion), creates the ordered new children under it, optionally re-parents it, links the new children to the scanned application, and marks the proposal applied. Note: one-click restore of the 'Before restructure' version reverts only the subject's DESCRIPTION — restoreVersion never reassigns the title, and it does not remove the created children.

Apply a reviewed structure proposal › path Parameters

workspaceId
​string · required

Workspace UUID

id
​string · required

Feature UUID

proposalId
​string · required

Proposal UUID

Apply a reviewed structure proposal › Request Body

parentTitle
​string · minLength: 1 · maxLength: 300
parentDescriptionMarkdown
​string · maxLength: 200000
​object[] · maxItems: 20
Default: []
​

Apply a reviewed structure proposal › Responses

Applied structure proposal

​FeatureDescriptionProposalDTO · required