> ## Documentation Index
> Fetch the complete documentation index at: https://conveo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# About the Conveo API

> Authenticate, paginate, and retrieve completed study and interview data through Conveo's REST API.

Use the REST API to retrieve study metadata, interview transcripts, facets, and temporary video-download links for an organization. The public v1 API provides four read endpoints. For assistant-driven study configuration and analysis, use the separate [MCP server](/docs/api-reference/mcp).

## Create an API key

An organization admin can open **Settings → Organization → API keys** and select **Create API key**. Enter an **Identifier** that names the integration and save. Copy the key immediately; it is shown only once.

The key identifies an organization. REST requests use organization-level access, rather than the current study-sharing permissions of the person running the request. Store the key as a secret and avoid putting it in browser code, URLs, or source control.

To revoke access, delete the key from **API keys**. To rotate a key, create its replacement, update the integration, verify access, and then delete the old key.

## Make a request

Base URL: `https://app.conveo.ai/public-api/v1`

Set `CONVEO_API_KEY` securely in your environment, then request the first page:

```bash theme={null}
curl --fail-with-body \
  --header "Authorization: Bearer ${CONVEO_API_KEY}" \
  'https://app.conveo.ai/public-api/v1/studies?page=1&pageSize=20'
```

The API also accepts `Conveo-Api-Key` as a header. A Bearer token takes precedence when both are supplied. Use an organization API key for REST; MCP OAuth access tokens are a different credential.

## Available endpoints

| Method and path                     | Returned data                                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------------------------- |
| `GET /studies`                      | Completed studies for the key's organization, ordered by completion time descending.          |
| `GET /studies/{id}`                 | Metadata for one completed study in that organization.                                        |
| `GET /studies/{studyId}/interviews` | Completed, visible interviews from a completed study, ordered by creation time descending.    |
| `GET /interviews/{id}`              | One completed, visible interview in the organization; its parent study need not be completed. |

The study-list response includes `completedOn`; the single-study response currently returns `id`, `internalTitle`, `createdAt`, and `updatedAt`. Interview responses include facets, participant details where available, transcript text, and a download URL where available.

See the endpoint reference for field schemas and examples. [Download this documentation's OpenAPI definition](/docs/api-reference/openapi.yml).

## Pagination

List endpoints accept integer `page` and `pageSize` parameters:

| Parameter | Default | Allowed values |
| --------- | ------- | -------------- |
| page      | 1       | 1 or greater   |
| pageSize  | 20      | 1–100          |

Responses contain `items` and `pagination`, with `page`, `pageSize`, and `total`. Continue until `page × pageSize` reaches `total`, or no items remain. Pagination is based on page numbers rather than a snapshot: new or changed records can shift page contents while an export is running. Deduplicate by ID when combining pages.

## Transcript and media behavior

* `transcriptAsWebVTT` contains participant-response messages, not a full alternating interviewer/participant dialogue. It is `null` when no response messages are available.
* The transcript uses original message text. Missing timing can produce zero or equal start/end times; do not assume every cue has meaningful duration.
* `participant` can be `null`. Its `name` can also be `null`; when available, the display name combines the first name and last initial.
* `videoDownloadURL` is `null` when a downloadable stored video is unavailable or URL creation fails. A generated link expires after 15 minutes. Request the interview again to obtain a fresh link.
* Hidden interviews are excluded. Draft and in-progress studies are not returned by the study endpoints.

## Handle errors

| Status | Meaning and next step                                                                                           |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| 400    | Invalid pagination; check integer values and bounds.                                                            |
| 401    | Missing or invalid API key; verify the credential and header.                                                   |
| 404    | The requested record is unavailable under that endpoint's organization, completion, or visibility requirements. |

Do not assume every error has the same JSON shape. Authentication and not-found errors use an `error` field; pagination validation returns a JSON error string. Retry transient server/network failures with backoff, and obtain a new media URL when an old link expires. No fixed public request-rate quota is specified here.

Contact [support@conveo.ai](mailto:support@conveo.ai) if you cannot access the required integration settings.