Studies

Inspect Study formats, Prototype usage, accepted work context, privacy-bounded Findings, and findings freshness without exposing participant identity or research answers.

4 endpoints

GET

List studies

GET /external/v1/studies

List Study metadata, format, Prototype stimulus, response counts, typed feedback configuration, and currently accepted work context. Use moderationMode and studyFormat to distinguish live interviews, AI-moderated interviews, and self-guided Studies. usesPrototype and prototypeStimulus identify Studies that test a Prototype. Research answers and participant identity are excluded. Follow X-Has-More and advance offset by X-Limit to retrieve the complete catalog.

Requirements

API scopes required:

studies:read

Request

Parameters

Name	Type	Description
limit	number	1–100 results. Defaults to 20.
offset	number	Number of results to skip.
status	string	Exact Study status.
moderationMode	enum	Filter by self_guided, ai_moderated, or live_interview.
initiativeId	uuid	Current accepted Initiative context.
ideaId	uuid	Current accepted Idea context.

Responses

200

Success

Studies were retrieved.

Schema

Array<Study>

Example Response

200 OK

json

[
  {
    "id": "study-uuid",
    "publicId": "STUDY-8",
    "workspaceId": "workspace-uuid",
    "name": "Scheduler direction check",
    "mainQuestion": "Can customers choose the right appointment type?",
    "status": "active",
    "type": "heatmap_interaction",
    "phase": "validation",
    "moderationMode": "live_interview",
    "studyFormat": "live_interview",
    "usesPrototype": true,
    "prototypeStimulus": {
      "prototypeId": "prototype-uuid",
      "prototypePublicId": "PROTOTYPE-7",
      "name": "Scheduling flow",
      "revisionId": "prototype-revision-uuid",
      "revisionNumber": 3,
      "status": "ready"
    },
    "responseCount": 7,
    "feedback": {
      "enabled": true,
      "prompt": "How clear was this interview?",
      "metric": "study_experience_clarity",
      "subject": {
        "type": "study",
        "id": "study-uuid"
      },
      "responseCount": 6,
      "averageRating": 4.17
    },
    "contexts": [],
    "initiativeIds": [],
    "ideaIds": [],
    "appPath": "/studies/STUDY-8",
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-14T10:00:00Z"
  }
]

GET

Get one study

GET /external/v1/studies/:id

Retrieve one Study by internal UUID or workspace-scoped public id. The response includes moderationMode, normalized studyFormat, usesPrototype, a bounded prototypeStimulus summary, and participantUrl when a participant-facing Study link is available.

Requirements

API scopes required:

studies:read

Request

Parameters

Name	Type	Description
id *	uuid \| public id	For example STUDY-8.

Responses

200

Success

The Study was retrieved.

Schema

Study

Example Response

200 OK

json

{
  "id": "study-uuid",
  "publicId": "STUDY-8",
  "workspaceId": "workspace-uuid",
  "name": "Scheduler direction check",
  "mainQuestion": "Can customers choose the right appointment type?",
  "status": "active",
  "type": "heatmap_interaction",
  "phase": "validation",
  "moderationMode": "self_guided",
  "studyFormat": "self_guided",
  "usesPrototype": true,
  "prototypeStimulus": {
    "prototypeId": "prototype-uuid",
    "prototypePublicId": "PROTOTYPE-7",
    "name": "Scheduling flow",
    "revisionId": "prototype-revision-uuid",
    "revisionNumber": 3,
    "status": "ready"
  },
  "responseCount": 7,
  "feedback": {
    "enabled": true,
    "prompt": "How clear was this study?",
    "metric": "study_experience_clarity",
    "subject": {
      "type": "study",
      "id": "study-uuid"
    },
    "responseCount": 6,
    "averageRating": 4.17
  },
  "contexts": [],
  "initiativeIds": [],
  "ideaIds": [],
  "appPath": "/studies/STUDY-8",
  "createdAt": "2026-07-01T00:00:00Z",
  "updatedAt": "2026-07-14T10:00:00Z",
  "participantUrl": "https://northstar.ideas.zentrik.ai/studies/scheduler-direction-check"
}

GET

Get study findings

GET /external/v1/studies/:id/evidence

Retrieve the active draft Findings version and its freshness for one Study. Findings include the decision summary, readiness, finding statements, evidence strength, sample count, review status, evidence-reference counts, recommended follow-ups, and open questions. This privacy-bounded endpoint never returns participant identity, raw responses, notes, transcripts, or verbatim evidence excerpts.

