Ideas

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

8 endpoints

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 planning questions and current answers for an idea by internal UUID or human-readable public ID. 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",
    "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 a pending planning 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 answer

The answer is empty or invalid.

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

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

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