Ideas

Ideas are the tangible solutions you're considering to address your opportunities. Track features, experiments, and improvements through their evaluation lifecycle.

17 endpoints

GET

Read the Idea plan

GET /external/v1/ideas/:id/plan

Read the native Idea Brief and a page of its Questions before curating. These are the same records shown on the Idea in Zentrik. report is null when no Brief exists; otherwise it includes id, ideaId, status, complete reportMarkdown and timestamps. Evidence snapshots and provider diagnostics are omitted. Question pagination uses X-Total-Count, X-Limit, X-Offset and X-Has-More. The separate definition field is returned by Get one idea; it is not the Brief.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
id *	uuid \| public ID	Idea reference in the API-key workspace, for example IDEA-42.
limit	integer	Question page size, 1–100; default 20.
offset	integer	Question offset; default 0.

Responses

200

Plan retrieved

Native questions and the latest Brief version.

400

Invalid input

Malformed, missing or unsupported fields.

403

Missing scope

The key lacks the required Idea scope.

404

Not found

The Idea or question is outside the key workspace.

Example Response

200 OK

json

{
  "questions": [],
  "report": null
}

POST

Create an unanswered question

POST /external/v1/ideas/:id/questions

Create an unanswered, unassigned native Question. This operation sends no assignment or invitation and does not save a suggested answer as a human answer. Generate the body id once and reuse the same body and ID after an uncertain response. A matching retry returns the existing question, including any answer since added by a person; a reused ID with different wording, reasoning or parent returns 409.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	uuid \| public ID	Idea reference in the API-key workspace, for example IDEA-42.

Request body (application/json)

iduuid

Required

Caller-generated stable Question ID for this creation request.

questionstring

Required

Non-empty question, up to 4,000 characters.

reasoningstring | null

Why this uncertainty changes the decision; up to 8,000 characters.

Responses

201

Question saved

The saved Question; retries retain its current answer and assignment.

Schema

IdeaQuestion

409

ID conflict

Read the saved question before using a different request ID.

400

Invalid input

Malformed, missing or unsupported fields.

403

Missing scope

The key lacks the required Idea scope.

404

Not found

The Idea or question is outside the key workspace.

Example Response

201 Created

json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "question": "Which reviewer must accept the proof?",
  "answer": null,
  "status": "pending",
  "assignee": null
}

PATCH

Revise an open question

PATCH /external/v1/ideas/:id/questions/:questionId

Revise an unanswered open or set-aside Question using its current updatedAt. Provide question or reasoning. Stale versions, resolved questions and questions with saved answers return 409. This does not reopen, answer, assign or notify anyone. Use the separate answer operation only for an actual answer supplied or approved by a person.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	uuid \| public ID	Idea reference in the API-key workspace, for example IDEA-42.
questionId *	uuid	The native Question ID.

Request body (application/json)

expectedUpdatedAtISO 8601 string

Required

Exact current updatedAt from the Question read.

questionstring

Revised non-empty wording, up to 4,000 characters.

reasoningstring | null

Revised rationale, up to 8,000 characters; null clears it.

Responses

200

Question revised

Schema

IdeaQuestion

409

Question changed

Read the current Question and preserve the saved answer or newer edit.

400

Invalid input

Malformed, missing or unsupported fields.

403

Missing scope

The key lacks the required Idea scope.

404

Not found

The Idea or question is outside the key workspace.

PUT

Save an authored Brief version

PUT /external/v1/ideas/:id/brief

Save an authored native Idea Brief without generating it with AI. First read the plan. Supply both expected fields as null only when report is null; otherwise copy the latest report id and updatedAt. Each successful request creates a completed native Brief version with current Question and bounded source-context snapshots; prior versions remain. Active generation and stale edits return 409. Reuse the same new body id and identical request after an uncertain response. This does not change the Idea description, answer Questions, approve work or send messages.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	uuid \| public ID	Idea reference in the API-key workspace, for example IDEA-42.

Request body (application/json)

iduuid