Requirements

API scopes required:

studies:read

Request

Parameters

Name	Type	Description
id *	uuid \| public id	For example STUDY-8.

Responses

200

Success

The active Findings and freshness were retrieved. findings is null when no version exists.

Schema

StudyEvidence

404

Not found

The Study does not exist in the API-key workspace.

Example Request

GET

/external/v1/studies/:id/evidence

curl

curl -X GET https://zentrik.ai/api/external/v1/studies/STUDY-8/evidence \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "study-uuid",
  "publicId": "STUDY-8",
  "name": "Scheduler direction check",
  "findings": {
    "versionId": "findings-version-uuid",
    "versionNumber": 2,
    "generatedAt": "2026-07-14T09:00:00Z",
    "decisionSummary": {
      "conclusion": "Customers need clearer appointment-type choices.",
      "evidenceStrength": "moderate",
      "productImplication": "Clarify labels before expanding the scheduling flow."
    },
    "readiness": {
      "status": "gathering_evidence",
      "note": "Interview one more office manager."
    },
    "findings": [
      {
        "id": "finding-uuid",
        "kind": "finding",
        "statement": "Participants missed the appointment-type control.",
        "evidenceStrength": "moderate",
        "sampleCount": 3,
        "reviewStatus": "draft",
        "evidenceReferenceCount": 4
      }
    ],
    "recommendedFollowUps": [
      "Test clearer appointment-type labels."
    ],
    "openQuestions": [
      "Does the result vary by office role?"
    ]
  },
  "findingsFreshness": {
    "hasFindings": true,
    "stale": false,
    "evidenceUpdatedAt": "2026-07-14T08:30:00Z",
    "findingsGeneratedAt": "2026-07-14T09:00:00Z"
  },
  "privacy": {
    "participantIdentityIncluded": false,
    "rawResponsesIncluded": false,
    "evidenceExcerptsIncluded": false
  }
}

POST

Generate study findings

POST /external/v1/studies/:id/findings/generate

Run Zentrik’s evidence-grounded AI synthesis for a Study and store a draft Findings version. The operation requires submitted responses. When the active Findings already cover the latest evidence, the request is an idempotent no-op and returns changed: false. The returned item follows the same privacy boundary as the Study evidence endpoint and still requires human review in Zentrik.

Requirements

API scopes required:

studies:write

Request

Parameters

Name	Type	Description
id *	uuid \| public id	For example STUDY-8.

Responses

200

Success

Findings were generated, or current Findings were returned with changed set to false.

Schema

StudyFindingsGenerationResult

400

No responses

The Study has no submitted responses to synthesize.

404

Not found

The Study does not exist in the API-key workspace.

Example Request

POST

/external/v1/studies/:id/findings/generate

curl

curl -X POST https://zentrik.ai/api/external/v1/studies/STUDY-8/findings/generate \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "operation": "study_findings_generation",
  "changed": true,
  "item": {
    "id": "study-uuid",
    "publicId": "STUDY-8",
    "name": "Scheduler direction check",
    "findings": {
      "versionId": "findings-version-uuid",
      "versionNumber": 2,
      "generatedAt": "2026-07-14T09:00:00Z",
      "decisionSummary": {
        "conclusion": "Customers need clearer appointment-type choices.",
        "evidenceStrength": "moderate",
        "productImplication": "Clarify labels before expanding the scheduling flow."
      },
      "readiness": {
        "status": "gathering_evidence",
        "note": "Interview one more office manager."
      },
      "findings": [
        {
          "id": "finding-uuid",
          "kind": "finding",
          "statement": "Participants missed the appointment-type control.",
          "evidenceStrength": "moderate",
          "sampleCount": 3,
          "reviewStatus": "draft",
          "evidenceReferenceCount": 4
        }
      ],
      "recommendedFollowUps": [
        "Test clearer appointment-type labels."
      ],
      "openQuestions": [
        "Does the result vary by office role?"
      ]
    },
    "findingsFreshness": {
      "hasFindings": true,
      "stale": false,
      "evidenceUpdatedAt": "2026-07-14T08:30:00Z",
      "findingsGeneratedAt": "2026-07-14T09:00:00Z"
    },
    "privacy": {
      "participantIdentityIncluded": false,
      "rawResponsesIncluded": false,
      "evidenceExcerptsIncluded": false
    }
  }
}