AURAL
For Creators

API Reference

Comprehensive REST reference for interviews, questions, sessions, candidates, and usage—parameters, curl examples, and response shapes

Base URL and conventions

Base path: /api/v1. Examples below use https://aural-ai.com; substitute your deployment host.

  • Auth — Authorization: Bearer dlv_… on every request.
  • JSON — Send Content-Type: application/json for bodies unless noted.
  • Success — Most responses wrap payloads in data. Paginated lists also return cursor (opaque string or null when there is no next page).
  • Errors — JSON shaped like { "error": { "code", "message", ... } } with 4xx/5xx status codes.
  • Rate limits — 60 requests per minute per API key. When exceeded, the API returns 429 Too Many Requests with an error body; back off and retry with exponential delay.

Interviews

List interviews

GET/api/v1/interviews

Returns interviews your key can access in its projects. Each item includes question and session counts.

Query Parameters
limitinteger= 20
Page size. Minimum 1, maximum 100.
cursorstring
Opaque pagination token from the previous response’s cursor field. Omit on the first page.
Request
curl -sS "https://aural-ai.com/api/v1/interviews?limit=20" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": [
    {
      "id": "...",
      "title": "Backend screening",
      "isActive": true,
      "_count": { "questions": 3, "sessions": 12 }
    }
  ],
  "cursor": "eyJ..."
}

When cursor is null, there are no further pages. Pass the previous cursor value to continue.

Create interview

POST/api/v1/interviews

Creates an interview in your first accessible project. Requires a title; other fields use defaults below.

Request Body
titlerequiredstring
Display name for the interview template.
descriptionstring
Longer description shown in the product UI.
objectivestring
What you want to learn from candidates.
assessmentCriteriaobject[]
Array of { name, description } rubric items for evaluators.
chatEnabledboolean= true
Allow text chat in the session.
voiceEnabledboolean= false
Enable voice mode for candidates.
videoEnabledboolean= false
Enable video for candidates.
aiNamestring= Aural
Name the AI uses when speaking to candidates.
aiToneenum= PROFESSIONAL
CASUAL | PROFESSIONAL | FORMAL | FRIENDLY — interview tone.
followUpDepthenum= MODERATE
LIGHT | MODERATE | DEEP — how hard the AI probes.
languagestring= en
BCP-47 style language code for the session.
timeLimitMinutesinteger | null
Optional cap on session length in minutes.
antiCheatingEnabledboolean= false
Turn on anti-cheating signals where supported.

If your organization has reached its interview template quota, the API returns 403 with PLAN_LIMIT_EXCEEDED (see Usage & Limits).

Request
curl -sS -X POST "https://aural-ai.com/api/v1/interviews" \
  -H "Authorization: Bearer dlv_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Backend screening","voiceEnabled":true,"chatEnabled":true}'
Response 200
{
  "data": {
    "id": "...",
    "title": "Backend screening",
    "chatEnabled": true,
    "voiceEnabled": true,
    "videoEnabled": false,
    "aiTone": "PROFESSIONAL",
    "followUpDepth": "MODERATE",
    "language": "en"
  }
}

Get interview detail

GET/api/v1/interviews/:id

Returns one interview with its questions array and session count. Unknown or inaccessible ids yield 404.

No query parameters.

Request
curl -sS "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "id": "...",
    "title": "Backend screening",
    "objective": "Assess API design",
    "questions": [
      {
        "id": "...",
        "text": "Describe a recent API.",
        "type": "OPEN_ENDED",
        "order": 0
      }
    ],
    "_count": { "sessions": 12 }
  }
}

Update interview

PATCH/api/v1/interviews/:id

Partial update. Any create body field may be sent; omitted keys are left unchanged.