Required

Caller-generated stable ID for this new authored Brief version.

expectedReportIduuid | null

Required

Latest report ID, or explicit null if no Brief exists.

expectedUpdatedAtISO 8601 string | null

Required

Latest report updatedAt, or explicit null if no Brief exists.

reportMarkdownstring

Required

Complete authored Markdown, 1–100,000 characters after trimming.

Responses

200

Brief saved

Native version ID, Idea ID, status, full reportMarkdown and timestamps. Read the plan again to confirm the latest version.

409

Brief changed

The Brief, Idea or request ID changed, or generation is active. Read the plan and reconcile before another save.

400

Invalid input

Malformed, missing or unsupported fields.

403

Missing scope

The key lacks the required Idea scope.

404

Not found

The Idea or question is outside the key workspace.

POST

Match product features

POST /external/v1/ideas/:id/match-features

Match the captured request to existing Features in its Product. Clear, source-grounded matches are applied; uncertain matches remain suggestions. Manual selections, including an empty selection, are preserved. A Feature relation does not mean the request is fulfilled. Repeated calls reuse an unchanged result.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	string	Idea UUID or workspace public ID, for example IDEA-42.

Responses

201

Matched

Returns the saved featureIds and featureMatching state. Check status: matched, needs_review, no_match, no_features, or manual. Missing Product returns null.

Schema

Idea

404

Not found

The Idea is not in the API-key workspace.

409

Changed during matching

The Idea or Product map changed. Read the current record and retry.

GET

Read saved classifications

GET /external/v1/ideas/:id/classifications

Read current taxonomy values and review state, or apply the same manual review actions as the product. Use groupKey from the active taxonomy and optionIds returned by this read. Read the result after a correction; a preview or completed model run is not a review.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
id *	string	Internal UUID or workspace-scoped public ID.

Responses

200

Success

Current taxonomy version, group values and review summary.

Example Request

GET

/external/v1/ideas/:id/classifications

http

GET /external/v1/ideas/IDEA-42/classifications

PATCH

Review classifications

PATCH /external/v1/ideas/:id/classifications

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	string	Internal UUID or workspace-scoped public ID.

Request body (application/json)

updatesClassificationUpdate[]

Required

Exactly one update identifies groupKey or taxonomyGroupId and action: accept, reject, set_option, set_text or mark_unassigned. set_option supplies optionIds; set_text supplies textValue. Submit one group per operation so each correction has a separate receipt.

Responses

200

Success

Current taxonomy version, group values and review summary.

Example Request

PATCH

/external/v1/ideas/:id/classifications

http

PATCH /external/v1/ideas/IDEA-42/classifications

{"updates":[{"groupKey":"workflow","action":"accept"}]}

GET

Read an Idea’s evidence

GET /external/v1/ideas/:id/evidence

List exact evidence directly linked to an Idea. Each record includes its relationship role (supports, qualifies, contradicts or context) and origin. A link alone does not mean the work addressed that evidence. Select the records covered by delivered work before resolving them. This endpoint does not infer evidence through related Insights or Opportunities. It needs ideas:read plus signal-evidence:read or signals:read. List responses are arrays with X-Total-Count, X-Limit, X-Offset and X-Has-More headers. Continue until X-Has-More is false; concurrent edits can shift offset pages.

Requirements

API scopes required:

ideas:read

signal-evidence:read

Request

Parameters

Name	Type	Description
id *	uuid \| public id	Idea reference, for example IDEA-42.
limit	integer	1–50; default 20.
offset	integer	Default 0.
visibility	enum	active (default) or all.

Responses

200

Success

The requested data is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

Example Response

200 OK

json

[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "title": "Export duplicates rows",
    "description": "Retrying the export adds a second copy.",
    "extracts": null,
    "category": "Product bug",
    "signalId": null,
    "resolvedAt": null,
    "resolution": null,
    "resolvedByUserId": null,
    "dismissedAt": null,
    "role": "supports",
    "origin": "entity_creation",
    "signalPublicId": null
  }
]

