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"

Next steps

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