Get Started

Quick Start

Create your first AI interview in under 5 minutes.

This guide walks you through creating an interview, handling the HITL approval flow, and receiving webhooks — from zero to a live candidate interview link.

Prerequisites

Item	Value
API Base URL	http://localhost:3009/api/v1
Admin email	admin@demo.ai-interview.com
Admin password	Admin123!
Demo API key	demo_api_key_12345678901234567890123456789012345678901234567890123456

Step 1 — Get an Access Token

Authenticate with the admin credentials to obtain a JWT. You can use this token or use the demo API key directly for A2A endpoints.

bash

curl -X POST http://localhost:3009/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@demo.ai-interview.com","password":"Admin123!"}'

Response 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid",
    "email": "admin@demo.ai-interview.com",
    "role": "ADMIN"
  }
}

Step 2 — Create an Interview

Submit a complete interview request via the A2A endpoint. Providing all required fields ensures the system skips the INFO_NEEDED state and proceeds directly to skill validation.

bash

curl -X POST http://localhost:3009/api/v1/a2a/interview \
  -H "X-API-Key: demo_api_key_12345678901234567890123456789012345678901234567890123456" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateName": "Jane Smith",
    "candidateEmail": "jane@example.com",
    "position": "Senior Software Engineer",
    "level": "SENIOR",
    "skills": ["TypeScript", "React", "Node.js", "PostgreSQL"],
    "jobDescription": "Join our platform team to build scalable web applications with a modern tech stack. You will architect and own key services.",
    "callbackUrl": "https://your-ats.example.com/webhook"
  }'

Response 201 — data complete

{
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "VALIDATING_SKILLS",
  "message": "Interview request accepted. Skill validation in progress.",
  "dataQuality": "EXCELLENT"
}

Save the runId — you need it for polling status and submitting the plan approval.

Step 3 — Receive Plan Webhook

When the Agno Planner Agent finishes generating the interview plan, the system sends a webhook to your callbackUrl.

Incoming webhook POST

{
  "event": "interview.plan_generated",
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "PENDING",
  "timestamp": "2024-01-15T10:45:00.000Z",
  "data": {
    "planId": "plan-uuid"
  }
}

Alternatively, poll status while waiting:

bash

curl http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/status \
  -H "X-API-Key: demo_api_key_..."

Step 4 — Approve the Plan

Once the state is PENDING, a recruiter reviews the plan in the admin dashboard at /admin/approvals or via the API:

bash

curl -X POST http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/approve \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "userId": "recruiter-user-uuid"
  }'

Response 200

{
  "message": "Interview plan approved. Candidate link generated.",
  "workflowState": "APPROVED",
  "interviewLink": "https://app.ai-interview.com/interview/join/abc123token"
}

Step 5 — Candidate Joins

Send the interviewLink to the candidate. They follow the OTP verification and device check flow before joining the live interview.

text

1. Candidate opens /interview/join/<token>
2. Verifies identity via OTP sent to their email
3. Completes device pre-check (camera + microphone)
4. Joins live interview session via WebSocket

Full Workflow Summary

Step	Actor	Action	State After
1	External ATS	POST /a2a/interview	VALIDATING_SKILLS
2	Agno Agent	Generate plan	PENDING
3	Recruiter	Review + approve plan	APPROVED
4	Candidate	Join via interview link	IN_PROGRESS
5	Agno Agent	Conduct + assess interview	ASSESSMENT_PENDING
6	Recruiter	Approve assessment	ASSESSMENT_APPROVED

See the HITL Workflow guide for handling the INFO_NEEDED state when data is incomplete.

Was this page helpful?

Previous← Introduction

NextOverview →