Skip to main content
GET
/
agents
List agents
curl --request GET \
  --url https://api.instaview.sk/agents \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "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",
      "voiceId": "ALEX",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "cefrLevel": "B1"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}
Lists all agents (interview templates) for the API key’s company with pagination support.

​
Overview

The list agents endpoint allows you to retrieve all available AI interview agents in your company. This is useful for finding existing agents before creating interviews, managing agent configurations, and auditing your agent library.

​
Use Cases

  • Find Existing Agents: Locate agents before scheduling interviews
  • Agent Management: Review and audit all configured agents
  • Bulk Operations: Retrieve agents for bulk interview scheduling
  • Agent Discovery: Browse available agents by type or purpose

​
Basic Usage

// List all agents (first page, 20 items)
GET /agents

​
With Pagination

// Get specific page
GET /agents?page=2&limit=50

// Response includes pagination metadata
{
  "data": {
    "items": [...],
    "pagination": {
      "total": 25,
      "page": 2,
      "limit": 50,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": true
    }
  }
}

​
Finding Agents for Interviews

async function findAgentForInterview(interviewType) {
  const response = await fetch("https://api.instaview.sk/agents", {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });

  const { data } = await response.json();

  // Filter agents by interview type
  return data.items.filter((agent) => agent.type === interviewType);
}

// Find technical screening agents
const technicalAgents = await findAgentForInterview("technical");

​
Company Scoping

All returned agents belong to your API key’s company. ATS keys can filter by companyId to access agents from specific companies they manage.

Agents Resource Guide

Learn about agent configuration and best practices

Create Agent

Create new interview agents

Pagination Guide

Understand pagination best practices

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
page
integer
default:1

Page number (1-based)

Required range: 1 <= x <= 10000
Example:

1

​
limit
integer
default:20

Number of items per page

Required range: 1 <= x <= 100
Example:

20

​
companyId
string<uuid>

Filter agents by company ID. If omitted, defaults to the API key's company.

Example:

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

Response

200 - application/json
​
data
object[]
required

Array of agents

​
total
number
required

Total number of items

Example:

150

​
page
number
required

Current page number

Example:

1

​
limit
number
required

Number of items per page

Example:

20

​
totalPages
number
required

Total number of pages

Example:

8