External REST API

Read and write the same products, accounts, insights, signals, opportunities, ideas, OKRs, context units, and context documents you manage in the app over HTTPS with workspace API keys. Vendor connections (Zoom, Jira, Google Drive, and others) are covered in the integration guides; this reference is for HTTP paths, methods, and payloads.

Secure

Keys and scopes are managed in workspace Settings; revoke anytime.

Fast

JSON over HTTPS for automation and dashboards.

RESTful

Conventional resources and verbs so clients stay predictable.

Authentication

All API requests must include an Authorization header with your API key as a bearer token. You can manage your API keys in the Settings > API Keys section of your Zentrik workspace.

Zentrik workspace Settings showing the API keys area before any keys exist. — Create and manage keys from Settings → API keys in your workspace.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://zentrik.ai/api/external/v1/insights

Modal for creating an API key with scope checkboxes. — Each key can be limited to the API scopes your automation needs.

Keep your API keys secret. Do not share them or commit them to public repositories. If a key is compromised, revoke it immediately in the dashboard.

Signals

Signals are the imported transcripts, tickets, reviews, and reports that feed Discovery. Use these endpoints when you want to bring evidence into Zentrik from another source.

Operations

GET/external/v1/signals

signals:read

GET/external/v1/signals/:publicId

signals:read

POST/external/v1/signals

signals:write

PATCH/external/v1/signals/:publicId

signals:write

DELETE/external/v1/signals/:publicId

signals:delete

POST/external/v1/signals/:publicId/process

signals:write

GET

List signals

List a bounded page of signals in your workspace. Signals are imported pieces of customer or market evidence such as transcripts, support tickets, reviews, and discovery reports.

Requirements

API scopes required:

signals: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)

Responses

200

Success

Signals were successfully retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers.

Schema

Array<Signal>

Example Request

GET

/external/v1/signals

curl

curl -X GET https://zentrik.ai/api/external/v1/signals?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "uuid",
    "name": "Support Ticket - 3/20/24, 10:00 AM",
    "publicId": "SIGNAL-42",
    "workspaceId": "workspace-uuid",
    "status": "processed",
    "context": "support_request",
    "signalType": null,
    "processorType": "zendesk",
    "providerType": "zendesk",
    "evidenceKind": "support_ticket",
    "analysisProfile": "support_ticket",
    "provenance": {
      "providerType": "zendesk",
      "evidenceKind": "support_ticket",
      "analysisProfile": "support_ticket"
    },
    "sourceFacet": "zendesk:support_ticket",
    "sourceLabel": "Zendesk support ticket",
    "sourceLinks": [
      {
        "name": "Open Zendesk ticket",
        "url": "https://example.zendesk.com/agent/tickets/12345",
        "type": "support_ticket",
        "primary": true
      }
    ],
    "source": {
      "type": "zendesk",
      "external_data": {
        "ticketId": "12345"
      }
    },
    "data": {
      "subject": "Users cannot reset password",
      "severity": "high"
    },
    "insightIds": [],
    "accountIds": [],
    "accountId": null,
    "accountExternalId": null,
    "externalId": "external-123",
    "createdAt": "2024-03-20T10:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z"
  }
]

GET

Get one signal

Retrieve a single signal by its public ID.

Requirements

API scopes required:

signals:read

Request

Parameters

Name	Type	Description
publicId *	string	Workspace-scoped public ID, such as SIGNAL-42

Responses

200

Success

The signal was successfully retrieved.

Schema

Signal

404

Not Found

No signal found with the provided ID.

Example Request

GET

/external/v1/signals/:publicId

curl

curl -X GET https://zentrik.ai/api/external/v1/signals/SIGNAL-42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "Support Ticket - 3/20/24, 10:00 AM",
  "publicId": "SIGNAL-42",
  "workspaceId": "workspace-uuid",
  "status": "processed",
  "context": "support_request",
  "signalType": null,
  "processorType": "zendesk",
  "providerType": "zendesk",
  "evidenceKind": "support_ticket",
  "analysisProfile": "support_ticket",
  "provenance": {
    "providerType": "zendesk",
    "evidenceKind": "support_ticket",
    "analysisProfile": "support_ticket"
  },
  "sourceFacet": "zendesk:support_ticket",
  "sourceLabel": "Zendesk support ticket",
  "sourceLinks": [
    {
      "name": "Open Zendesk ticket",
      "url": "https://example.zendesk.com/agent/tickets/12345",
      "type": "support_ticket",
      "primary": true
    }
  ],
  "source": {
    "type": "zendesk",
    "external_data": {
      "ticketId": "12345"
    }
  },
  "data": {
    "sessionId": "session-123"
  },
  "insightIds": [
    "insight-uuid"
  ],
  "accountIds": [],
  "accountId": null,
  "accountExternalId": null,
  "externalId": "external-123",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}

POST

Create a signal

Create a new signal by sending the text you want Zentrik to analyze. This is the recommended public API flow for transcripts, support tickets, reviews, structured feedback records, and discovery reports. Advanced raw signal bodies are also accepted on this same endpoint and are auto-queued.

Requirements

API scopes required:

signals:write

Request

Request body (application/json)

namestring

Optional display name for the signal. When omitted for typed text signals, Zentrik generates one from the signal type and timestamp.

textstring

Required

The raw transcript, support ticket, review, structured feedback record, or discovery report text that Zentrik should process into insights.

signalType'transcript' | 'support_ticket' | 'review' | 'feedback_record' | 'discovery_report'

Required

What kind of text you are sending. This determines how Zentrik processes the signal. New text signals are automatically queued for processing after creation.

providerTypestring

Optional source system or importer identifier, such as g2, app_store, reddit, gartner, manual_csv, or external_api.

evidenceKindstring

Optional evidence shape override. For typed text this defaults from signalType and usually does not need to be sent.

analysisProfile'default_transcript' | 'support_ticket' | 'survey_response' | 'discovery_report'

Optional processing profile override. For typed text this defaults from signalType.

additionalContextstring

Optional notes to help Zentrik interpret the text correctly. Use this for things like where the text came from, what batch it belongs to, or any lightweight analyst note. This is treated as supplemental context, not an instruction override.

occurredAtiso-date

Optional timestamp representing when the original signal happened. When provided, it is used as the signal creation timestamp for trend accuracy.

productIdsuuid[]

Optional list of products to narrow the product context used during processing.

accountIduuid

Optional account to associate with this signal and the insights created from typed text processing.

accountIdsuuid[]

Optional list of account IDs to associate directly with this signal. Use accountId for the common single-account case.

accountExternalIdstring

Optional stable client-side account identifier, such as crm-example-account. Prefer this for CRM automations that should not persist backend UUIDs.

externalIdstring

Stable record identifier from the source system. Use this for recurring imports so retries can deduplicate and reconcile back to the original record.

sourceLinks{ name?: string; url: string; type?: string; primary?: boolean }[]

Links users should land on from Zentrik, such as the original app store review, G2 review, Reddit thread or comment, Gartner report, support ticket, source row, or meeting link. HTTP and HTTPS URLs are normalized and returned on the Signal object.

sourceExternalDataobject

Provider-specific metadata to keep with the signal, such as reviewId, rating, locale, reportId, threadId, productSlug, or dataset. Zentrik stores this under source.external_data.

Responses

201

Created

The signal was successfully created and queued for asynchronous processing. Create responses include a queued job id.

Schema

Signal

Example Request

POST

/external/v1/signals

json