Request Body (all optional)
titlestring
New title.
descriptionstring
Updated description.
objectivestring
Updated objective.
assessmentCriteriaobject[]
Replace rubric with a new array of criteria.
chatEnabledboolean
Toggle chat channel.
voiceEnabledboolean
Toggle voice.
videoEnabledboolean
Toggle video.
aiNamestring
AI display name.
aiToneenum
CASUAL | PROFESSIONAL | FORMAL | FRIENDLY.
followUpDepthenum
LIGHT | MODERATE | DEEP.
languagestring
Session language code.
timeLimitMinutesinteger | null
Session time cap; null clears the cap.
antiCheatingEnabledboolean
Anti-cheating toggle.
Request
curl -sS -X PATCH "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID" \
  -H "Authorization: Bearer dlv_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voiceEnabled":true}'
Response 200
{
  "data": {
    "id": "...",
    "title": "Backend screening",
    "voiceEnabled": true
  }
}

Archive interview

DELETE/api/v1/interviews/:id

Soft-archives the interview by setting isActive to false. Historical sessions remain available.

No request body.

Request
curl -sS -X DELETE "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "id": "...",
    "archived": true
  }
}

Publish interview

POST/api/v1/interviews/:id/publish

Activates the interview, turns off invite-only mode, ensures a publicSlug exists, and returns the shareable candidate URL.

No request body.

Request
curl -sS -X POST "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/publish" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "id": "...",
    "publicSlug": "acme-backend-2025",
    "url": "https://aural-ai.com/i/acme-backend-2025"
  }
}

Questions

List questions

GET/api/v1/interviews/:id/questions

Returns all questions for the interview, sorted by order ascending.

No query parameters.

Request
curl -sS "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/questions" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": [
    {
      "id": "...",
      "text": "Pick a design pattern.",
      "type": "SINGLE_CHOICE",
      "order": 0,
      "options": ["Singleton", "Factory", "Observer"]
    }
  ]
}

Create questions

POST/api/v1/interviews/:id/questions

Creates one or many questions. Send a single object or an array; omit order to auto-increment.

Request Body (per question)
textrequiredstring
The prompt shown to the candidate.
typeenum= OPEN_ENDED
OPEN_ENDED | SINGLE_CHOICE | MULTIPLE_CHOICE | CODING | WHITEBOARD | RESEARCH.
orderinteger
Zero-based position; auto-assigned when omitted.
requiredboolean= true
Maps to isRequired in storage.
optionsstring[]
Choice labels for SINGLE_CHOICE and MULTIPLE_CHOICE.
followUpEnabledboolean= true
Maps to probeOnShort — allow AI follow-ups.

Wrap a single question in an object, or send an array to bulk-create.

Request
curl -sS -X POST "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/questions" \
  -H "Authorization: Bearer dlv_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"text":"Pick one","type":"SINGLE_CHOICE","options":["A","B"]}]'
Response 200
{
  "data": [
    {
      "id": "...",
      "text": "Pick one",
      "type": "SINGLE_CHOICE",
      "order": 0,
      "options": ["A", "B"]
    }
  ]
}

Update question

PATCH/api/v1/questions/:id

Partial update for a single question anywhere in your accessible projects.

Request Body (all optional)
textstring
New prompt text.
typeenum
Question type enum as on create.
orderinteger
Reorder index.
requiredboolean
Updates isRequired.
optionsstring[]
Replace choice options.
followUpEnabledboolean
Updates probeOnShort.
Request
curl -sS -X PATCH "https://aural-ai.com/api/v1/questions/QUESTION_ID" \
  -H "Authorization: Bearer dlv_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order":1}'
Response 200
{
  "data": {
    "id": "...",
    "text": "Pick one",
    "order": 1,
    "type": "SINGLE_CHOICE"
  }
}

Delete question

DELETE/api/v1/questions/:id

Permanently removes the question from its interview.

No request body.

Request
curl -sS -X DELETE "https://aural-ai.com/api/v1/questions/QUESTION_ID" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "id": "...",
    "deleted": true
  }
}

Sessions

List sessions for an interview

GET/api/v1/interviews/:id/sessions

Paginated sessions with summaries and per-session message counts.