PATCH

Change an Idea status

PATCH /external/v1/ideas/:id/status

Apply the exact workspace-configured status label to one Idea. expectedCurrentStatus rejects stale writes. The configured promotion status is reserved for the promotion workflow; this operation never creates an Initiative. Task and evidence states are independent.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	uuid \| public id	Idea reference, for example IDEA-42.

Request body (application/json)

statusstring

Required

Exact workspace status label, 1–120 characters.

expectedCurrentStatusstring

Optional previously observed status label.

Responses

200

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Request

PATCH

/external/v1/ideas/:id/status

json

{
  "status": "Shipped",
  "expectedCurrentStatus": "Approved"
}

Example Response

200 OK

json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "publicId": "IDEA-42",
  "status": "Shipped",
  "previousStatus": "Approved",
  "changed": true
}

GET

List ideas

GET /external/v1/ideas

Get a bounded page of potential solutions and features tracked as ideas.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
include	string	Use classifications to return saved taxonomy version, values, labels and review status.
limit	number	Maximum number of items to return (default: 20, maximum: 100)
offset	number	Number of items to skip (default: 0)
sourceKey	string	Exact stable source namespace to match
externalId	string	Exact source-record identifier to match
integrationId	uuid	Exact connected integration identifier to match

Responses

200

Success

List of ideas retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers.

Schema

Array<Idea>

Example Request

GET

/external/v1/ideas

curl

curl -X GET https://zentrik.ai/api/external/v1/ideas?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "uuid",
    "name": "Implement one-click checkout",
    "description": "Reduce friction by storing user preferences...",
    "status": "New"
  }
]

GET

Get one idea

GET /external/v1/ideas/:id

Retrieve one feature idea by its internal UUID or human-readable public ID. The response includes description and the separate saved team definition (nullable). The native Idea Brief is read through the plan endpoint.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
include	string	Use classifications to return saved taxonomy version, values, labels and review status.
id *	string	The internal UUID or public ID (for example, IDEA-42)

Responses

200

Success

Schema

Idea

Example Request

GET

/external/v1/ideas/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/ideas/IDEA-42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET

List idea questions

GET /external/v1/ideas/:id/questions

List the questions on an idea, whether Zentrik generated them or people added them in the app, with their current answers, by internal UUID or human-readable public ID. `reasoning` says why a question matters and `placeholder` is Zentrik's drafted answer. `status` is `pending` (open), `skipped` (set aside: still open, out of the open list), `answered`, or `rejected` (not relevant). Results use the standard pagination headers.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
id *	string	The internal UUID or public ID (for example, IDEA-42)
limit	number	Maximum number of questions to return (default: 20, maximum: 100)
offset	number	Number of questions to skip (default: 0)

Responses

200

Success

Questions were retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers.

Schema

Array<IdeaQuestion>

404

Not found

The idea is not in the API-key workspace.

Example Request

GET

/external/v1/ideas/:id/questions

curl

curl -X GET 'https://zentrik.ai/api/external/v1/ideas/IDEA-42/questions?limit=20&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "question-uuid",
    "ideaId": "idea-uuid",
    "question": "Which workflow should ship first?",
    "answer": null,
    "placeholder": "Name the first workflow",
    "reasoning": "The rollout plan depends on which workflow users meet first.",
    "status": "pending",
    "createdAt": "2026-08-05T10:00:00.000Z",
    "updatedAt": "2026-08-05T10:00:00.000Z"
  }
]

PATCH

Answer an idea question

PATCH /external/v1/ideas/:id/questions/:questionId/answer

Answer an open or set-aside question, or revise its current answer. The idea reference is workspace-scoped and may be an internal UUID or public ID.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	string	The internal UUID or public ID (for example, IDEA-42)
questionId *	uuid	The question UUID returned by the list endpoint

Request body (application/json)

answerstring

Required

The non-empty answer to save

Responses

200

Updated

The persisted question and answer were returned.

Schema