{
  "name": "G2 Reviews - March Batch",
  "text": "Users love the product overall, but several reviewers mention that exports are hard to find and slow to complete for large datasets.",
  "signalType": "review",
  "providerType": "g2",
  "externalId": "g2-review:review-row-1",
  "additionalContext": "Public review batch collected from G2 and Capterra.",
  "occurredAt": "2025-03-11T14:30:00Z",
  "productIds": [
    "product-uuid-1"
  ],
  "accountExternalId": "crm-example-account",
  "sourceExternalData": {
    "reviewId": "review-row-1",
    "rating": 3,
    "productSlug": "example-product"
  },
  "sourceLinks": [
    {
      "name": "Open G2 review",
      "url": "https://www.g2.com/products/example-product/reviews/review-row-1",
      "type": "review",
      "primary": true
    }
  ]
}

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "Review - 3/11/25, 2:30 PM",
  "publicId": "SIGNAL-43",
  "workspaceId": "workspace-uuid",
  "status": "processing",
  "context": null,
  "signalType": "review",
  "processorType": "manual-text",
  "providerType": "g2",
  "evidenceKind": "review",
  "analysisProfile": "survey_response",
  "provenance": {
    "providerType": "g2",
    "evidenceKind": "review",
    "analysisProfile": "survey_response"
  },
  "sourceFacet": "g2:review",
  "sourceLabel": "G2 Review",
  "sourceLinks": [
    {
      "name": "Open G2 review",
      "url": "https://www.g2.com/products/example-product/reviews/review-row-1",
      "type": "review",
      "primary": true
    }
  ],
  "source": {
    "type": "manual-text",
    "external_data": {
      "reviewId": "review-row-1",
      "rating": 3,
      "productSlug": "example-product",
      "links": [
        {
          "name": "Open G2 review",
          "url": "https://www.g2.com/products/example-product/reviews/review-row-1",
          "type": "review",
          "primary": true
        }
      ]
    }
  },
  "data": {
    "s3Key": "signals/manual-text/workspace-uuid/uuid.txt",
    "productIds": [
      "product-uuid-1"
    ],
    "accountId": "account-uuid-1",
    "accountExternalId": "crm-example-account",
    "additionalContext": "Public review batch collected from G2 and Capterra.",
    "uploadedAt": "2025-03-21T10:00:00Z"
  },
  "insightIds": [],
  "accountId": "account-uuid-1",
  "accountExternalId": "crm-example-account",
  "externalId": "g2-review:review-row-1",
  "createdAt": "2025-03-11T14:30:00Z",
  "updatedAt": "2025-03-21T10:00:00Z",
  "jobId": "job-123",
  "processing": {
    "lastJobId": "job-123",
    "startedAt": "2025-03-21T10:00:00Z",
    "processedAt": null,
    "failedAt": null,
    "lastError": null
  }
}

PATCH

Update a signal

Update fields of an existing signal, such as metadata or linked insights.

Requirements

API scopes required:

signals:write

Request

Parameters

Name	Type	Description
publicId *	string	Workspace-scoped public ID, such as SIGNAL-43

Request body (application/json)

sourceobject

Updated source descriptor for the signal.

dataobject

Updated arbitrary context payload.

insightIdsstring[]

Replace the list of linked insight IDs.

externalIdstring

Updated external record identifier.

status'pending' | 'processed'

Processing status for the signal.

contextstring

Persisted signal context, such as user_interview or support_request.

Responses

200

Updated

The signal was successfully updated.

Schema

Signal

Example Request

PATCH

/external/v1/signals/:publicId

curl

curl -X PATCH https://zentrik.ai/api/external/v1/signals/SIGNAL-43 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"insightIds": ["insight-uuid"]}'

DELETE

Delete a signal

Permanently delete a signal from the workspace.

Requirements

API scopes required:

signals:delete

Request

Parameters

Name	Type	Description
publicId *	string	Workspace-scoped public ID, such as SIGNAL-43

Responses

200

Success

The signal was successfully deleted.

Schema

{ message: string }

Example Request

DELETE

/external/v1/signals/:publicId

curl

curl -X DELETE https://zentrik.ai/api/external/v1/signals/SIGNAL-43 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "message": "Deleted"
}

POST

Process a signal

Queue signal processing for an existing signal. Use this for explicit re-runs or manual retries.

Requirements

API scopes required:

signals:write

Request

Parameters

Name	Type	Description
publicId *	string	Workspace-scoped public ID, such as SIGNAL-43.

Responses

201

Queued

The signal was queued for asynchronous processing.

Schema

{ jobId: string }

Example Request

POST

/external/v1/signals/:publicId/process

curl

curl -X POST https://zentrik.ai/api/external/v1/signals/SIGNAL-43/process \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "jobId": "job-456"
}

Creation Modes

The recommended public API flow is typed text ingestion. Sendtext andsignalTypeto create a manual signal that is automatically queued for AI processing into insights.

Supported signal types: transcript, support_ticket, review, feedback_record, discovery_report

Canonical provenance: processorType controls routing, providerType identifies the source system, evidenceKind describes the evidence shape, and analysisProfile selects the extraction behavior.

Source links: send sourceLinks with final URLs for the original review, thread, report, ticket, source row, or meeting so Zentrik can render direct evidence actions in Discovery.

Profile mapping: transcript → transcript analysis, support_ticket → ticket analysis, review and feedback_record → feedback/review analysis, discovery_report → synthesized discovery-report analysis

Async behavior: create returns a processing signal plus a jobId

Inferred context: you do not need to send a context label. Zentrik infers the best matching interaction context during processing.

Advanced/raw ingestion: the same create endpoint also supports lower-level fields such as processorType, providerType, evidenceKind, source, and data.

Those fields are intentionally omitted from the primary docs here because most public API users only need the typed text flow.

Data Models

Signals are intentionally flexible. The core fields help you track provenance while thesource anddata payloads carry your custom structure.

Signal Object

Field	Type	Description
id	uuid	The unique identifier for the signal.
name	string	Display name for the signal. For typed text signals, Zentrik can generate this automatically from the signal type and timestamp.
publicId	string	Workspace-scoped, human-readable identifier in the form "SIGNAL-123". Useful for referencing signals in UI and exports.
workspaceId	uuid	ID of the workspace this signal belongs to.
status	'pending' \| 'processing' \| 'processed' \| 'failed'	Processing status of the signal. Create responses that queue work now typically return processing immediately, then later settle to processed or failed.
signalType	'transcript' \| 'support_ticket' \| 'review' \| 'feedback_record' \| 'discovery_report' \| null	Present for manual text signals. Indicates which typed ingestion flow created the signal.
processorType	string	Canonical operational processor route, such as manual-text, manual-transcript, gong, or zendesk.
providerType	string	Canonical source system or importer, such as external_api, manual, gong, zendesk, gmail_mailbox, or g2.
evidenceKind	string	Canonical evidence shape, such as transcript, support_ticket, review, feedback_record, discovery_report, or email_thread.
analysisProfile	'default_transcript' \| 'support_ticket' \| 'survey_response' \| 'discovery_report'	Canonical prompt/extraction profile used by processing.
provenance	{ providerType: string; evidenceKind: string; analysisProfile: string }	Canonical signal provenance grouped for clients that do not need operational processor routing.
sourceFacet	string	Derived filter/grouping key in the form providerType:evidenceKind.
sourceLabel	string	Derived display label for the source facet.
sourceLinks	{ name: string; url: string; type: string; primary?: boolean }[]	Normalized source links users can open from Discovery to inspect the original evidence. These are derived from sourceLinks on create and legacy URL fields stored in source.external_data, data, or import metadata.
context	string \| null	Normalized interaction context inferred or stored for the signal, such as user_interview, feature_feedback, or support_request. Most clients do not need to send this on create.
source	{ type: string; external_data?: object }	Provider-specific source payload. Canonical provenance lives in processorType, providerType, evidenceKind, and analysisProfile.
data	object \| null	Stored metadata for the signal. For typed text signals this includes the S3 key plus optional product, account, and notes metadata. Most clients do not need to write this directly.
insightIds	uuid[]	List of insight IDs that have been linked to this signal.
accountIds	uuid[]	List of account IDs linked directly to this signal.
accountId	uuid \| null	Legacy single-account field. When multiple accounts are linked, this returns the first linked account ID.
accountExternalId	string \| null	Client-provided external account identifier when the signal was created with accountExternalId.
externalId	string \| null	Identifier of the record in the external system (for example, a ticket or event identifier).
createdAt	iso-date	Timestamp when the signal was first created.
updatedAt	iso-date	Timestamp of the last modification.
jobId	string \| undefined	Returned on create/process responses when an asynchronous processing job has been queued.
processing	{ lastJobId?: string \| null; startedAt?: string \| null; processedAt?: string \| null; failedAt?: string \| null; lastError?: string \| null } \| null	Operational processing metadata. Use this to debug queue progress and retries before assuming a signal is stuck.

