Skip to main content
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.

​
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:
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

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.

​
Pagination

List endpoints accept integer page and pageSize parameters: 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

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 if you cannot access the required integration settings.