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

# Initiatives API reference

List and inspect Initiatives, then maintain lifecycle fields, team ownership, and generated documents. Resolve assignable team IDs only when you need to filter or replace assignments; team membership and administration remain in the Zentrik app.

- Human reference: https://zentrik.ai/docs/api/initiatives
- 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/initiatives — List initiatives

Operation ID: `list-initiatives`

List the lean Initiative catalog for customer dashboard mapping, including compact team names and IDs. Results are workspace-scoped and sorted by most recent update. Follow X-Has-More and advance offset by X-Limit to retrieve the complete catalog.

Required API key scopes: `initiatives:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | 1–100 results. Defaults to 20. |
| `offset` | number | No | Number of results to skip. |
| `status` | string | No | Exact Initiative status. |
| `productId` | uuid | No | Exact Product filter. |
| `teamId` | uuid | No | Return Initiatives assigned to this exact workspace team. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Initiatives were retrieved. | Array<Initiative> |

### Example response

```json
[
  {
    "id": "initiative-uuid",
    "publicId": "INITIATIVE-42",
    "name": "Unified scheduling",
    "description": "Make scheduling consistent across locations.",
    "status": "IN_PROGRESS",
    "priority": "HIGH",
    "workspaceId": "workspace-uuid",
    "productId": "product-uuid",
    "teams": [
      {
        "id": "team-uuid",
        "name": "Core product"
      }
    ],
    "startDate": "2026-07-01",
    "finishDate": null,
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-14T10:00:00Z"
  }
]
```

---

## GET /external/v1/initiatives/:id — Get one initiative

Operation ID: `get-initiative`

Retrieve one Initiative by internal UUID or workspace-scoped public id.

Required API key scopes: `initiatives:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | For example INITIATIVE-42. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The Initiative was retrieved. | Initiative |

### Example response

```json
{
  "id": "initiative-uuid",
  "publicId": "INITIATIVE-42",
  "name": "Unified scheduling",
  "description": "Make scheduling consistent across locations.",
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "workspaceId": "workspace-uuid",
  "productId": "product-uuid",
  "teams": [
    {
      "id": "team-uuid",
      "name": "Core product"
    }
  ],
  "startDate": "2026-07-01",
  "finishDate": null,
  "createdAt": "2026-07-01T00:00:00Z",
  "updatedAt": "2026-07-14T10:00:00Z"
}
```

---

## GET /external/v1/teams — List assignable teams

Operation ID: `list-initiative-teams`

List the compact team options that can be assigned to Initiatives in the API-key workspace. Team membership and administration stay in Zentrik; this endpoint provides stable IDs and display names for assignment workflows.

Required API key scopes: `initiatives:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | 1–100 results. Defaults to 20. |
| `offset` | number | No | Number of results to skip. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Initiative team options were retrieved. | Array<TeamSummary> |

### Example response

```json
[
  {
    "id": "team-uuid",
    "name": "Core product"
  }
]
```

---

## PATCH /external/v1/initiatives/:id — Update an initiative

Operation ID: `update-initiative`

Update the Initiative fields used to maintain its lifecycle and team ownership. Send at least one field. Omitted fields stay unchanged. Use the teams catalog to resolve IDs before replacing assignments. This route does not change participants, tags, features, or generated documents.

Required API key scopes: `initiatives:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | For example INITIATIVE-42. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Initiative name, 1–255 characters. It cannot be blank. |
| `description` | string | No | Plain-text or light-Markdown description. |
| `status` | enum | No | PENDING, UNPLANNED, PLANNED, IN_PROGRESS, or COMPLETED. |
| `priority` | enum | No | URGENT, HIGH, MEDIUM, or LOW. |
| `productId` | uuid \| null | No | Workspace Product to link, or null to clear the link. |
| `startDate` | YYYY-MM-DD \| null | No | Planned start date, or null to clear it. |
| `finishDate` | YYYY-MM-DD \| null | No | Planned finish date, or null to clear it. |
| `teamIds` | uuid[] | No | Complete, non-empty set of unique workspace team IDs to assign. |

### Example request

