Endpoints

Complete reference for all InsightAgent API endpoints.

Interviews

List Interviews

GET /api/interviews

Query parameters (optional):

Parameter

Type

Description

page

number

Page number (1-indexed)

limit

number

Results per page (max: 100)

status

string

Filter by status: NOT_SCHEDULED, SCHEDULED, IN_PROGRESS, COMPLETED

search

string

Search by interview title or expert name (case-insensitive)

Note: The IN_PROGRESS status filter also includes interviews with DIALING status.

When page and limit are provided, returns paginated response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Without pagination parameters, returns a plain array of interviews.

Get Interview

GET /api/interviews/{id}

Returns the full interview details including sessions with media URLs and AI-generated analysis.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Technical Interview",
  "interviewType": "FULL_INTERVIEW",
  "status": "COMPLETED",
  "questions": ["Tell me about your experience..."],
  "expertData": {
    "name": "John Doe",
    "title": "Senior Engineer",
    "employmentHistory": [...]
  },
  "scheduledAt": "2024-12-01T10:00:00.000Z",
  "completedAt": "2024-12-01T10:45:00.000Z",
  "totalConversationSeconds": 2700,
  "sessionCount": 1,
  "summary": "The interview covered the candidate's extensive experience in distributed systems...",
  "quotes": [
    {
      "quote": "The key to scaling is understanding your bottlenecks before they become problems",
      "speaker": "expert",
      "context": "Discussing approach to system design",
      "timestamp_secs": 342
    }
  ],
  "analysisGeneratedAt": "2024-12-01T11:00:00.000Z",
  "sessions": [
    {
      "id": "session-uuid",
      "startedAt": "2024-12-01T10:00:00.000Z",
      "endedAt": "2024-12-01T10:45:00.000Z",
      "durationSeconds": 2700,
      "isActive": true,
      "isProcessed": true,
      "audioUrl": "https://storage.example.com/signed-audio-url",
      "transcriptUrl": "https://storage.example.com/signed-transcript-url"
    }
  ],
  "resolvedAgent": {
    "id": "agent-uuid",
    "name": "Technical Interview Agent",
    "agentType": "FULL_INTERVIEW"
  }
}

Analysis Fields

Field

Type

Description

summary

string | null

AI-generated executive summary of the interview

quotes

array | null

Notable quotes extracted from the expert's responses

quotes[].quote

string

Exact verbatim quote from the transcript

quotes[].speaker

string

Always expert (agent quotes are filtered out)

quotes[].context

string

Why this quote is significant

quotes[].timestamp_secs

number

Timestamp in seconds

analysisGeneratedAt

string | null

ISO8601 datetime when analysis was generated

Analysis is automatically generated when an interview completes. Fields are null for interviews that haven't been analyzed yet.

The sessions array contains all interview sessions with signed media URLs (valid for 1 hour). Use the convenience endpoints below for simpler access to the primary session's media.

Create Interview

POST /api/interviews

Body:

{
  "interviewType": "FULL_INTERVIEW | VETTING_INTERVIEW (required)",
  "title": "string (required)",
  "callSubject": "string (required)",
  "expertData": {
    "name": "string (required)",
    "title": "string (required)",
    "employmentHistory": [
      {
        "title": "string (required)",
        "company": "string (required)",
        "period": "string"
      }
    ]
  },
  "questions": ["string"] (at least one required),
  "scheduledAt": "ISO8601 datetime (optional)",
  "dialInPhone": "string",
  "meetingId": "string",
  "dialInPin": "string",
  "compliance": "string",
  "customVariables": {
    "company_background": "string",
    "research_focus": "string"
  }
}

Required fields:

interviewType - Must be FULL_INTERVIEW or VETTING_INTERVIEW
title - Interview title
callSubject - Subject/topic for the call
questions - Array with at least one question
expertData.name - Expert's full name
expertData.title - Expert's job title
expertData.employmentHistory - At least one employment entry
expertData.employmentHistory[].title - Job title for each employment entry
expertData.employmentHistory[].company - Company name for each employment entry

Custom Variables:

customVariables - Key-value pairs for agent prompt variables
Required variables (defined in Settings → Variables) must be provided
Returns 400 MISSING_REQUIRED_VARIABLES error if required variables are missing

Update Interview

PUT /api/interviews/{id}

