Skip to main content
The intervyo.ai REST API lets you run calibrated AI interviews from your own systems: define how the AI evaluates, schedule sessions, stream back scorecards, and sync results into your ATS, LMS, or internal tooling. Everything you can do in the dashboard is available over the API.

Agent Profiles

Define the interviewer — persona, scoring dimensions, tone, and difficulty.

Evaluation Templates

Describe what to assess: role, skills, objective, and the pass bar.

Evaluation Stages

Compose multi-step pipelines — screen → technical → final.

Participants

The people being evaluated. Create them, then schedule sessions.

Sessions

A single AI interview. Schedule it and the invite goes out automatically.

Code Execution

Run candidate code against test cases in Python, JavaScript, or TypeScript.

​
Base URL

All endpoints are served from a single host and versioned under /api/v1: 
https://www.intervyo.ai/api/v1

GET    https://www.intervyo.ai/api/v1/sessions
POST   https://www.intervyo.ai/api/v1/sessions
GET    https://www.intervyo.ai/api/v1/participants
POST   https://www.intervyo.ai/api/v1/agent-profiles

​
Authentication

Authenticate every request with an API key in the x-api-key header. Keys are created in the dashboard under Developer → API Keys and are prefixed iv_live_. 
curl "https://www.intervyo.ai/api/v1/sessions" \
  -H "x-api-key: iv_live_your_key_here"
API keys are secrets. Use them only from server-side code, never from a browser or mobile client. Rotate immediately if one leaks — see Authentication.
Calls made from a signed-in dashboard session can authenticate with cookies instead of a key. For those requests, pass your team slug as the accountSlug query parameter so the API can resolve the workspace.

​
Permission scopes

Keys carry granular scopes. A 403 means the key is valid but missing the scope an endpoint requires.
ScopeGrants access to
candidates.read / .write / .deleteParticipants
interviews.read / .writeSessions and agent profiles
evaluation_templates.read / .writeEvaluation templates
evaluation_stages.read / .writeEvaluation stages

​
Content type

Requests and responses are JSON. Send Content-Type: application/json on POST and PATCH. Responses are always JSON, except 204 No Content on successful deletes.

​
Response shape

Single-resource responses wrap the result in a data field: 
{
  "data": { "id": "e3a1c2d4-...", "status": "scheduled" }
}
List endpoints add a meta object with pagination details: 
{
  "data": [ /* rows */ ],
  "meta": { "page": 1, "pageSize": 20, "total": 137, "totalPages": 7 }
}

​
Pagination

List endpoints accept page and pageSize query parameters: 
GET /api/v1/sessions?page=2&pageSize=50
​
page
integer
default:"1"
1-based page number.
​
pageSize
integer
default:"20"
Items per page. Maximum 100.
Stop iterating once page reaches meta.totalPages.

​
Idempotency

Creating a session is the one operation you never want to run twice. Pass an idempotency_key in the request body — replaying the same key returns the original session instead of scheduling a duplicate. 
POST /api/v1/sessions
{
  "candidate_id": "ba4f2cdd-...",
  "evaluation_template_id": "ce1cd564-...",
  "stage": "screen",
  "idempotency_key": "ats-job-8821-stage-screen"
}
The response includes "idempotent": true when a prior session was returned.
Derive the key from a stable identifier in your own system — an ATS job + stage, for example — so automatic retries are naturally deduplicated.

​
Errors

Errors return the appropriate HTTP status with an error message. Validation failures (400) also include an issues array pinpointing the offending fields. 
{
  "error": "Validation error",
  "issues": [
    { "path": ["evaluation_template_id"], "message": "Required" }
  ]
}
The request body or query failed validation. Inspect issues for the specific fields.
Missing or invalid API key.
The workspace has no active paid plan, or you’re out of session credits.
The key is valid but lacks the required permission scope.
The resource doesn’t exist, or your key can’t see it.
The resource already exists — e.g. a duplicate participant email, or a duplicate session. Pass force: true to override the session check.
408 execution timed out (15s limit), 422 the language doesn’t support batched execution, 502 the upstream runner failed.
Retries are safe on 5xx. If a burst is throttled, honor the Retry-After header and back off exponentially.

​
Timestamps

All timestamps are ISO 8601 in UTC, and should be sent the same way: 
{ "scheduled_at": "2026-06-02T07:48:31.200Z" }

​
MCP server

The same engine is available over the Model Context Protocol for use inside Claude, Cursor, and other MCP clients. See Remote MCP Server.

​
Versioning

The current version is v1. Backward-compatible additions (new fields, new endpoints) ship under v1 without notice — write clients that ignore unknown fields. Breaking changes ship under a new prefix (v2), and v1 keeps working for at least 12 months after v2 reaches general availability.
Subscribe to the changelog for new endpoints and deprecation timelines.
Last modified on June 2, 2026