```curl
curl -X PATCH https://zentrik.ai/api/external/v1/initiatives/INITIATIVE-42 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Make insights trustworthy and useful","status":"IN_PROGRESS","priority":"HIGH","teamIds":["team-uuid"]}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The stored Initiative was returned after the update. | Initiative |
| 400 | Invalid request | The body is empty or not an object, includes an unsupported field, contains an invalid lifecycle value or date, supplies invalid team assignments, or links a Product that conflicts with existing Product features. | — |
| 404 | Not found | The Initiative or Product is outside the API-key workspace or does not exist. | — |

### Example response

```json
{
  "id": "initiative-uuid",
  "publicId": "INITIATIVE-42",
  "name": "Make insights trustworthy and useful",
  "description": "Make scheduling consistent across locations.",
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "workspaceId": "workspace-uuid",
  "productId": "product-uuid",
  "teams": [
    {
      "id": "team-uuid",
      "name": "Core product"
    }
  ],
  "startDate": "2026-07-01",
  "finishDate": null,
  "createdAt": "2026-07-01T00:00:00Z",
  "updatedAt": "2026-07-14T10:00:00Z"
}
```

---

## POST /external/v1/initiatives/:id/documents/regenerate — Regenerate an initiative document

Operation ID: `regenerate-initiative-document`

Queue a source-grounded rebuild of an existing Initiative Brief, PRD, or TDD from the Initiative’s current state and question answers. The generated document is replaced in place. A duplicate request for the same active document returns the existing job receipt instead of creating another job; this is different from directly overwriting document HTML.

Required API key scopes: `initiatives:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | The Initiative reference, for example INITIATIVE-42. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | enum | Yes | One of INITIATIVE_BRIEF, PRD, or TDD. |

### Example request

```curl
curl -X POST https://zentrik.ai/api/external/v1/initiatives/INITIATIVE-42/documents/regenerate \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type":"PRD"}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 202 | Accepted | The regeneration was queued, or the active duplicate receipt was returned. Poll statusUrl until status is completed or failed. | InitiativeDocumentRegenerationReceipt |
| 400 | Invalid document type | Only generated Initiative Brief, PRD, and TDD documents can be regenerated. | — |
| 404 | Not found | The Initiative or requested generated document is outside the workspace or does not exist. | — |
| 409 | Generation already active | Another generation job is already active for this Initiative and document type. | — |

### Example response

```json
{
  "operation": "initiative_document_regeneration",
  "jobId": "job-uuid",
  "jobType": "generate-prd",
  "status": "pending",
  "queued": true,
  "deduplicated": false,
  "initiativeId": "initiative-uuid",
  "initiativePublicId": "INITIATIVE-42",
  "documentId": "document-uuid",
  "documentType": "PRD",
  "createdAt": "2026-08-05T10:00:00.000Z",
  "updatedAt": "2026-08-05T10:00:00.000Z",
  "failure": null,
  "statusUrl": "/api/external/v1/initiatives/INITIATIVE-42/documents/regenerations/job-uuid"
}
```

---

## GET /external/v1/initiatives/:id/documents/regenerations/:jobId — Get document regeneration status

Operation ID: `get-initiative-document-regeneration`

Inspect a document regeneration receipt by job ID. Poll this endpoint until status is completed or failed. Failure details include a safe message and whether the operation is known to be retryable.

Required API key scopes: `initiatives:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | The same Initiative reference used to start regeneration. |
| `jobId` | uuid | Yes | The job ID returned by the regenerate endpoint. |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/initiatives/INITIATIVE-42/documents/regenerations/job-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The current regeneration state was returned. | InitiativeDocumentRegenerationReceipt |
| 404 | Not found | The Initiative and job do not form a regeneration operation in the API-key workspace. | — |

### Example response

```json
{
  "operation": "initiative_document_regeneration",
  "jobId": "job-uuid",
  "jobType": "generate-prd",
  "status": "completed",
  "queued": false,
  "deduplicated": false,
  "initiativeId": "initiative-uuid",
  "initiativePublicId": "INITIATIVE-42",
  "documentId": "document-uuid",
  "documentType": "PRD",
  "createdAt": "2026-08-05T10:00:00.000Z",
  "updatedAt": "2026-08-05T10:02:00.000Z",
  "failure": null
}
```