Delete Interview

DELETE /api/interviews/{id}

Get Transcription

GET /api/interviews/{id}/transcription

Returns the transcript from the primary session as an array of entries:

[
  {
    "role": "agent | user",
    "message": "string",
    "timestamp_secs": number
  }
]

For interviews with multiple sessions, use the sessions array from the Get Interview endpoint to access individual session transcripts via their transcriptUrl.

Get Live Transcript

GET /api/interviews/{id}/transcript/live

Returns cached transcript events for an in-progress interview. Use this to observe the conversation in real-time.

Response:

{
  "events": [
    {
      "type": "agent",
      "text": "Hello, thank you for joining today's interview.",
      "timestamp": "2026-01-26T10:00:05.000Z",
      "sessionId": "session-uuid"
    },
    {
      "type": "user",
      "text": "Thanks for having me.",
      "timestamp": "2026-01-26T10:00:12.000Z",
      "sessionId": "session-uuid"
    }
  ]
}

Notes:

Available for interviews with status IN_PROGRESS or COMPLETED (during processing)
Returns 400 if interview is not in progress
Events are cached temporarily during the interview

Get Audio

GET /api/interviews/{id}/audio

Returns a signed URL for the audio recording from the primary session.

Response:

{
  "url": "https://storage.example.com/signed-audio-url",
  "expiresIn": 3600
}

The signed URL is valid for 1 hour. For interviews with multiple sessions, use the sessions array from the Get Interview endpoint to access individual session recordings.

Get Interview Stats

GET /api/interviews/stats

Returns aggregate counts of interviews by status for the current account.

Response:

{
  "notScheduled": 5,
  "scheduled": 12,
  "inProgress": 2,
  "completed": 87,
  "total": 106,
  "abandoned": 1
}

Field

Description

notScheduled

Interviews created but not yet scheduled

scheduled

Interviews scheduled for a future time

inProgress

Interviews currently active (includes DIALING status)

completed

Finished interviews

total

Total interview count

abandoned

In-progress interviews with no activity for 5+ minutes

AI Agents

List Agents

GET /api/agents

Returns all agents available to the current account, including system default agents and custom agents.

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Technical Interview Agent",
    "agentType": "FULL_INTERVIEW",
    "language": "en",
    "agentPersonaName": "Riley",
    "firstMessage": "Hello! Can you hear me well?",
    "customPrompt": "# Goal\nConduct thorough technical interviews...",
    "description": "Custom agent for senior engineering interviews",
    "isDefault": false,
    "versionNumber": 3,
    "createdAt": "2025-12-06T20:04:24.513Z",
    "updatedAt": "2025-12-08T11:10:44.837Z"
  }
]

Get Agent

GET /api/agents/{id}

Retrieve a specific agent configuration by its unique identifier.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Interview Agent",
  "agentType": "FULL_INTERVIEW",
  "language": "en",
  "agentPersonaName": "Riley",
  "firstMessage": "Hello! Can you hear me well?",
  "customPrompt": "# Goal\nConduct thorough technical interviews...",
  "description": "Custom agent for senior engineering interviews",
  "isDefault": false,
  "versionNumber": 3,
  "createdAt": "2025-12-06T20:04:24.513Z",
  "updatedAt": "2025-12-08T11:10:44.837Z"
}

Create Agent

POST /api/agents

Body:

{
  "name": "string (required)",
  "agentType": "FULL_INTERVIEW | VETTING_INTERVIEW (required)",
  "language": "string (required, ISO 639-1 code)",
  "agentPersonaName": "string (optional)",
  "customPrompt": "string (optional, max 10000 chars)",
  "description": "string (optional, max 500 chars)",
  "firstMessage": "string (optional)"
}

Supported languages: en, es, fr, de, it, pt, pl, hi, zh, ko, ru, nl, tr, sv, id, fil, ja, uk, el, cs, fi, ro, da, bg, ms, sk, hr, ar, ta, vi, hu, no

Returns 202 Accepted - agent creation is asynchronous and creates both PHONE and WEB platform versions.

Update Agent

PUT /api/agents/{id}

Update an existing agent's configuration. Creates a new version in the agent's history.

Delete Agent

DELETE /api/agents/{id}

Soft delete an agent (marked as inactive, not permanently removed).

Activate Agent

POST /api/agents/{id}/activate