Accounts

Manage workspace accounts over the External API so CRM automations can look up, create, and update the company records that signals and insights should attach to.

Operations

GET/external/v1/accounts

accounts:read

GET/external/v1/accounts/:id

accounts:read

POST/external/v1/accounts

accounts:write

PATCH/external/v1/accounts/:id

accounts:write

DELETE/external/v1/accounts/:id

accounts:delete

GET/external/v1/accounts/:id/contacts

accounts:read

POST/external/v1/accounts/:id/contacts

accounts:write

PATCH/external/v1/accounts/:id/contacts/:contactId

accounts:write

DELETE/external/v1/accounts/:id/contacts/:contactId

accounts:write

GET

List all accounts

List accounts in the current workspace. This is the main lookup endpoint for CRM automation before transcript ingestion.

Requirements

API scopes required:

accounts:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of accounts to return.
offset	number	Number of accounts to skip.
q	string	Case-insensitive search across name, domain, website, and externalId.
name	string	Exact account name match (case-insensitive).
domain	string	Exact domain or website match (case-insensitive).
externalId	string	Stable client-side identifier such as crm-example-account.

Responses

200

Success

Accounts were successfully retrieved.

Schema

Array<Account>

Example Request

GET

/external/v1/accounts

curl

curl -X GET 'https://zentrik.ai/api/external/v1/accounts?externalId=crm-example-account' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "account-uuid",
    "name": "Example Account",
    "domain": "example.com",
    "website": "https://example.com",
    "lifecycleStage": "TRIAL",
    "externalId": "crm-example-account",
    "workspaceId": "workspace-uuid",
    "contactIds": [
      "contact-1"
    ],
    "insightIds": [
      "insight-1"
    ],
    "opportunityIds": [
      "opportunity-1"
    ],
    "ideaIds": [
      "idea-1"
    ],
    "createdAt": "2026-04-09T10:00:00Z",
    "updatedAt": "2026-04-09T10:00:00Z"
  }
]

GET

Get one account

Retrieve one account from the current workspace.

Requirements

API scopes required:

accounts:read

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.

Responses

200

Success

The account was successfully retrieved.

Schema

Account

404

Not Found

No account found with the provided id.

Example Request

GET

/external/v1/accounts/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/accounts/account-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "account-uuid",
  "name": "Example Account",
  "domain": "example.com",
  "website": "https://example.com",
  "lifecycleStage": "TRIAL",
  "externalId": "crm-example-account",
  "workspaceId": "workspace-uuid",
  "contactIds": [
    "contact-1"
  ],
  "insightIds": [
    "insight-1"
  ],
  "opportunityIds": [
    "opportunity-1"
  ],
  "ideaIds": [
    "idea-1"
  ],
  "createdAt": "2026-04-09T10:00:00Z",
  "updatedAt": "2026-04-09T10:00:00Z"
}

POST

Create an account

Create an account in the current workspace. CRM agents typically use `externalId` as the durable bridge between local records and Zentrik accounts. Manage contacts with the account contacts endpoints after the account exists.

Requirements

API scopes required:

accounts:write

Request

Request body (application/json)

namestring

Required

Account display name.

externalIdstring

Stable client-side identifier such as crm-example-account.

domainstring

Primary company domain.

websitestring

Canonical website URL.

industrystring

Industry or vertical label.

companySizestring

Company size bucket.

lifecycleStagestring

Canonical Zentrik lifecycle stage: LEAD, TRIAL, ACTIVE, CHURNED, or PARTNER.

notesstring

Supplemental operator or CRM notes.

Responses

201

Created

The account was successfully created.

Schema

Account

Example Request

POST

/external/v1/accounts

json

{
  "name": "Example Account",
  "externalId": "crm-example-account",
  "domain": "example.com",
  "website": "https://example.com",
  "industry": "B2B software",
  "companySize": "11-50",
  "lifecycleStage": "TRIAL",
  "notes": "Primary contact evaluates roadmap fit."
}

Example Response

200 OK

json

{
  "id": "account-uuid",
  "name": "Example Account",
  "externalId": "crm-example-account",
  "domain": "example.com",
  "website": "https://example.com",
  "industry": "B2B software",
  "companySize": "11-50",
  "lifecycleStage": "TRIAL",
  "workspaceId": "workspace-uuid",
  "contactIds": [],
  "insightIds": [],
  "opportunityIds": [],
  "ideaIds": [],
  "createdAt": "2026-04-09T10:00:00Z",
  "updatedAt": "2026-04-09T10:00:00Z"
}

PATCH

Update an account

Update an existing account in the current workspace. Contact arrays are not accepted here; use the dedicated contact endpoints for people and roles.

Requirements

API scopes required:

accounts:write

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.

Request body (application/json)

namestring

Updated display name.

externalIdstring

Updated stable client-side identifier.

domainstring

Updated primary company domain.

websitestring

Updated canonical website URL.

industrystring

Updated industry or vertical label.

companySizestring

Updated company size bucket.

lifecycleStagestring

Updated canonical Zentrik lifecycle stage.

notesstring

Updated operator or CRM notes.

Responses

200

Updated

The account was successfully updated.

Schema

Account

Example Request

PATCH

/external/v1/accounts/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/accounts/account-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"lifecycleStage":"ACTIVE"}'

DELETE

Delete an account

Delete an account from the current workspace.

Requirements

API scopes required:

accounts:delete

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.

Responses

200

Deleted

The account was successfully deleted.

Example Request

DELETE

/external/v1/accounts/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/accounts/account-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET

List account contacts

List contacts linked to an account in the current workspace. Use this before contact sync automation rather than relying on account `contactIds` alone.

Requirements

API scopes required:

accounts:read

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.

Responses

200

Success

Contacts were successfully retrieved.

Schema

Array<Contact>

404

Not Found

No account found with the provided id in the current workspace.

Example Request

GET

/external/v1/accounts/:id/contacts

curl

curl -X GET https://zentrik.ai/api/external/v1/accounts/account-uuid/contacts \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "contact-uuid",
    "accountId": "account-uuid",
    "name": "Primary product contact",
    "role": "VP Product",
    "email": "product-contact@example.com",
    "phone": null,
    "notes": "Primary product evaluator and champion.",
    "isPrimary": true,
    "createdAt": "2026-04-09T10:00:00Z",
    "updatedAt": "2026-04-09T10:00:00Z"
  }
]

POST

Create an account contact

Create one contact on an account. This is the preferred way to add contacts; do not patch the account `contacts` array for incremental updates.

Requirements

API scopes required:

accounts:write

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.

Request body (application/json)

namestring

Required

Contact display name.

rolestring

