Skip to main content
The Versive public API (v1) lets you manage studies, questions, logic, interviews, translations, and insights programmatically. Typical uses: creating interviews with tracked links from your own app, syncing study content from your systems, building studies with the AI agent, and pulling interview transcripts and summaries into your data warehouse.

​
Base URL

The machine-readable OpenAPI document is available at:
Use the OpenAPI document for code generation and agent tool discovery. The pages in this reference add examples, authorization context, and product guidance that are not represented fully in the schema.

​
Authentication

Public REST integrations use an organization API key passed as a Bearer token:
API keys are created in your organization settings (Organization → API keys) by an owner or admin. Each key is scoped to one organization and grants full API access to that organization’s data — there are no per-key scopes, so treat keys like passwords: store them in a secrets manager, never in client-side code, and deactivate keys you no longer use. A missing or invalid bearer credential returns 401 with {"detail": "Invalid authentication credentials"}. The same public API routes also accept short-lived, scoped JWTs issued for authenticated Versive MCP server sessions. Each MCP connection is granted studies:read, interviews:read, and studies:write at consent time (or a narrower set if the client requests one). Those scopes are an upper bound: organization roles and study access policies are still checked on every request. MCP clients manage these credentials automatically; do not copy MCP access tokens into direct REST API integrations.

​
Conventions

  • JSON everywhere — request bodies are JSON (Content-Type: application/json); one endpoint (Update question) also accepts multipart/form-data for file uploads.
  • IDs are UUID strings.
  • Organization scoping is automatic — the key determines the organization; requesting a resource that belongs to another organization returns 403.
  • Partial updates — PUT endpoints only change the fields you send. On studies, the config object is merged into the existing config rather than replaced.
  • Pagination is endpoint-specific — list studies currently returns all matching records, while GET /interviews?study_id=... supports page and page_size. Check each endpoint’s parameters before assuming either behavior.

​
Rate limits and retries

Versive does not currently publish numeric request-rate limits for the public API. Clients should keep concurrency bounded and retry transient 5xx responses with exponential backoff and jitter. If the API edge returns 429, treat it as transient and honor Retry-After when present. Do not retry validation, authentication, or authorization failures without changing the request. See Versioning and compatibility for the public API lifecycle and deprecation signals.

​
Errors

Errors use conventional HTTP status codes with a JSON body:

​
Resources

Studies

Create, list, update, translate, and AI-edit studies; read response metrics.

Questions

Read, batch-create/update, and delete a study’s questions.

Question logic

Manage conditional branching rules.

Interviews

Create tracked participant links and read interview transcripts and status.

Insights

Fetch AI-generated interview summaries.

Translations

Trigger and manage study translations.

Folders

Create and list folders for organizing studies.

Webhooks

Receive an event after an interview is completed.

Versioning

Understand compatibility guarantees and deprecation signals.