Set an agent as the default for its type (affects both PHONE and WEB platforms).

Get Agent Variables

GET /api/agents/{id}/variables

Returns variables used by an agent's prompt, with their definitions and requirements.

Response:

[
  {
    "name": "company_background",
    "displayName": "Company Background",
    "description": "Context about the target company",
    "isRequired": true,
    "defaultValue": null
  },
  {
    "name": "research_focus",
    "displayName": "Research Focus",
    "description": "Specific area to explore",
    "isRequired": false,
    "defaultValue": "general market research"
  }
]

Variables

Manage custom variables for agent prompts.

List Variables

GET /api/account/variables

Returns all custom variables defined for your account.

Response:

{
  "variables": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "company_background",
      "displayName": "Company Background",
      "description": "Context about the target company",
      "isRequired": true,
      "defaultValue": null,
      "usedByAgents": ["Technical Interview Agent"],
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}

Create Variable

POST /api/account/variables

Body:

{
  "name": "string (required)",
  "displayName": "string (required)",
  "description": "string (optional)",
  "isRequired": false,
  "defaultValue": "string (optional)"
}

Variable name rules:

Must start with a letter (a-z, A-Z)
Can contain letters, numbers, and underscores
Must be unique within the account

Response: 201 Created with the created variable.

Error responses:

400 INVALID_VARIABLE_NAME - Name doesn't meet format requirements
409 VARIABLE_NAME_EXISTS - A variable with this name already exists

Get Variable

GET /api/account/variables/{id}

Returns a specific variable with its agent usage information.

Update Variable

PUT /api/account/variables/{id}

Body:

{
  "displayName": "string (optional)",
  "description": "string (optional)",
  "isRequired": false,
  "defaultValue": "string (optional)"
}

Notes:

The name field cannot be changed after creation
isRequired can only be changed from true to false (not vice versa)

Error responses:

400 CANNOT_MAKE_VARIABLE_REQUIRED - Cannot change optional variable to required
404 - Variable not found

Delete Variable

DELETE /api/account/variables/{id}

Deletes a variable. Variables currently used by agent prompts cannot be deleted.

Error responses:

400 VARIABLE_IN_USE - Variable is referenced in agent prompts (includes list of agents)
404 - Variable not found

Auth

Get Current User

GET /api/auth/me

Returns the authenticated user's profile and account information.

Response:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fullName": "John Doe",
    "accountId": "660e8400-e29b-41d4-a716-446655440001",
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "account": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Acme Corp",
    "status": "ACTIVE",
    "billingType": "MANUAL_INVOICE"
  }
}

Webhooks (Post-Interview)

Configure webhooks to receive notifications after interviews complete:

Webhook Payload

{
  "event": "interview.completed",
  "timestamp": "2024-12-01T00:00:00Z",
  "data": {
    "interviewId": "...",
    "status": "COMPLETED"
  }
}

Webhook subscriptions are configured per interview via the postNotifications field.

PreviousAuthentication NextWhat's New

Last updated 8 days ago

Good afternoon

hashtagInterviews

hashtagList Interviews

hashtagGet Interview

hashtagAnalysis Fields

hashtagCreate Interview

hashtagUpdate Interview

hashtagDelete Interview

hashtagGet Transcription

hashtagGet Live Transcript

hashtagGet Audio

hashtagGet Interview Stats

hashtagAI Agents

hashtagList Agents

hashtagGet Agent

hashtagCreate Agent

hashtagUpdate Agent

hashtagDelete Agent

hashtagActivate Agent

hashtagGet Agent Variables

hashtagVariables

hashtagList Variables

hashtagCreate Variable

hashtagGet Variable

hashtagUpdate Variable

hashtagDelete Variable

hashtagAuth

hashtagGet Current User

hashtagWebhooks (Post-Interview)

hashtagWebhook Payload

Interviews

List Interviews

Get Interview

Analysis Fields

Create Interview

Update Interview

Delete Interview

Get Transcription

Get Live Transcript

Get Audio

Get Interview Stats

AI Agents

List Agents

Get Agent

Create Agent

Update Agent

Delete Agent

Activate Agent

Get Agent Variables

Variables

List Variables

Create Variable

Get Variable

Update Variable

Delete Variable

Auth

Get Current User

Webhooks (Post-Interview)

Webhook Payload