--- title: "Ideas API reference" canonical_url: https://zentrik.ai/docs/api/ideas markdown_url: https://zentrik.ai/docs/api/ideas.md last_reviewed: 2026-10-25 --- # Ideas API reference Ideas are the tangible solutions you're considering to address your opportunities. Track features, experiments, and improvements through their evaluation lifecycle. - Human reference: https://zentrik.ai/docs/api/ideas - Complete Markdown index: https://zentrik.ai/docs/api/index.md - Base URL: `https://zentrik.ai/api` - Authentication: `Authorization: Bearer YOUR_API_KEY` - Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions ## GET /external/v1/ideas/:id/plan — Read the Idea plan Operation ID: `get-idea-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. Required API key scopes: `ideas:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public ID | Yes | Idea reference in the API-key workspace, for example IDEA-42. | | `limit` | integer | No | Question page size, 1–100; default 20. | | `offset` | integer | No | Question offset; default 0. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 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 ```json { "questions": [], "report": null } ``` --- ## POST /external/v1/ideas/:id/questions — Create an unanswered question Operation ID: `create-idea-question` 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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public ID | Yes | Idea reference in the API-key workspace, for example IDEA-42. | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid | Yes | Caller-generated stable Question ID for this creation request. | | `question` | string | Yes | Non-empty question, up to 4,000 characters. | | `reasoning` | string \| null | No | Why this uncertainty changes the decision; up to 8,000 characters. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 201 | Question saved | The saved Question; retries retain its current answer and assignment. | 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 ```json { "id": "33333333-3333-4333-8333-333333333333", "question": "Which reviewer must accept the proof?", "answer": null, "status": "pending", "assignee": null } ``` --- ## PATCH /external/v1/ideas/:id/questions/:questionId — Revise an open question Operation ID: `revise-idea-question` 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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public ID | Yes | Idea reference in the API-key workspace, for example IDEA-42. | | `questionId` | uuid | Yes | The native Question ID. | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `expectedUpdatedAt` | ISO 8601 string | Yes | Exact current updatedAt from the Question read. | | `question` | string | No | Revised non-empty wording, up to 4,000 characters. | | `reasoning` | string \| null | No | Revised rationale, up to 8,000 characters; null clears it. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Question revised | | 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 /external/v1/ideas/:id/brief — Save an authored Brief version Operation ID: `save-idea-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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public ID | Yes | Idea reference in the API-key workspace, for example IDEA-42. | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid | Yes | Caller-generated stable ID for this new authored Brief version. | | `expectedReportId` | uuid \| null | Yes | Latest report ID, or explicit null if no Brief exists. | | `expectedUpdatedAt` | ISO 8601 string \| null | Yes | Latest report updatedAt, or explicit null if no Brief exists. | | `reportMarkdown` | string | Yes | Complete authored Markdown, 1–100,000 characters after trimming. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 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 /external/v1/ideas/:id/match-features — Match product features Operation ID: `match-idea-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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | Idea UUID or workspace public ID, for example IDEA-42. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 201 | Matched | Returns the saved featureIds and featureMatching state. Check status: matched, needs_review, no_match, no_features, or manual. Missing Product returns null. | 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 /external/v1/ideas/:id/classifications — Read saved classifications Operation ID: `get-idea-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. Required API key scopes: `ideas:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | Internal UUID or workspace-scoped public ID. | ### Example request ```http GET /external/v1/ideas/IDEA-42/classifications ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | Current taxonomy version, group values and review summary. | — | --- ## PATCH /external/v1/ideas/:id/classifications — Review classifications Operation ID: `update-idea-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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | Internal UUID or workspace-scoped public ID. | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `updates` | ClassificationUpdate[] | Yes | 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. | ### Example request ```http PATCH /external/v1/ideas/IDEA-42/classifications {"updates":[{"groupKey":"workflow","action":"accept"}]} ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | Current taxonomy version, group values and review summary. | — | --- ## GET /external/v1/ideas/:id/evidence — Read an Idea’s evidence Operation ID: `get-idea-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. Required API key scopes: `ideas:read`, `signal-evidence:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public id | Yes | Idea reference, for example IDEA-42. | | `limit` | integer | No | 1–50; default 20. | | `offset` | integer | No | Default 0. | | `visibility` | enum | No | active (default) or all. | ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 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 ```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 /external/v1/ideas/:id/status — Change an Idea status Operation ID: `set-idea-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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | uuid \| public id | Yes | Idea reference, for example IDEA-42. | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `status` | string | Yes | Exact workspace status label, 1–120 characters. | | `expectedCurrentStatus` | string | No | Optional previously observed status label. | ### Example request ```json { "status": "Shipped", "expectedCurrentStatus": "Approved" } ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 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 response ```json { "id": "33333333-3333-4333-8333-333333333333", "publicId": "IDEA-42", "status": "Shipped", "previousStatus": "Approved", "changed": true } ``` --- ## GET /external/v1/ideas — List ideas Operation ID: `list-ideas` Get a bounded page of potential solutions and features tracked as ideas. Required API key scopes: `ideas:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `include` | string | No | Use classifications to return saved taxonomy version, values, labels and review status. | | `limit` | number | No | Maximum number of items to return (default: 20, maximum: 100) | | `offset` | number | No | Number of items to skip (default: 0) | | `sourceKey` | string | No | Exact stable source namespace to match | | `externalId` | string | No | Exact source-record identifier to match | | `integrationId` | uuid | No | Exact connected integration identifier to match | ### Example request ```curl curl -X GET https://zentrik.ai/api/external/v1/ideas?limit=10 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | List of ideas retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers. | Array | ### Example response ```json [ { "id": "uuid", "name": "Implement one-click checkout", "description": "Reduce friction by storing user preferences...", "status": "New" } ] ``` --- ## GET /external/v1/ideas/:id — Get one idea Operation ID: `get-idea` 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. Required API key scopes: `ideas:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `include` | string | No | Use classifications to return saved taxonomy version, values, labels and review status. | | `id` | string | Yes | The internal UUID or public ID (for example, IDEA-42) | ### Example request ```curl curl -X GET https://zentrik.ai/api/external/v1/ideas/IDEA-42 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | | Idea | --- ## GET /external/v1/ideas/:id/questions — List idea questions Operation ID: `list-idea-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. Required API key scopes: `ideas:read` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | The internal UUID or public ID (for example, IDEA-42) | | `limit` | number | No | Maximum number of questions to return (default: 20, maximum: 100) | | `offset` | number | No | Number of questions to skip (default: 0) | ### Example request ```curl curl -X GET 'https://zentrik.ai/api/external/v1/ideas/IDEA-42/questions?limit=20&offset=0' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | Questions were retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers. | Array | | 404 | Not found | The idea is not in the API-key workspace. | — | ### Example response ```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 /external/v1/ideas/:id/questions/:questionId/answer — Answer an idea question Operation ID: `answer-idea-question` 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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | The internal UUID or public ID (for example, IDEA-42) | | `questionId` | uuid | Yes | The question UUID returned by the list endpoint | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `answer` | string | Yes | The non-empty answer to save | ### Example request ```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"}' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Updated | The persisted question and answer were returned. | 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 response ```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 /external/v1/ideas — Create an idea Operation ID: `create-idea` 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. Required API key scopes: `ideas:write` ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | No | Title of the idea. Zentrik generates one from the description when omitted. | | `description` | string | Yes | Detailed description of the solution | | `status` | string | No | Exact workspace-configured Idea status. Omit it during an idempotent update to preserve the current status. | | `sourceKey` | string | No | Stable source namespace. Use it with externalId for idempotent create-or-update behavior. | | `externalId` | string | No | Stable record identifier within sourceKey. | | `integrationId` | uuid | No | Connected integration identifier for integration-owned records. | | `productId` | uuid | No | Workspace Product whose Feature map should be used. | | `featureIds` | uuid[] | No | Explicit same-product Feature selection. Omit for automatic matching; an empty list keeps the field unlinked. | | `insightIds` | uuid[] | No | Insights to link to the idea. | | `accountIds` | uuid[] | No | Accounts related to the Idea. Link only Accounts supported by its source or Evidence; the relationship does not claim current usage or endorsement. | | `validateInsightLinks` | boolean | No | Set true only when insightIds are an explicitly confirmed evidence path. Existing confirmed links are never demoted when omitted or false. | | `classifications` | ClassificationAssignment[] | No | 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. | ### Example request ```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" ] } ] } ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 201 | Created | The idea was successfully created. | Idea | ### Example response ```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 /external/v1/ideas/:id — Update an idea Operation ID: `update-idea` 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. Required API key scopes: `ideas:write` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | The internal UUID or public ID (for example, IDEA-42) | ### JSON request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | No | Updated name | | `description` | string | No | Updated description | | `projectId` | string \| null | No | Initiative UUID/public ID to attach this idea to, or null to detach it | | `featureIds` | uuid[] | No | Replace related Features and take manual ownership. An empty list removes them; future automatic matches do not restore them. | | `insightIds` | uuid[] | No | Replacement set of linked Insights. | | `accountIds` | uuid[] | No | Replacement set of related workspace Accounts. Use only source-supported links; a relationship does not claim current usage or endorsement. | | `validateInsightLinks` | boolean | No | Set true only to confirm the supplied insightIds as validated evidence links. | | `classifications` | ClassificationAssignment[] | No | Workspace taxonomy assignments. Use optionValues: [] or textValue: null to mark a supplied group unassigned. | ### Example request ```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"]}]}' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Updated | | 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. | — | --- ## DELETE /external/v1/ideas/:id — Delete an idea Operation ID: `delete-idea` Permanently delete an idea by its internal UUID or human-readable public ID. Required API key scopes: `ideas:delete` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | The internal UUID or public ID (for example, IDEA-42) | ### Example request ```curl curl -X DELETE https://zentrik.ai/api/external/v1/ideas/IDEA-42 \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Success | | — | --- ## DELETE /external/v1/ideas/:id/comments/:commentId — Delete an idea comment Operation ID: `delete-idea-comment` 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. Required API key scopes: `ideas:delete` ### Parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | The idea's internal UUID or public ID (for example, IDEA-42) | | `commentId` | string | Yes | The comment UUID | ### Example request ```curl curl -X DELETE https://zentrik.ai/api/external/v1/ideas/IDEA-42/comments/COMMENT_UUID \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Responses | Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 200 | Deleted | The scoped comment was deleted. The receipt does not include comment content. | IdeaCommentDeletionReceipt | | 404 | Not found | The idea is outside the API-key workspace, or the comment does not belong to that idea and workspace. | — | ### Example response ```json { "success": true, "ideaId": "uuid", "ideaPublicId": "IDEA-42", "commentId": "uuid" } ```