Role, title, or account-specific responsibility.

emailstring

Email address.

phonestring

Phone number.

notesstring

Operator notes such as influence, interests, and outreach guidance.

isPrimaryboolean

Whether this is the primary contact for the account.

Responses

201

Created

The contact was successfully created.

Schema

Contact

404

Not Found

No account found with the provided id in the current workspace.

Example Request

POST

/external/v1/accounts/:id/contacts

json

{
  "name": "Primary product contact",
  "role": "VP Product",
  "email": "product-contact@example.com",
  "notes": "Primary product evaluator and champion.",
  "isPrimary": true
}

Example Response

200 OK

json

{
  "id": "contact-uuid",
  "accountId": "account-uuid",
  "name": "Primary product contact",
  "role": "VP Product",
  "email": "product-contact@example.com",
  "notes": "Primary product evaluator and champion.",
  "isPrimary": true,
  "createdAt": "2026-04-09T10:00:00Z",
  "updatedAt": "2026-04-09T10:00:00Z"
}

PATCH

Update an account contact

Update one contact on an account. The contact must belong to the requested account in the current workspace.

Requirements

API scopes required:

accounts:write

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.
contactId *	uuid	The backend contact UUID.

Request body (application/json)

namestring

Updated contact display name.

rolestring

Updated role, title, or account-specific responsibility.

emailstring

Updated email address.

phonestring

Updated phone number.

notesstring

Updated operator notes.

isPrimaryboolean

Updated primary-contact flag.

Responses

200

Updated

The contact was successfully updated.

Schema

Contact

404

Not Found

No account/contact pair found in the current workspace.

Example Request

PATCH

/external/v1/accounts/:id/contacts/:contactId

curl

curl -X PATCH https://zentrik.ai/api/external/v1/accounts/account-uuid/contacts/contact-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"notes":"Strategic evaluator. Reach out for roadmap and pricing context."}'

DELETE

Delete an account contact

Delete one contact from an account. This requires `accounts:write` so clients can manage contacts without receiving account-delete permission.

Requirements

API scopes required:

accounts:write

Request

Parameters

Name	Type	Description
id *	uuid	The backend account UUID.
contactId *	uuid	The backend contact UUID.

Responses

200

Deleted

The contact was successfully deleted.

404

Not Found

No account/contact pair found in the current workspace.

Example Request

DELETE

/external/v1/accounts/:id/contacts/:contactId

curl

curl -X DELETE https://zentrik.ai/api/external/v1/accounts/account-uuid/contacts/contact-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Products

Create and manage workspace products, their stable external sync identifiers, feature maps, personas, clarification questions, and portfolio metrics.

Operations

GET/external/v1/products

products:read

GET/external/v1/products/:id

products:read

POST/external/v1/products

products:write

PATCH/external/v1/products/:id

products:write

DELETE/external/v1/products/:id

products:delete

GET/external/v1/products/portfolio-summary

products:read

GET/external/v1/products/:id/metrics

products:read

GET/external/v1/products/:id/features

products:read

POST/external/v1/products/:id/features

products:write

PATCH/external/v1/products/:id/features/:featureId

products:write

DELETE/external/v1/products/:id/features/:featureId

products:write

GET/external/v1/products/:id/personas

products:read

POST/external/v1/products/:id/personas

products:write

PATCH/external/v1/products/:id/personas/:personaId

products:write

DELETE/external/v1/products/:id/personas/:personaId

products:write

GET/external/v1/products/:id/questions

products:read

GET/external/v1/products/:id/questions/:questionId

products:read

GET

List all products

List products in the current workspace. Use `externalId` for deterministic syncs from external systems.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of products to return.
offset	number	Number of products to skip.
q	string	Case-insensitive search across name, description, type, and externalId.
name	string	Exact product name match.
externalId	string	Exact client-side sync identifier.
include	string	Comma-separated: features, personas, questions, metrics.

Responses

200

Success

Products were successfully retrieved.

Schema

Array<Product>

Example Request

GET

/external/v1/products

curl

curl -X GET 'https://zentrik.ai/api/external/v1/products?externalId=prd-discovery&include=metrics' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "product-uuid",
    "name": "Zentrik Discovery",
    "description": "AI-assisted discovery workspace for product teams.",
    "descriptionAnalysis": null,
    "type": "SaaS",
    "stack": "NestJS, React, PostgreSQL",
    "mission": "Preserve customer intent from signal to roadmap.",
    "externalId": "prd-discovery",
    "workspaceId": "workspace-uuid",
    "kpis": [
      "Reduce insight review time",
      "Increase evidence coverage"
    ],
    "techStack": [
      {
        "name": "PostgreSQL",
        "roles": [
          "Backend Engineer"
        ]
      }
    ],
    "analysis": {},
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z",
    "metrics": {
      "insights": 12,
      "ideas": 5,
      "opportunities": 3,
      "signals": 21
    }
  }
]

GET

Get one product

Retrieve one product by Zentrik UUID. Add `include` to hydrate context collections.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
include	string	Comma-separated: features, personas, questions, metrics.

Responses

200

Success

The product was successfully retrieved.

Schema

Product

404

Not Found

No product found with the provided id in the current workspace.

Example Request

GET

/external/v1/products/:id

curl

curl -X GET 'https://zentrik.ai/api/external/v1/products/product-uuid?include=features,personas' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "product-uuid",
  "name": "Zentrik Discovery",
  "description": "AI-assisted discovery workspace for product teams.",
  "descriptionAnalysis": null,
  "type": "SaaS",
  "stack": "NestJS, React, PostgreSQL",
  "mission": "Preserve customer intent from signal to roadmap.",
  "externalId": "prd-discovery",
  "workspaceId": "workspace-uuid",
  "kpis": [
    "Reduce insight review time",
    "Increase evidence coverage"
  ],
  "techStack": [
    {
      "name": "PostgreSQL",
      "roles": [
        "Backend Engineer"
      ]
    }
  ],
  "analysis": {},
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z",
  "features": [
    {
      "id": "feature-uuid",
      "productId": "product-uuid",
      "name": "Signal intake",
      "description": "Bring customer evidence into Discovery.",
      "parentId": null
    }
  ],
  "personas": [
    {
      "id": "persona-uuid",
      "productId": "product-uuid",
      "name": "Product Manager",
      "description": "Owns discovery synthesis.",
      "goals": [],
      "painPoints": [],
      "useCases": []
    }
  ]
}

POST

Create a product

Create a product. `externalId` is optional but recommended for idempotent external syncs. Initial features and personas may be provided on create only.

Requirements

API scopes required:

products:write

Request

Request body (application/json)

namestring

Required

Product display name.

descriptionstring

Required

Product description.

externalIdstring

Stable client-side identifier, unique per workspace when present.

typestring

Product category.

stackstring

Short implementation stack summary.

missionstring

Outcome or mission statement.

kpisstring[]

Outcome measures tracked for this product.

techStackarray

Structured technologies and roles.

featuresarray

Initial feature records.

personasarray

Initial persona records.

Responses

201

Created

The product was successfully created.

Schema

Product

409

Conflict

The externalId already exists in this workspace.

Example Request

POST

/external/v1/products

json

{
  "name": "Zentrik Discovery",
  "description": "AI-assisted discovery workspace for product teams.",
  "externalId": "prd-discovery",
  "mission": "Preserve customer intent from signal to roadmap.",
  "features": [
    {
      "name": "Signal intake",
      "description": "Bring customer evidence into Discovery."
    }
  ],
  "personas": [
    {
      "name": "Product Manager",
      "description": "Owns discovery synthesis."
    }
  ]
}

Example Response

200 OK

json

