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

# Studies API reference

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

- Human reference: https://zentrik.ai/docs/api/studies
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/studies — List studies

Operation ID: `list-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.

Required API key scopes: `studies:read`

### Parameters

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

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Studies were retrieved. | Array<Study> |

### Example response

```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 /external/v1/studies/:id — Get one study

Operation ID: `get-study`

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.

Required API key scopes: `studies:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | For example STUDY-8. |

### Responses

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

### Example response

```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 /external/v1/studies/:id/evidence — Get study findings

Operation ID: `get-study-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.

Required API key scopes: `studies:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | For example STUDY-8. |

### Example request

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

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The active Findings and freshness were retrieved. findings is null when no version exists. | StudyEvidence |
| 404 | Not found | The Study does not exist in the API-key workspace. | — |

### Example response

```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 /external/v1/studies/:id/findings/generate — Generate study findings

Operation ID: `generate-study-findings`

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.

Required API key scopes: `studies:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid \| public id | Yes | For example STUDY-8. |

### Example request

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

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Findings were generated, or current Findings were returned with changed set to false. | 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 response

```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
    }
  }
}
```