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.

6 endpoints

GET

List Insights

GET /external/v1/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.
sourceKey	string	Exact stable source namespace to match
externalId	string	Exact source-record identifier to match
integrationId	uuid	Exact connected integration identifier to match

Responses

200

Success

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": "Validated",
    "type": "Usability friction",
    "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

GET /external/v1/insights/:id

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": "Validated",
  "type": "Usability friction",
  "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

POST /external/v1/insights

Create or idempotently update a structured finding. Send sourceKey with externalId for a stable source identity. Send raw transcripts and other evidence to the Signals API so Zentrik preserves Evidence before routing findings.

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

One of: New, Validated, Rejected. Default is New.

typestring

One of: Bug, Request, Usability friction, Positive feedback, Tech, Other.

productIduuid

ID of the associated product

sourceKeystring

Stable source namespace. Use it with externalId for idempotent create-or-update behavior.

externalIdstring

Stable record identifier within sourceKey.

integrationIduuid

Connected integration identifier for integration-owned records.

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": "Validated",
  "type": "Usability friction",
  "productId": "8a1b2c3d-...",
  "sourceKey": "research-repository",
  "externalId": "finding-184",
  "tagIds": [
    "tag-1"
  ]
}

Example Response

201 Created

json

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

PATCH

Update Insight

PATCH /external/v1/insights/:id

Modify an existing insight by UUID. You can update its status, type, source identity, links, or description as the finding 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

Updated state: New, Validated, or Rejected

typestring

Updated type

productIduuid

Updated product association

sourceKeystring

Updated stable source namespace

externalIdstring

Updated source-record identifier

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

Example Response

200 OK

json

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

DELETE

Delete Insight

DELETE /external/v1/insights/:id

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

Preview insights from text (AI)

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

Preview insight candidates extracted from meeting transcripts, support tickets, or long-form feedback. This endpoint does not persist results. To create durable product records, send the source text to POST /external/v1/signals so Zentrik captures Evidence before routing or creating Insights.

Requirements

API scopes required:

insights:write

Request

Request body (application/json)

transcriptstring

Required

Full transcript text to analyze for insights

productIduuid

Optional product ID used to scope the preview

Responses

200

Success

AI preview completed successfully. No records were persisted.

Schema

Array<InsightCandidate>

400

Direct persistence disabled

createInsights=true is not supported. Create a Signal so Evidence is persisted before Insight routing.

Example Request

POST

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

json

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

Example Response

200 OK

json

[
  {
    "title": "Navigation issue",
    "description": "Users expressed confusion about the menu layout...",
    "extracts": "I can never find the menu item I need.",
    "category": "Usability",
    "confidence": 91
  }
]

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: New, Validated, or Rejected.
type	enum	The finding category: Bug, Request, Usability friction, Positive feedback, Tech, or Other.
productId	uuid \| null	The ID of the product this insight belongs to.
integrationId	uuid \| null	The integration this insight was imported from, or null when it was not created via an integration.
sourceKey	string \| null	The stable source namespace used with externalId for idempotent synchronization.
externalId	string \| null	The insight's identifier within sourceKey, or within its connected integration.
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.