{
  "id": "product-uuid",
  "name": "Zentrik Discovery",
  "description": "AI-assisted discovery workspace for product teams.",
  "descriptionAnalysis": null,
  "type": "SaaS",
  "stack": "NestJS, React, PostgreSQL",
  "mission": "Preserve customer intent from signal to roadmap.",
  "externalId": "prd-discovery",
  "workspaceId": "workspace-uuid",
  "kpis": [
    "Reduce insight review time",
    "Increase evidence coverage"
  ],
  "techStack": [
    {
      "name": "PostgreSQL",
      "roles": [
        "Backend Engineer"
      ]
    }
  ],
  "analysis": {},
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

PATCH

Update a product

Update core product fields. Nested features, personas, and questions are rejected here; use the dedicated subresource endpoints.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Request body (application/json)

namestring

Updated product name.

descriptionstring

Updated product description.

externalIdstring | null

Update or clear the external sync identifier.

missionstring | null

Updated mission statement.

kpisstring[] | null

Replace product KPIs.

Responses

200

Updated

The product was successfully updated.

Schema

Product

Example Request

PATCH

/external/v1/products/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/products/product-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"prd-discovery-v2"}'

DELETE

Delete a product

Delete a product from the current workspace.

Requirements

API scopes required:

products:delete

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Responses

200

Deleted

The product was successfully deleted.

Example Request

DELETE

/external/v1/products/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/products/product-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET

Get portfolio summary

Return products plus aggregate counts used by portfolio views.

Requirements

API scopes required:

products:read

Responses

200

Success

Portfolio summary was successfully retrieved.

Example Request

GET

/external/v1/products/portfolio-summary

curl

curl -X GET https://zentrik.ai/api/external/v1/products/portfolio-summary \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "products": [
    {
      "id": "product-uuid",
      "name": "Zentrik Discovery",
      "description": "AI-assisted discovery workspace for product teams.",
      "descriptionAnalysis": null,
      "type": "SaaS",
      "stack": "NestJS, React, PostgreSQL",
      "mission": "Preserve customer intent from signal to roadmap.",
      "externalId": "prd-discovery",
      "workspaceId": "workspace-uuid",
      "kpis": [
        "Reduce insight review time",
        "Increase evidence coverage"
      ],
      "techStack": [
        {
          "name": "PostgreSQL",
          "roles": [
            "Backend Engineer"
          ]
        }
      ],
      "analysis": {},
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ],
  "metrics": {
    "product-uuid": {
      "insights": 12,
      "ideas": 5,
      "opportunities": 3,
      "signals": 21
    }
  },
  "meta": {
    "signalsLookbackDays": 7
  }
}

GET

Get product metrics

Return aggregate metrics for a single product.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Responses

200

Success

Product metrics were successfully retrieved.

Example Request

GET

/external/v1/products/:id/metrics

curl

curl -X GET https://zentrik.ai/api/external/v1/products/product-uuid/metrics \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "contextPersonas": 2,
  "contextFeatureMapNodes": 8,
  "initiativesTotal": 3,
  "insights": 12,
  "signals": 21,
  "opportunities": 3,
  "ideas": 5
}

GET

List product features

List feature map nodes for a product.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Responses

200

Success

Features were successfully retrieved.

Schema

Array<ProductFeature>

Example Response

200 OK

json

[
  {
    "id": "feature-uuid",
    "productId": "product-uuid",
    "name": "Signal intake",
    "description": "Bring customer evidence into Discovery.",
    "parentId": null
  }
]

POST

Create a product feature

Create one product feature. `parentId` may reference an existing feature in the same product.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Request body (application/json)

namestring

Required

Feature name.

descriptionstring

Required

Feature description.

parentIduuid | null

Optional parent feature.

Responses

201

Created

The feature was successfully created.

Schema

ProductFeature

Example Request

POST

/external/v1/products/:id/features

json

{
  "name": "Signal intake",
  "description": "Bring customer evidence into Discovery."
}

PATCH

Update a product feature

Update one product feature. The feature must belong to the requested product.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
featureId *	uuid	The feature UUID.

Request body (application/json)

namestring

Updated feature name.

descriptionstring

Updated feature description.

parentIduuid | null

Updated parent feature.

Responses

200

Updated

The feature was successfully updated.

Schema

ProductFeature

DELETE

Delete a product feature

Delete one product feature.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
featureId *	uuid	The feature UUID.

Responses

200

Deleted

The feature was successfully deleted.

GET

List product personas

List personas for a product.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Responses

200

Success

Personas were successfully retrieved.

Schema

Array<ProductPersona>

Example Response

200 OK

json

[
  {
    "id": "persona-uuid",
    "productId": "product-uuid",
    "name": "Product Manager",
    "description": "Owns discovery synthesis.",
    "goals": [],
    "painPoints": [],
    "useCases": []
  }
]

POST

Create a product persona

Create one product persona.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Request body (application/json)

namestring

Required

Persona name.

descriptionstring

Required

Persona description.

goalsstring[]

Persona goals.

painPointsstring[]

Persona pain points.

useCasesstring[]

Persona use cases.

Responses

201

Created

The persona was successfully created.

Schema

ProductPersona

PATCH

Update a product persona

Update one product persona.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
personaId *	uuid	The persona UUID.

Request body (application/json)

namestring

Updated persona name.

descriptionstring

Updated persona description.

goalsstring[]

Replacement goals.

painPointsstring[]

Replacement pain points.

useCasesstring[]

Replacement use cases.

Responses

200

Updated

The persona was successfully updated.

Schema

ProductPersona

DELETE

Delete a product persona

Delete one product persona.

Requirements

API scopes required:

products:write

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
personaId *	uuid	The persona UUID.

Responses

200

Deleted

The persona was successfully deleted.

GET

List product questions

List product clarification questions. This API is read-only for questions.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.

Responses

200

Success

Questions were successfully retrieved.

Schema

Array<ProductQuestion>

GET

Get a product question

Retrieve one product clarification question.

Requirements

API scopes required:

products:read

Request

Parameters

Name	Type	Description
id *	uuid	The product UUID.
questionId *	uuid	The question UUID.

Responses

200

Success

The question was successfully retrieved.

Schema

ProductQuestion

Insights

Insights are the core of discovery. They represent feedback, observations, or data points collected from users and markets. Use these endpoints to manage the lifecycle of your discovery data.

Operations

GET/external/v1/insights

insights:read

GET/external/v1/insights/:id

insights:read

POST/external/v1/insights

insights:write

PATCH/external/v1/insights/:id

insights:write

DELETE/external/v1/insights/:id

insights:delete

POST/external/v1/insights/process-transcript/insights

insights:write

GET

List Insights

Returns a bounded page of insights in your workspace. Insights are the core of discovery, representing feedback and data points collected from various sources.

Requirements

API scopes required:

insights: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)
include	string	Comma-separated optional details. Supported values: classifications, provenance. Provenance can increase response size.

Responses

200

Success

A list of insights was successfully retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers.

Schema

Array<Insight>

Example Request

GET

/external/v1/insights

curl

curl -X GET https://zentrik.ai/api/external/v1/insights?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Users find navigation confusing",
    "description": "Initial feedback from customer interviews...",
    "status": "published",
    "type": "feedback",
    "productId": "8a1b2c3d-...",
    "createdAt": "2024-03-20T10:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z",
    "opportunityIds": [
      "uuid-1"
    ],
    "ideaIds": [
      "uuid-2"
    ],
    "tagIds": [
      "tag-1"
    ]
  }
]

GET

Get Insight

Retrieve detailed information about a specific insight by its unique identifier.

Requirements

API scopes required:

insights:read

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier of the insight

Responses

200

Success

The insight details were successfully retrieved.

Schema

Insight