IdeaQuestion

400

Invalid request

The answer is empty, or questionId is not a question UUID.

404

Not found

The idea or question is outside the API-key workspace.

Example Request

PATCH

/external/v1/ideas/:id/questions/:questionId/answer

curl

curl -X PATCH https://zentrik.ai/api/external/v1/ideas/IDEA-42/questions/QUESTION_UUID/answer \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"answer":"Workspace setup"}'

Example Response

200 OK

json

{
  "id": "question-uuid",
  "ideaId": "idea-uuid",
  "question": "Which workflow should ship first?",
  "answer": "Workspace setup",
  "placeholder": "Name the first workflow",
  "reasoning": "The rollout plan depends on which workflow users meet first.",
  "status": "answered",
  "createdAt": "2026-08-05T10:00:00.000Z",
  "updatedAt": "2026-08-06T10:00:00.000Z"
}

POST

Create an idea

POST /external/v1/ideas

Submit or idempotently update a feature idea or solution. Send sourceKey with externalId for a stable source identity. A repeat request with the same pair updates the existing idea, and an omitted status preserves its current workflow state.

Requirements

API scopes required:

ideas:write

Request

Request body (application/json)

namestring

Title of the idea. Zentrik generates one from the description when omitted.

descriptionstring

Required

Detailed description of the solution

statusstring

Exact workspace-configured Idea status. Omit it during an idempotent update to preserve the current status.

sourceKeystring

Stable source namespace. Use it with externalId for idempotent create-or-update behavior.

externalIdstring

Stable record identifier within sourceKey.

integrationIduuid

Connected integration identifier for integration-owned records.

productIduuid

Workspace Product whose Feature map should be used.

featureIdsuuid[]

Explicit same-product Feature selection. Omit for automatic matching; an empty list keeps the field unlinked.

insightIdsuuid[]

Insights to link to the idea.

accountIdsuuid[]

Accounts related to the Idea. Link only Accounts supported by its source or Evidence; the relationship does not claim current usage or endorsement.

validateInsightLinksboolean

Set true only when insightIds are an explicitly confirmed evidence path. Existing confirmed links are never demoted when omitted or false.

classificationsClassificationAssignment[]

Patch-style workspace taxonomy assignments. Use group keys plus option keys or labels from the active taxonomy. Each item must provide optionValues for a list group or textValue for a text group.

Responses

201

Created

The idea was successfully created.

Schema

Idea

Example Request

POST

/external/v1/ideas

json

{
  "name": "AI-powered search",
  "description": "Use LLMs to improve search relevance...",
  "sourceKey": "research-repository",
  "externalId": "proposal-184",
  "accountIds": [
    "account-uuid"
  ],
  "classifications": [
    {
      "groupKey": "stage",
      "optionValues": [
        "validation"
      ]
    },
    {
      "groupKey": "phi_level",
      "optionValues": [
        "high"
      ]
    }
  ]
}

Example Response

201 Created

json

{
  "id": "uuid",
  "name": "AI-powered search",
  "sourceKey": "research-repository",
  "externalId": "proposal-184",
  "accountIds": [
    "account-uuid"
  ],
  "provenance": {
    "method": "external_api"
  },
  "taxonomyVersionId": "taxonomy-version-uuid",
  "classifications": [
    {
      "groupKey": "stage",
      "optionLabels": [
        "Validation"
      ]
    },
    {
      "groupKey": "phi_level",
      "optionLabels": [
        "High"
      ]
    }
  ]
}

PATCH

Update an idea

PATCH /external/v1/ideas/:id

Modify an existing idea by its internal UUID or human-readable public ID. Classification assignments patch only the supplied workspace taxonomy groups; omitted groups remain unchanged. An idea can belong to only one Initiative: use projectId: null to detach it before attaching it to a different Initiative.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	string	The internal UUID or public ID (for example, IDEA-42)

Request body (application/json)

namestring

Updated name

descriptionstring

Updated description

projectIdstring | null

