Tara API¶

Integration guide for the Tara API. Create AI-led interviews, hand the candidate a link, and read back the transcript and evaluation — or register a webhook and have every result pushed to you the moment it's ready.

What you're integrating against

The interview itself runs entirely on Allps servers. Your system's job is to create interview records and consume their results. There is no long-lived session between your backend and Allps during the interview.

Two API surfaces¶

The API is split into two self-contained surfaces, both authenticated with the same credential:

Surface	Base path	Purpose
Interview API	`/interview/*`	Create interviews, read transcripts, evaluations, and recording URLs.
Webhook management API	`/webhooks/*`	Register a URL, receive interview results pushed as they become ready, inspect and replay deliveries.

The two are related only by the interview_id that appears in every payload. Read Lifecycle for how they fit together, and Webhooks if you'd prefer push over poll.

The three-phase lifecycle¶

Every interview moves through three phases. You're in control of the first and the last; the middle happens on Allps.

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  YOUR APP   │     │  Allps API   │     │  CANDIDATE  │
└──────┬──────┘     └──────┬───────┘     └──────┬──────┘
       │                   │                    │
   PHASE 1: SCHEDULE       │                    │
       │                   │                    │
       │  POST /interview/create-from-questions │
       ├──────────────────►│                    │
       │                   │                    │
       │◄──────────────────┤                    │
       │ { interview_id, interview_link }       │
       │                   │                    │
       │                   │                    │
   PHASE 2: DELIVERY       │                    │
       │                   │                    │
       │  (send link to candidate out-of-band)  │
       ├───────────────────────────────────────►│
       │                   │                    │
       │                   │  Interview session │
       │                   │◄──────────────────►│
       │                   │                    │
       │                   │  Transcript + eval │
       │                   │  persisted         │
       │                   │                    │
       │                   │                    │
   PHASE 3: RETRIEVE       │                    │
       │                   │                    │
       │  GET /interview/details/{id}           │
       ├──────────────────►│                    │
       │◄──────────────────┤                    │
       │  state == 2 (ENDED)                    │
       │                   │                    │
       │  GET /interview/transcript/{id}        │
       │  GET /interview/evaluation-report/{id} │
       ├──────────────────►│                    │
       │◄──────────────────┤                    │
       │                   │                    │

Phase 1 — Schedule is synchronous and fast. A single POST returns an interview_id and an interview_link.

Phase 2 — Delivery is asynchronous and outside your control. The candidate may take the interview five minutes or five days after scheduling.

Phase 3 — Retrieve begins once the candidate finishes. You either poll the read endpoints or register a webhook and receive the same data pushed to you.

Quick start¶

Minimum viable integration

Create, share, wait, fetch. Four requests and a webhook that isn't strictly required.

1. Create an interview¶

curlResponse

curl -X POST https://interviews-api.allpsdigital.com/interview/create-from-questions \
  -H "x-application-secret-key: sk_int_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "Senior Backend Engineer",
    "candidate_id": "your-internal-candidate-id",
    "language_code": 1,
    "experience_level": "senior",
    "difficulty_level": "medium",
    "primary_tech_focus": "Distributed Systems",
    "questions": [
      {
        "question": "Walk me through how you would design a rate limiter.",
        "evaluation_criteria": [
          "Mentions token bucket or sliding window",
          "Considers distributed state"
        ],
        "type": "technical"
      }
    ]
  }'

{
  "message": "Interview created successfully",
  "interview_id": "0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b",
  "interview_link": "https://interviews.allps.ai/interview?iid=0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
}

2. Hand the link to the candidate¶

Send interview_link over whatever channel your product uses. The candidate needs a modern browser and a microphone — nothing else.

3. Wait for the interview to end¶

Either poll until state == 2 (ENDED), or register a webhook and skip the polling entirely. Both paths are described in Lifecycle → Phase 3.

4. Fetch the artefacts¶

curl https://interviews-api.allpsdigital.com/interview/transcript/0f2b8c6e-… \
  -H "x-application-secret-key: sk_int_your_key_here"

curl https://interviews-api.allpsdigital.com/interview/evaluation-report/0f2b8c6e-… \
  -H "x-application-secret-key: sk_int_your_key_here"

Where to go next¶

:material-timer-outline: Lifecycle The three phases in detail — how to create each kind of interview, what the candidate sees, and the two retrieval strategies.
:material-webhook: Webhooks Register a delivery URL, verify the HMAC signature, and understand the payload contract for every interview kind.
:material-book-open-variant: Reference Authentication, enums, error codes, idempotency rules, and the pre-launch integration checklist.
:material-api: API Reference The rendered OpenAPI specification — every endpoint, every field, every response schema.