Ideas

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

10 endpoints

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

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
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.

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

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.
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	Summary of the saved workspace taxonomy classifications returned after a classification write.
classifications	ClassificationValue[]	Persisted classification values returned after create or update receives classifications.
createdAt	iso-date	Creation timestamp.
updatedAt	iso-date	Last update timestamp.