Initiatives

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.

6 endpoints

GET

List initiatives

GET /external/v1/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.

Requirements

API scopes required:

initiatives:read

Request

Parameters

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

Responses

200

Success

Initiatives were retrieved.

Schema

Array<Initiative>

Example Response

200 OK

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

Get one initiative

GET /external/v1/initiatives/:id

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

Requirements

API scopes required:

initiatives:read

Request

Parameters

Name	Type	Description
id *	uuid \| public id	For example INITIATIVE-42.

Responses

200

Success

The Initiative was retrieved.

Schema

Initiative

Example Response

200 OK

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

List assignable teams

GET /external/v1/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.

Requirements

API scopes required:

initiatives:read

Request

Parameters

Name	Type	Description
limit	number	1–100 results. Defaults to 20.
offset	number	Number of results to skip.

Responses

200

Success

Initiative team options were retrieved.

Schema

Array<TeamSummary>

Example Response

200 OK

json

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

PATCH

Update an initiative

PATCH /external/v1/initiatives/:id

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.

Requirements

API scopes required:

initiatives:write

Request

Parameters

Name	Type	Description
id *	uuid \| public id	For example INITIATIVE-42.

Request body (application/json)

namestring

Initiative name, 1–255 characters. It cannot be blank.

descriptionstring

Plain-text or light-Markdown description.

statusenum

PENDING, UNPLANNED, PLANNED, IN_PROGRESS, or COMPLETED.

priorityenum

URGENT, HIGH, MEDIUM, or LOW.

productIduuid | null

Workspace Product to link, or null to clear the link.

startDateYYYY-MM-DD | null

Planned start date, or null to clear it.

finishDateYYYY-MM-DD | null

Planned finish date, or null to clear it.

teamIdsuuid[]

Complete, non-empty set of unique workspace team IDs to assign.

Responses

200

Success

The stored Initiative was returned after the update.

Schema

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 Request

PATCH

/external/v1/initiatives/:id

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"]}'

Example Response

200 OK

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

Regenerate an initiative document

POST /external/v1/initiatives/:id/documents/regenerate

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.

Requirements

API scopes required:

initiatives:write

Request

Parameters

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

Request body (application/json)

typeenum

Required

One of INITIATIVE_BRIEF, PRD, or TDD.

Responses

202

Accepted

The regeneration was queued, or the active duplicate receipt was returned. Poll statusUrl until status is completed or failed.

Schema

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 Request

POST

/external/v1/initiatives/:id/documents/regenerate

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"}'

Example Response

202 Accepted

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

Get document regeneration status

GET /external/v1/initiatives/:id/documents/regenerations/:jobId

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.

Requirements

API scopes required:

initiatives:read

Request

Parameters

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

Responses

200

Success

The current regeneration state was returned.

Schema

InitiativeDocumentRegenerationReceipt

404

Not found

The Initiative and job do not form a regeneration operation in the API-key workspace.

Example Request

GET

/external/v1/initiatives/:id/documents/regenerations/:jobId

curl

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

Example Response

200 OK

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
}