API Reference

Interviews

Create and manage interview records — CRUD endpoints with multi-tenant isolation.

Interview endpoints handle the full lifecycle of an interview record: creation, retrieval, status updates, plan management, and assessment access. All endpoints require JWT authentication and automatically scope results to the caller's tenant.

Endpoints

Method	Endpoint	Permission	Description
POST	/interviews	interview:create	Create internal interview (non-A2A)
GET	/interviews	interview:read	List interviews with pagination
GET	/interviews/:id	interview:read	Get single interview
PUT	/interviews/:id	interview:update	Update interview fields
DELETE	/interviews/:id	interview:delete	Delete interview record
GET	/interviews/:id/plan	interview:read	Get AI-generated plan
GET	/interviews/:id/assessment	interview:read	Get AI assessment
GET	/interviews/:runId/status	interview:read	Get workflow status by runId

POST /interviews

Create an interview directly (bypasses A2A protocol). Used by the admin dashboard when creating interviews internally.

bash

curl -X POST http://localhost:3009/api/v1/interviews \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateName": "Jane Smith",
    "candidateEmail": "jane@example.com",
    "position": "Senior Engineer",
    "level": "SENIOR",
    "skills": ["TypeScript", "React", "Node.js"],
    "jobDescription": "Build scalable platform services with modern tooling.",
    "scheduledAt": "2024-02-01T10:00:00.000Z"
  }'

Response 201

{
  "id": "interview-uuid",
  "candidateName": "Jane Smith",
  "candidateEmail": "jane@example.com",
  "position": "Senior Engineer",
  "level": "SENIOR",
  "skills": ["TypeScript", "React", "Node.js"],
  "workflowState": "RECEIVED",
  "tenantId": "tenant-uuid",
  "createdAt": "2024-01-15T10:00:00.000Z"
}

GET /interviews

List all interviews for the authenticated tenant. Supports filtering by state and pagination.

bash

# List all interviews
curl http://localhost:3009/api/v1/interviews \
  -H "Authorization: Bearer <jwt>"

# Filter by state with pagination
curl "http://localhost:3009/api/v1/interviews?state=PENDING&page=1&limit=20" \
  -H "Authorization: Bearer <jwt>"

Query Param	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	20	Items per page (max 100)
state	string	-	Filter by workflow state

Response 200

{
  "data": [
    {
      "id": "interview-uuid",
      "candidateName": "Jane Smith",
      "position": "Senior Engineer",
      "workflowState": "PENDING",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

GET /interviews/:id

Returns the full interview record including all fields.

bash

curl http://localhost:3009/api/v1/interviews/interview-uuid \
  -H "Authorization: Bearer <jwt>"

Response 200

{
  "id": "interview-uuid",
  "tenantId": "tenant-uuid",
  "candidateName": "Jane Smith",
  "candidateEmail": "jane@example.com",
  "position": "Senior Engineer",
  "level": "SENIOR",
  "skills": ["TypeScript", "React", "Node.js"],
  "jobDescription": "Build scalable platform services...",
  "workflowState": "PENDING",
  "runId": "agno-run-uuid",
  "planId": "plan-uuid",
  "callbackUrl": "https://ats.example.com/webhook",
  "scheduledAt": null,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:45:00.000Z"
}

GET /interviews/:id/plan

Returns the AI-generated interview plan. Only available when workflowState is PENDING or later.

bash

curl http://localhost:3009/api/v1/interviews/interview-uuid/plan \
  -H "Authorization: Bearer <jwt>"

Response 200

{
  "id": "plan-uuid",
  "interviewId": "interview-uuid",
  "structure": {
    "duration": 60,
    "sections": [
      {
        "name": "Technical Assessment",
        "duration": 40,
        "topics": ["TypeScript patterns", "React architecture", "API design"]
      },
      {
        "name": "System Design",
        "duration": 15,
        "topics": ["Scalability", "Database modeling"]
      },
      {
        "name": "Cultural Fit",
        "duration": 5,
        "topics": ["Team collaboration", "Problem-solving approach"]
      }
    ]
  },
  "createdAt": "2024-01-15T10:45:00.000Z"
}

GET /interviews/:id/assessment

Returns the AI-generated assessment. Only available after COMPLETED state.

Response 200

{
  "id": "assessment-uuid",
  "interviewId": "interview-uuid",
  "overallScore": 82,
  "recommendation": "STRONG_HIRE",
  "summary": "Jane demonstrated exceptional TypeScript skills and clear system design thinking.",
  "scores": {
    "technical": {
      "typescript_proficiency": 4,
      "system_design": 4,
      "problem_solving": 5
    },
    "communication": {
      "clarity": 4,
      "structure": 4
    }
  },
  "transcript": "...",
  "createdAt": "2024-01-15T12:30:00.000Z"
}

Error Responses

404 Not Found

json

{
  "statusCode": 404,
  "message": "Interview not found"
}

403 Forbidden

json

{
  "statusCode": 403,
  "message": "Insufficient permissions. Required: interview:read"
}

Interviews created via the A2A endpoint (POST /a2a/interview) are also accessible via these endpoints using their id.

Was this page helpful?

Previous← Authentication

NextCandidate Access →