Initiative UUID/public ID to attach this idea to, or null to detach it

featureIdsuuid[]

Replace related Features and take manual ownership. An empty list removes them; future automatic matches do not restore them.

insightIdsuuid[]

Replacement set of linked Insights.

accountIdsuuid[]

Replacement set of related workspace Accounts. Use only source-supported links; a relationship does not claim current usage or endorsement.

validateInsightLinksboolean

Set true only to confirm the supplied insightIds as validated evidence links.

classificationsClassificationAssignment[]

Workspace taxonomy assignments. Use optionValues: [] or textValue: null to mark a supplied group unassigned.

Responses

200

Updated

Schema

Idea

400

Invalid Initiative link

The target is invalid, or the idea is already linked to another Initiative. Detach it with projectId: null before attaching the new Initiative.

Example Request

PATCH

/external/v1/ideas/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/ideas/IDEA-42 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"INITIATIVE-7","accountIds":["account-uuid"],"classifications":[{"groupKey":"category","optionValues":["workflow"]}]}'

DELETE

Delete an idea

DELETE /external/v1/ideas/:id

Permanently delete an idea by its internal UUID or human-readable public ID.

Requirements

API scopes required:

ideas:delete

Request

Parameters

Name	Type	Description
id *	string	The internal UUID or public ID (for example, IDEA-42)

Responses

200

Success

Example Request

DELETE

/external/v1/ideas/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/ideas/IDEA-42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

DELETE

Delete an idea comment

DELETE /external/v1/ideas/:id/comments/:commentId

Delete one comment from an idea without deleting or rewriting the idea. External API keys are workspace-admin credentials because only workspace owners/admins can create them.

Requirements

API scopes required:

ideas:delete

Request

Parameters

Name	Type	Description
id *	string	The idea's internal UUID or public ID (for example, IDEA-42)
commentId *	string	The comment UUID

Responses

200

Deleted

The scoped comment was deleted. The receipt does not include comment content.

Schema

IdeaCommentDeletionReceipt

404

Not found

The idea is outside the API-key workspace, or the comment does not belong to that idea and workspace.

Example Request

DELETE

/external/v1/ideas/:id/comments/:commentId

curl

curl -X DELETE https://zentrik.ai/api/external/v1/ideas/IDEA-42/comments/COMMENT_UUID \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "success": true,
  "ideaId": "uuid",
  "ideaPublicId": "IDEA-42",
  "commentId": "uuid"
}

Data Models

The Idea model represents a potential feature or solution that addresses identified opportunities.

Idea Object

Field	Type	Description
id	uuid	The unique identifier for the idea.
name	string	The title or name of the feature idea.
description	string	Detailed description of the proposed solution.
status	string	The workspace-configured Idea workflow status.
productId	uuid	The ID of the product this idea belongs to.
featureIds	uuid[]	Related Product Feature IDs, available in list and detail reads.
featureMatching	object \| null	Matching status, applied matches and review suggestions. Each selection includes featureId, reasoning and an exact sourceQuote.
projectId	uuid \| null	The initiative this idea is attached to, or null when it is not attached.
integrationId	uuid \| null	The integration this idea was imported from, or null when it was not created via an integration.
sourceKey	string \| null	The stable source namespace used with externalId for idempotent synchronization.
externalId	string \| null	The idea's identifier within sourceKey, or within its connected integration.
createdSource	string \| null	Legacy-compatible creation-channel classification.
provenance	object \| null	Durable creation origin. External API callers cannot rewrite this value after creation.
opportunityIds	uuid[]	List of opportunities that this idea addresses.
insightIds	uuid[]	List of insights that inspired this idea.
taxonomyVersionId	uuid \| null	The active workspace taxonomy version used when classifications were written.
classificationSummary	object	Current saved taxonomy summary when include=classifications is requested or classifications are written.
classifications	ClassificationValue[]	Persisted classification values returned with include=classifications or a classification write.
createdAt	iso-date	Creation timestamp.
updatedAt	iso-date	Last update timestamp.