---
title: "Ideas API reference"
canonical_url: https://zentrik.ai/docs/api/ideas
markdown_url: https://zentrik.ai/docs/api/ideas.md
last_reviewed: 2026-09-03
---

# 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 — 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 |
| --- | --- | --- | --- |
| `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<Idea> |

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

Required API key scopes: `ideas:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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 planning questions and current answers for an idea by internal UUID or human-readable public ID. 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<IdeaQuestion> |
| 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",
    "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 a pending planning 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 answer | The answer is empty or invalid. | — |
| 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",
  "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. |
| `insightIds` | uuid[] | No | Insights to link to the idea. |
| `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",
  "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",
  "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 |
| `insightIds` | uuid[] | No | Replacement set of linked Insights. |
| `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","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"
}
```