Query Parameters
limitinteger= 20
Between 1 and 100.
cursorstring
Pagination token from the prior response.

Each row includes id, status, participant fields, AI outputs (summary, insights, themes, sentiment), totalDurationSeconds, timestamps, and _count.messages.

Request
curl -sS "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/sessions?limit=20" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": [
    {
      "id": "...",
      "status": "COMPLETED",
      "participantName": "Alex",
      "participantEmail": "alex[at]example.com",
      "summary": "Strong system design answers.",
      "insights": ["Clear tradeoff discussion"],
      "themes": ["APIs", "scalability"],
      "sentiment": "positive",
      "totalDurationSeconds": 1842,
      "createdAt": "2026-04-01T12:00:00.000Z",
      "updatedAt": "2026-04-01T12:31:00.000Z",
      "_count": { "messages": 42 }
    }
  ],
  "cursor": null
}

Get session detail

GET/api/v1/sessions/:id

Full session record including ordered messages and nested interview metadata.

No query parameters.

Request
curl -sS "https://aural-ai.com/api/v1/sessions/SESSION_ID" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "id": "...",
    "status": "COMPLETED",
    "participantName": "Alex",
    "participantEmail": "alex[at]example.com",
    "summary": "Strong system design answers.",
    "insights": ["Clear tradeoff discussion"],
    "themes": ["APIs"],
    "sentiment": "positive",
    "totalDurationSeconds": 1842,
    "createdAt": "2026-04-01T12:00:00.000Z",
    "messages": [
      {
        "id": "...",
        "role": "assistant",
        "content": "Welcome to your interview.",
        "timestamp": "2026-04-01T12:00:05.000Z"
      }
    ],
    "interview": {
      "id": "...",
      "title": "Backend screening",
      "objective": "Assess API design"
    }
  }
}

Candidates

List candidates

GET/api/v1/interviews/:id/candidates

All invite rows for the interview, including tokens and linked session ids when present.

No query parameters.

Request
curl -sS "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/candidates" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": [
    {
      "id": "...",
      "name": "Alex",
      "email": "alex[at]example.com",
      "phone": "+1-555-0100",
      "notes": "Referral from Jane",
      "inviteToken": "...",
      "sessionId": null,
      "createdAt": "2026-04-01T10:00:00.000Z"
    }
  ]
}

Create candidates

POST/api/v1/interviews/:id/candidates

Creates invite rows and returns inviteUrl for each. Accepts one object or up to 500 in an array.

Request Body (per candidate)
namestring
Candidate display name.
emailstring
Contact email.
phonestring
Optional phone number.
notesstring
Internal notes for your team.

If session hours are exhausted for the organization, the API responds with 403, PLAN_LIMIT_EXCEEDED, and limit: "session_hours".

Request
curl -sS -X POST "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/candidates" \
  -H "Authorization: Bearer dlv_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex","email":"alex[at]example.com"}'
Response 200
{
  "data": [
    {
      "id": "...",
      "name": "Alex",
      "email": "alex[at]example.com",
      "inviteToken": "...",
      "inviteUrl": "https://aural-ai.com/i/acme-backend-2025?token=..."
    }
  ]
}

Usage

Organization usage and limits

GET/api/v1/usage

Snapshot of plan label and current consumption for templates, session hours, AI tokens, and seats.

No query parameters.

Request
curl -sS "https://aural-ai.com/api/v1/usage" \
  -H "Authorization: Bearer dlv_KEY"
Response 200
{
  "data": {
    "plan": "pro",
    "templates": { "used": 8, "limit": 25 },
    "session_hours": { "used": 42.5, "limit": 100 },
    "ai_tokens": { "used": 125000, "limit": 500000 },
    "seats": { "used": 5, "limit": 10 }
  }
}

Interpretation of limits, null caps, and quota errors is covered in Usage & Limits.

OpenAPI

Use the OpenAPI spec with codegen or documentation tools to stay in sync as the API evolves.
AuthenticationUsage & Limits