404

Not Found

No insight found with the provided ID.

Example Request

GET

/external/v1/insights/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/insights/550e8400-e29b-41d4-a716-446655440000 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Users find navigation confusing",
  "description": "Initial feedback from customer interviews...",
  "status": "published",
  "type": "feedback",
  "productId": "8a1b2c3d-...",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "opportunityIds": [
    "uuid-1"
  ],
  "ideaIds": [
    "uuid-2"
  ],
  "tagIds": [
    "tag-1"
  ]
}

POST

Create Insight

Manually create a new insight. Use this for structured feedback or when you already have the processed data.

Requirements

API scopes required:

insights:write

Request

Request body (application/json)

namestring

The title of the insight

descriptionstring

Required

Detailed summary of the observation

statusstring

Default is 'draft'. One of: draft, published, archived

typestring

One of: feedback, user-interview, market-research, session-recording, support-ticket, other

productIduuid

ID of the associated product

opportunityIdsstring[]

List of associated opportunity IDs

ideaIdsstring[]

List of associated idea IDs

tagIdsstring[]

List of associated tag IDs

suggestionsobject

AI-generated suggestions for the insight

externalLinksobject[]

Array of { type, url, name } for external references

Responses

201

Created

The insight was successfully created.

Schema

Insight

Example Request

POST

/external/v1/insights

json

{
  "name": "User finds the billing page confusing",
  "description": "During user interviews, 3/5 users couldn't find...",
  "status": "published",
  "type": "feedback",
  "productId": "8a1b2c3d-...",
  "tagIds": [
    "tag-1"
  ]
}

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "User finds the billing page confusing",
  "description": "During user interviews, 3/5 users couldn't find...",
  "status": "published",
  "type": "feedback",
  "productId": "8a1b2c3d-...",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "opportunityIds": [],
  "ideaIds": [],
  "tagIds": [
    "tag-1"
  ]
}

PATCH

Update Insight

Modify an existing insight. You can update the status, name, or description as the discovery process evolves.

Requirements

API scopes required:

insights:write

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier of the insight

Request body (application/json)

namestring

Updated title

descriptionstring

Updated description

statusstring

Update state (e.g., 'archived')

typestring

Updated type

productIduuid

Updated product association

opportunityIdsstring[]

Updated list of opportunity IDs

ideaIdsstring[]

Updated list of idea IDs

tagIdsstring[]

Updated list of tag IDs

Responses

200

Updated

The insight was successfully updated.

Schema

Insight

Example Request

PATCH

/external/v1/insights/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/insights/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status": "archived"}'

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "Users find navigation confusing",
  "description": "Initial feedback from customer interviews...",
  "status": "archived",
  "type": "feedback",
  "productId": "8a1b2c3d-...",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-21T09:00:00Z"
}

DELETE

Delete Insight

Permanently remove an insight from the workspace. This action cannot be undone.

Requirements

API scopes required:

insights:delete

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier of the insight

Responses

200

Success

The insight was successfully deleted.

Schema

{ message: string }

Example Request

DELETE

/external/v1/insights/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/insights/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "message": "Deleted"
}

POST

Extract insights from text (AI)

Leverage Zentrik's AI to automatically extract insights from meeting transcripts, support tickets, or long-form feedback. The AI identifies key pain points and opportunities automatically.

Requirements

API scopes required:

insights:write

Request

Request body (application/json)

transcriptstring

Required

Full transcript text to analyze for insights

productIduuid

Optional product ID to associate insights with

createInsightsboolean

Whether to persist generated insights (default: false)

Responses

200

Success

AI processing completed successfully.

Schema

Array<Insight>

Example Request

POST

/external/v1/insights/process-transcript/insights

json

{
  "transcript": "Full text of the meeting or feedback...",
  "createInsights": true
}

Example Response

200 OK

json

[
  {
    "id": "uuid-1",
    "name": "Navigation issue",
    "description": "Users expressed confusion about the menu layout...",
    "type": "feedback",
    "status": "draft",
    "createdAt": "2024-03-20T10:00:00Z"
  }
]

Data Models

Understanding the structure of the data returned by the Insights API. These models are consistent across all endpoints in this category.

Insight Object

Field	Type	Description
id	uuid	The unique identifier for the insight.
name	string	The title or headline of the insight.
description	string	A detailed summary of the observation or feedback.
status	enum	The current state of the insight (draft, published, archived).
type	enum	The source or category of the insight (e.g., feedback, user-interview).
productId	uuid \| null	The ID of the product this insight belongs to.
opportunityIds	uuid[]	List of IDs for opportunities linked to this insight.
ideaIds	uuid[]	List of IDs for ideas linked to this insight.
tagIds	uuid[]	List of IDs for tags associated with this insight.
createdAt	iso-date	Timestamp when the insight was first created.
updatedAt	iso-date	Timestamp of the last modification.

Opportunities

Opportunities help you bridge the gap between user problems (insights) and product solutions (ideas). Use these endpoints to organize and prioritize the problems worth solving.

Operations

GET/external/v1/opportunities

opportunities:read

GET/external/v1/opportunities/:id

opportunities:read

POST/external/v1/opportunities

opportunities:write

PATCH/external/v1/opportunities/:id

opportunities:write

DELETE/external/v1/opportunities/:id

opportunities:delete

GET

List opportunities

Retrieve a bounded page of compact opportunities in your workspace. Opportunities represent significant problems, needs, or desired outcomes identified from insights. List responses use relation IDs/counts instead of hydrating every linked insight or idea.

Requirements

API scopes required:

opportunities: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)

Responses

200

Success

List of opportunities retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers.

Schema

Array<Opportunity>

Example Request

GET

/external/v1/opportunities

curl

curl -X GET https://zentrik.ai/api/external/v1/opportunities?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "uuid",
    "name": "Streamline checkout process",
    "description": "High drop-off rate at the final step...",
    "status": "Draft",
    "insightIds": [
      "insight-uuid"
    ],
    "ideaIds": []
  }
]

GET

Get one opportunity

Retrieve detailed information about a specific opportunity.

Requirements

API scopes required:

opportunities:read

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier of the opportunity

Responses

200

Success

Schema

Opportunity

Example Request

GET

/external/v1/opportunities/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "Streamline checkout process"
}

POST

Create an opportunity

Define a new opportunity identified from your discovery efforts.

Requirements

API scopes required:

opportunities:write

Request

Request body (application/json)

namestring

Required

Title of the opportunity

descriptionstring

Required

Detailed problem statement

scorenumber

Opportunity score (0-100)

Responses

201

Created

The opportunity was successfully created.

Schema

Opportunity

Example Request

POST

/external/v1/opportunities

json

{
  "name": "Reduce churn in Mobile App",
  "description": "Users are uninstalling after 2 days...",
  "score": 92
}

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "Reduce churn in Mobile App"
}

PATCH

Update an opportunity

Modify an existing opportunity.

Requirements

API scopes required:

opportunities:write

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier of the opportunity

Request body (application/json)

namestring

Updated title

scorenumber

Updated score

Responses

200

Updated

Schema

Opportunity

Example Request

PATCH

/external/v1/opportunities/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"score": 95}'

DELETE

Delete an opportunity

Permanently remove an opportunity.

Requirements

API scopes required:

opportunities:delete

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier

Responses

200

Success

Example Request

DELETE

/external/v1/opportunities/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/opportunities/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Data Models

The Opportunity model represents a prioritized problem or need discovered during the research phase.

Opportunity Object

