AURAL
For Creators

Quick Start — Developer API Setup Guide

Create an API key, call the REST API, and run through interview setup end to end

From API key to published interview

The Developer API is served under /api/v1 on your Aural deployment (for example https://aural-ai.com/api/v1). For a machine-readable list of operations and schemas, use the OpenAPI document.

1

Create an API key

In the app, open Settings → API Keys, create a key, and copy the secret value (it starts with dlv_). Store it securely; it is shown only once.

2

Make your first authenticated request

Send the key in the Authorization header as a Bearer token. List interviews you can access:

bash
curl -sS "https://aural-ai.com/api/v1/interviews?limit=20" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE"

Successful responses wrap resources in a data field (and may include cursor for pagination).

3

Create an interview

New interviews are created in your first accessible project. At minimum, send a title; other fields are optional.

bash
curl -sS -X POST "https://aural-ai.com/api/v1/interviews" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"title":"Backend screening","voiceEnabled":true,"chatEnabled":true}'

Note the interview id from data for the next steps.

4

Add questions

Attach one or more questions to the interview. You can POST a single object or an array. Types include OPEN_ENDED, SINGLE_CHOICE, MULTIPLE_CHOICE, CODING, WHITEBOARD, and RESEARCH.

bash
curl -sS -X POST "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/questions" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"text":"Describe a recent API you designed.","type":"OPEN_ENDED"}'
5

Publish

Publishing activates the interview and returns a shareable candidate URL (data.url).

bash
curl -sS -X POST "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/publish" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE"
6

Check sessions and results

List completed or in-progress sessions for the interview:

bash
curl -sS "https://aural-ai.com/api/v1/interviews/INTERVIEW_ID/sessions?limit=20" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE"

Fetch one session (summary, insights, messages, etc.) by id from the list:

bash
curl -sS "https://aural-ai.com/api/v1/sessions/SESSION_ID" \
  -H "Authorization: Bearer dlv_YOUR_KEY_HERE"

Feature coverage and additional workflows

The API supports interview context, candidate profiles, invitation emails, session completion, report media, and personal practice results. Textarea resizing and tab draft preservation are browser interactions and do not require API fields.

POST /interviews and PATCH /interviews/{id}
ccSenderOnInviteboolean= true
Enable CC for individual and bulk invitation emails.
inviteCcEmailstring | null
One CC override email; null uses the API key owner's email. Omit on PATCH to retain the saved value.
jobDescriptionstring | null
Interview/practice context. Supply extracted text; null clears, omission on PATCH preserves.
resumeTextstring | null
Interview/practice context. Supply extracted text; null clears, omission on PATCH preserves.
companyNamestring | null
Interview/practice context. Supply extracted text; null clears, omission on PATCH preserves.
roleTitlestring | null
Interview/practice context. Supply extracted text; null clears, omission on PATCH preserves.
bash
curl -sS -X PATCH "$AURAL_BASE_URL/api/v1/interviews/INTERVIEW_ID" \
  -H "Authorization: Bearer $AURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ccSenderOnInvite":true,"inviteCcEmail":"recruiting[at]example.com","companyName":"Example","roleTitle":"Backend Engineer"}'

Set AURAL_BASE_URL to your deployment (http://localhost:3000 for local testing) and AURAL_API_KEY to your key. CC defaults on and is visible to candidates; disabling CC prevents copies even when an override is saved.

Preview and send invitations

POST /interviews/{id}/invites — ids are candidate IDs returned by candidate creation. Creating candidates does not send email.

bash
curl -sS -X POST "$AURAL_BASE_URL/api/v1/interviews/INTERVIEW_ID/invites" \
  -H "Authorization: Bearer $AURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["CANDIDATE_ID"],"dryRun":true}'

Review the preview, then set dryRun to false to send. Each email uses the candidate's personal /i/invite/{token} link and preserves invite-only access. Only unstarted candidates with an email and invite token are eligible.

Preview and end interview sessions

POST /interviews/{id}/sessions/end — Uses the same body, but ids are session IDs. Only IN_PROGRESS sessions are ended, using the app's activity-duration and billing logic. Completion does not generate an AI report.

json
{"ids":["SESSION_ID"],"dryRun":true}

Both bulk endpoints require MEMBER or higher. Supply 1–100 IDs; duplicates are processed once. dryRun defaults to true. Execution rechecks eligibility, so a preview does not reserve records.

json
{"data":{"dryRun":true,"results":[{"id":"CANDIDATE_ID","status":"eligible"},{"id":"OTHER_ID","status":"skipped","reason":"Not eligible"}]}}

HTTP 200 does not mean every item succeeded. Inspect each eligible, skipped, succeeded, or failed status and reason. Batches are not atomic. Email sending is not idempotent: resubmitting a whole batch may resend successful invites. Retry only known failures; investigate uncertain timeouts before resending.

Session list/detail responses include startedAt, completedAt, and lastActivityAt. IN_PROGRESS alone does not mean a participant is currently active.

Reports, media, and practices

  • GET /sessions/{id}/report: Existing summary, insights, messages, antiCheatingLog, audioRecordings, screenshots, and mediaRetention. Signed media URLs expire; fetch fresh URLs when needed. Does not generate missing AI reports.
  • GET /interviews/{id}/practices?limit=100: The key owner's practice summaries; limit is 1–500, with no cursor pagination.
  • GET /practices/{id}: session, interview, questions, and attempts including feedback, scores, and retained answer audio. Only the key owner's own practices are accessible.

Interview time is accounted within the current subscription billing period, excluding idle gaps. Practices do not consume interview session hours, but AI practice operations use AI tokens. Read GET /usage instead of hard-coding plan allowances.

Use the web/mobile app for AI interview generation/refinement, PDF/URL extraction, live voice and microphone controls, practice answer submission/grading, answer-bank editing, recording uploads, and report generation. Those interactions do not have public REST write endpoints. Webhooks and official SDKs are not provided; internal tRPC and voice WebSockets are not stable Developer API contracts.

Next steps

Read Authentication, the API Reference, and Usage & Limits for error codes, quotas, and every endpoint in detail.
Authentication