Skip to main content
GET
/
agents
/
{id}
Get agent by ID
curl --request GET \
  --url https://api.instaview.sk/agents/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Frontend Developer Interview",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "createdAt": "2025-11-20T10:30:00Z",
  "updatedAt": "2025-11-20T10:30:00Z",
  "questions": [
    "What is your experience with React?"
  ],
  "instructions": "Focus on technical skills and previous project experience",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Sales"
  },
  "cefrLevel": "B1",
  "backgroundSound": "OFFICE"
}
Retrieves a specific agent (interview template) by ID, including all configuration details, questions, and evaluation criteria.

​
Overview

The get agent endpoint returns complete information about a single agent, including its name, description, voice settings, interview type, questions, and evaluation criteria. Use this endpoint to review agent configuration before using it in interviews.

​
Use Cases

  • Review Agent Configuration: Inspect agent settings before scheduling interviews
  • Validate Agent Details: Verify questions and evaluation criteria
  • Agent Auditing: Review agent configurations for compliance
  • Configuration Reference: Get agent details for documentation or reporting

​
Response Data

The response includes all agent configuration: 
{
  "id": "agent-uuid",
  "name": "Technical Screening Agent",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "questions": [
    "Tell me about your React experience",
    "Explain microservices architecture"
  ],
  "instructions": "Focus on technical depth and accuracy, problem-solving approach",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-20T14:30:00Z"
}

​
When to Use

Use this endpoint when you need complete agent details. For listing multiple agents, use the List Agents endpoint instead.

​
Company Isolation

You can only access agents that belong to your API key’s company. Attempting to access an agent from another company will result in a 403 Forbidden error.

​
Error Scenarios

  • 404 Not Found: Agent doesn’t exist or has been deleted
  • 403 Forbidden: Agent belongs to a different company

Agents Resource Guide

Learn about agent configuration

Update Agent

Modify agent configuration

List Agents

Browse all available agents

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

​
id
string<uuid>
required

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
​
id
string<uuid>
required

Agent ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
name
string
required

Agent name

Example:

"Frontend Developer Interview"

​
type
enum<string>
required

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>
required

Focus of the agent. GENERIC: For jobless interviews where candidates don't need job assignments. SCREENING: Initial candidate screening and assessment. OUTREACH: Candidate outreach and engagement. LANGUAGE_TEST: Language proficiency assessment.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

​
language
enum<string>
required

Language of the interview

Available options:
UNDEFINED,
EN,
JA,
ZH,
DE,
HI,
FR,
KO,
PT,
IT,
ES,
ID,
NL,
TR,
FIL,
PL,
SV,
BG,
RO,
AR,
CS,
EL,
FI,
HR,
MS,
SK,
DA,
TA,
UK,
RU,
HU,
NO,
VI
Example:

"EN"

​
duration
number
required

Duration of the interview in minutes

Example:

30

​
createdAt
string<date-time>
required

Agent creation timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
updatedAt
string<date-time>
required

Agent last update timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
questions
string[]

List of questions for the interview

Example:
["What is your experience with React?"]
​
instructions
string

Additional instructions for the interview

Example:

"Focus on technical skills and previous project experience"

​
voiceId
enum<string>

Voice ID for the AI interview

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
​
companyId
string<uuid>

Company ID that owns the agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
metadata
object

Custom metadata

Example:
{ "department": "Sales" }
​
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

​
backgroundSound
enum<string> | null

Ambient background sound during calls (OFFICE or OFF). Null means no override is set and the default applies.

Available options:
OFF,
OFFICE
Example:

"OFFICE"