Field	Type	Description
id	uuid	The unique identifier for the opportunity.
name	string	The title of the opportunity.
description	string	Detailed summary of the problem or need.
score	number	Priority score (0-100) based on impact and feasibility.
status	enum	Current state (e.g., discovery, defined, validated, archived).
productId	uuid	The ID of the product this opportunity addresses.
insightIds	uuid[]	IDs of insights that support this opportunity.
ideaIds	uuid[]	IDs of ideas that aim to solve this opportunity.
createdAt	iso-date	Creation timestamp.
updatedAt	iso-date	Last update timestamp.

Ideas

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

Operations

GET/external/v1/ideas

ideas:read

GET/external/v1/ideas/:id

ideas:read

POST/external/v1/ideas

ideas:write

PATCH/external/v1/ideas/:id

ideas:write

DELETE/external/v1/ideas/:id

ideas:delete

GET

List 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)

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": "evaluating"
  }
]

GET

Get one idea

Retrieve one feature idea by ID.

Requirements

API scopes required:

ideas:read

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier

Responses

200

Success

Schema

Idea

Example Request

GET

/external/v1/ideas/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/ideas/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST

Create an idea

Submit a new feature idea or solution for evaluation.

Requirements

API scopes required:

ideas:write

Request

Request body (application/json)

namestring

Required

Title of the idea

descriptionstring

Required

Detailed description of the solution

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

Example Response

200 OK

json

{
  "id": "uuid",
  "name": "AI-powered search"
}

PATCH

Update an idea

Modify an existing idea.

Requirements

API scopes required:

ideas:write

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier

Request body (application/json)

namestring

Updated name

descriptionstring

Updated description

Responses

200

Updated

Schema

Idea

Example Request

PATCH

/external/v1/ideas/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/ideas/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"name": "AI Search 2.0"}'

DELETE

Delete an idea

Permanently delete an idea.

Requirements

API scopes required:

ideas:delete

Request

Parameters

Name	Type	Description
id *	uuid	The unique identifier

Responses

200

Success

Example Request

DELETE

/external/v1/ideas/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/ideas/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

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	enum	Evaluation state (e.g., evaluating, backlog, development, released, archived).
productId	uuid	The ID of the product this idea belongs to.
opportunityIds	uuid[]	List of opportunities that this idea addresses.
insightIds	uuid[]	List of insights that inspired this idea.
createdAt	iso-date	Creation timestamp.
updatedAt	iso-date	Last update timestamp.

OKRs

OKRs describe measurable product outcomes for a workspace. Use these endpoints to keep objectives, key results, product links, and project links synchronized with external planning systems.

Operations

GET/external/v1/okrs

okrs:read

GET/external/v1/okrs/:id

okrs:read

POST/external/v1/okrs

okrs:write

PATCH/external/v1/okrs/:id

okrs:write

DELETE/external/v1/okrs/:id

okrs:delete

GET

List all OKRs

List OKRs in the current workspace. Results include product ids and key-result project ids.

Requirements

API scopes required:

okrs:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of OKRs to return.
offset	number	Number of OKRs to skip.

Responses

200

Success

OKRs were successfully retrieved.

Schema

Array<OKR>

Example Request

GET

/external/v1/okrs

curl

curl -X GET 'https://zentrik.ai/api/external/v1/okrs?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "okr-uuid",
    "objective": "Increase activation for self-serve teams",
    "priority": 1,
    "workspaceId": "workspace-uuid",
    "productIds": [
      "product-uuid"
    ],
    "keyResults": [
      {
        "id": "key-result-uuid",
        "name": "Lift week-one activation from 42% to 55%",
        "projectIds": [
          "project-uuid"
        ],
        "createdAt": "2026-05-14T10:00:00Z",
        "updatedAt": "2026-05-14T10:00:00Z"
      }
    ],
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z"
  }
]

GET

Get one OKR

Retrieve one OKR from the current workspace.

Requirements

API scopes required:

okrs:read

Request

Parameters

Name	Type	Description
id *	uuid	The OKR UUID.

Responses

200

Success

The OKR was successfully retrieved.

Schema

OKR

404

Not Found

No OKR found with the provided id.

Example Request

GET

/external/v1/okrs/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "okr-uuid",
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "workspaceId": "workspace-uuid",
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "id": "key-result-uuid",
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ],
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ],
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

POST

Create an OKR

Create an OKR. Product and project ids must belong to the API key workspace.

Requirements

API scopes required:

okrs:write

Request

Request body (application/json)

objectivestring

Required

Outcome-oriented objective.

prioritynumber

Required

Numeric priority used by planning surfaces.

productIdsuuid[]

Products this OKR supports.

keyResultsobject[]

Required

Array of { name, projectIds? } key results.

Responses

201

Created

The OKR was successfully created.

Schema

OKR

Example Request

POST

/external/v1/okrs

json

{
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ]
    }
  ]
}

Example Response

200 OK

json

{
  "id": "okr-uuid",
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "workspaceId": "workspace-uuid",
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "id": "key-result-uuid",
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ],
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ],
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

PATCH

Update an OKR

Update an OKR. When keyResults is supplied, it is treated as the full replacement list.

Requirements

API scopes required:

okrs:write

Request

Parameters

Name	Type	Description
id *	uuid	The OKR UUID.

Request body (application/json)

objectivestring

Updated objective.

prioritynumber

Updated priority.

productIdsuuid[]

Replacement product links.

keyResultsobject[]

Replacement key-result list. Existing key results include id.

Responses

200

Updated

The OKR was successfully updated.

Schema

OKR

Example Request

PATCH

/external/v1/okrs/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"priority":2}'

DELETE

Delete an OKR

Delete an OKR and its key results from the current workspace.

Requirements

API scopes required:

okrs:delete

Request

Parameters

Name	Type	Description
id *	uuid	The OKR UUID.

Responses

200

Deleted

The OKR was successfully deleted.

Example Request

DELETE

/external/v1/okrs/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Data Models

The OKR model returns product links as ids and nests key results with their project links.

OKR Object

Field	Type	Description
id	uuid	The unique identifier for the OKR.
objective	string	Outcome-oriented objective.
priority	number	Numeric priority used by roadmap planning surfaces.
workspaceId	uuid	Workspace that owns the OKR.
productIds	uuid[]	Products linked to the OKR.
keyResults	object[]	Key results with id, name, projectIds, createdAt, and updatedAt.
createdAt	iso-date	Timestamp when the OKR was created.
updatedAt	iso-date	Timestamp of the latest OKR update.

Context Units

Context units are curated Markdown guidance that agents and product workflows reuse across a workspace. Use these endpoints for text-based rules, decisions, constraints, and product-scoped guidance.

Operations

GET/external/v1/context-units

context-units:read

GET/external/v1/context-units/:id

context-units:read

POST/external/v1/context-units

context-units:write

PATCH/external/v1/context-units/:id

context-units:write

DELETE/external/v1/context-units/:id

context-units:delete

GET

List all context units

List context units in the current workspace. Responses include the full Markdown body.

Requirements

API scopes required:

context-units:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of context units to return.
offset	number	Number of context units to skip.

Responses

200

Success

Context units were successfully retrieved.

Schema

Array<ContextUnit>

Example Request

GET

/external/v1/context-units

curl

curl -X GET 'https://zentrik.ai/api/external/v1/context-units?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "context-unit-uuid",
    "name": "Engineering principles",
    "description": "Reusable engineering guidance for product delivery.",
    "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
    "productId": null,
    "workspaceId": "workspace-uuid",
    "vectorFileId": "file-vector-id",
    "indexingStatus": "indexed",
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z"
  }
]

GET

Get one context unit

Retrieve one context unit from the current workspace.

Requirements

API scopes required:

context-units:read

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Responses

200

Success

The context unit was successfully retrieved.

Schema

ContextUnit

404

Not Found

No context unit found with the provided id.

Example Request

GET

/external/v1/context-units/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/context-units/context-unit-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "context-unit-uuid",
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null,
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

POST

Create a context unit

Create a native text context unit. The data field accepts Markdown and is indexed for retrieval.

Requirements

API scopes required:

context-units:write

Request

Request body (application/json)

namestring

Required

Short title for the context unit.

descriptionstring

Human-readable summary.

datastring

Required

Full Markdown context body.

productIduuid | null

Optional product scope. Omit or null for global workspace context.

Responses

201

Created

The context unit was stored and indexed.

Schema

ContextUnit

Example Request

POST

/external/v1/context-units

json

{
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null
}

Example Response

200 OK

json

{
  "id": "context-unit-uuid",
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null,
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

PATCH

Update a context unit

Update context unit text or metadata. Any content or scope change reindexes the context unit.

Requirements

API scopes required:

context-units:write

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Request body (application/json)

namestring

Updated title.

descriptionstring

Updated summary.

datastring

Updated Markdown context body.

productIduuid | null

Replacement product scope. Null makes the unit global.

Responses

200

Updated

The context unit was successfully updated.

Schema

ContextUnit

Example Request

PATCH

/external/v1/context-units/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/context-units/context-unit-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data":"## Principles\n\n- Validate workspace relationships"}'

DELETE

Delete a context unit

Delete a context unit and its retrieval index entry when present.

Requirements

API scopes required:

context-units:delete

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Responses

200

Deleted

The context unit was successfully deleted.

Example Request

DELETE

/external/v1/context-units/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/context-units/context-unit-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Data Models

Context unit responses include the full Markdown body in data and retrieval indexing status.

ContextUnit Object

Field	Type	Description
id	uuid	The unique identifier for the context unit.
name	string	Short title for the reusable context.
description	string	Human-readable summary for when to use this context.
data	string	Full Markdown context body.
productId	uuid \| null	Product retrieval scope, or null for global workspace context.
workspaceId	uuid	Workspace that owns the context unit.
vectorFileId	string \| null	Retrieval provider file id when indexing has completed.
indexingStatus	enum	indexed when retrieval indexing is available, pending otherwise.
createdAt	iso-date	Timestamp when the context unit was created.
updatedAt	iso-date	Timestamp of the latest context unit update.

Context Documents

Context documents are workspace knowledge files used by retrieval and product context surfaces. Use these endpoints to import text, upload files, scope documents to products, and inspect previewable content.

Operations

GET/external/v1/context-documents

context-documents:read

GET/external/v1/context-documents/:id

context-documents:read

GET/external/v1/context-documents/:id/content

context-documents:read

POST/external/v1/context-documents

context-documents:write

POST/external/v1/context-documents/upload

context-documents:write

PATCH/external/v1/context-documents/:id

context-documents:write

DELETE/external/v1/context-documents/:id

context-documents:delete

GET

List all context documents

List context documents in the current workspace. Raw storage keys are never returned.

Requirements

API scopes required:

context-documents:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of documents to return.
offset	number	Number of documents to skip.

Responses

200

Success

Context documents were successfully retrieved.

Schema

Array<ContextDocument>

Example Request

GET

/external/v1/context-documents

curl

curl -X GET 'https://zentrik.ai/api/external/v1/context-documents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "context-document-uuid",
    "fileName": "activation-research.md",
    "mimeType": "text/markdown",
    "size": 1834,
    "description": "Research notes for activation planning.",
    "productId": "product-uuid",
    "workspaceId": "workspace-uuid",
    "vectorFileId": "file-vector-id",
    "indexingStatus": "indexed",
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z"
  }
]

GET

Get one context document

Retrieve metadata for one context document in the current workspace.

Requirements

API scopes required:

context-documents:read

Request

Parameters

Name	Type	Description
id *	uuid	The context document UUID.

Responses

200

Success

The context document was successfully retrieved.

Schema

ContextDocument

404

Not Found

No context document found with the provided id.

Example Request

GET

/external/v1/context-documents/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

GET

Preview context document content

Preview text-like context document content. Large content is truncated to the documented limit.

Requirements

API scopes required:

context-documents:read

Request

Parameters

Name	Type	Description
id *	uuid	The context document UUID.

Responses

200

Success

The preview payload was returned.

Example Request

GET

/external/v1/context-documents/:id/content

curl

curl -X GET https://zentrik.ai/api/external/v1/context-documents/context-document-uuid/content \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "supported": true,
  "content": "# Activation research",
  "contentFormat": "markdown",
  "truncated": false,
  "maxChars": 40000,
  "sourceUrl": null,
  "sourceLabel": null
}

POST

Import a text context document

Import a text or markdown context document from JSON. The document is stored and indexed for retrieval.

Requirements

API scopes required:

context-documents:write

Request

Request body (application/json)

fileNamestring

Required

Display file name, including extension.

contentstring

Required

Text content to store and index.

mimeTypestring

Defaults to text/markdown.

productIduuid | null

Optional product scope. Omit or null for global workspace context.

descriptionstring | null

Human-readable context note.

Responses

201

Created

The context document was stored and queued for retrieval indexing.

Schema

ContextDocument

Example Request

POST

/external/v1/context-documents

json

{
  "fileName": "activation-research.md",
  "content": "# Activation research\n\nTeams need clearer setup progress.",
  "mimeType": "text/markdown",
  "productId": "product-uuid",
  "description": "Research notes for activation planning."
}

Example Response

200 OK

json

{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

POST

Upload a context document file

Upload a binary or text file as multipart/form-data. The file field name must be file.

Requirements

API scopes required:

context-documents:write

Request

Request body (application/json)

filefile

Required

The file to upload. Maximum size is 50 MB.

productIduuid | null

Optional product scope.

descriptionstring | null

Human-readable context note.

Responses

201

Created

The context document file was uploaded.

Schema

ContextDocument

Example Request

POST

/external/v1/context-documents/upload

curl

curl -X POST https://zentrik.ai/api/external/v1/context-documents/upload \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@activation-research.md' \
  -F 'productId=product-uuid'

Example Response

200 OK

json

{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

PATCH

Update a context document

Update document metadata. Changing productId re-indexes the document with the new retrieval scope.

Requirements

API scopes required:

context-documents:write

Request

Parameters

Name	Type	Description
id *	uuid	The context document UUID.

Request body (application/json)

fileNamestring

Updated display file name.

descriptionstring | null

Updated context note.

productIduuid | null

Replacement product scope. Null makes the document global.

Responses

200

Updated

The context document was successfully updated.

Schema

ContextDocument

Example Request

PATCH

/external/v1/context-documents/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"productId":null}'

DELETE

Delete a context document

Delete a context document, its stored file, and its retrieval index entry when present.

Requirements

API scopes required:

context-documents:delete

Request

Parameters

Name	Type	Description
id *	uuid	The context document UUID.

Responses

200

Deleted

The context document was successfully deleted.

Example Request

DELETE

/external/v1/context-documents/:id

curl

curl -X DELETE https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Data Models

Context document responses expose retrieval status and safe metadata, not storage keys.

ContextDocument Object

Field	Type	Description
id	uuid	The unique identifier for the context document.
fileName	string	Display file name.
mimeType	string \| null	Stored MIME type.
size	number \| null	Stored byte size.
description	string \| null	Human-readable note.
productId	uuid \| null	Product retrieval scope, or null for global workspace context.
workspaceId	uuid	Workspace that owns the context document.
vectorFileId	string \| null	Retrieval provider file id when indexing has completed.
indexingStatus	enum	indexed when retrieval indexing is available, pending otherwise.
createdAt	iso-date	Timestamp when the document was created.
updatedAt	iso-date	Timestamp of the latest metadata update.