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),
  "status": "NOT_SCHEDULED | SCHEDULED (optional)",
  "scheduledAt": "ISO8601 datetime (optional)",
  "dialInPhone": "string",
  "meetingId": "string",
  "dialInPin": "string",
  "agentGroupId": "uuid (optional)",
  "compliance": "string",
  "customVariables": {
    "company_background": "string",
    "research_focus": "string"
  },
  "notifications": [
    {
      "endpoint": "https://your-server.com/webhook",
      "attributes": {
        "method": "POST",
        "headers": { "Authorization": "Bearer your-token" }
      }
    }
  ]
}

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

Status:

status - Explicitly set the interview status to NOT_SCHEDULED or SCHEDULED. If omitted, status is derived from scheduledAt (set → SCHEDULED, omitted → NOT_SCHEDULED).

Agent Selection:

agentGroupId - UUID of the agent group to use for this interview. Get available agent group IDs from GET /api/agents. If omitted, the account's default agent for the given interviewType is used.

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

Webhooks:

notifications - Array of webhook subscriptions to notify when the interview completes. See Webhooks for full details.

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

API Keys

Manage API keys for programmatic access. All endpoints require authentication via Bearer token.

List API Keys

GET /api/api-keys

Returns all API keys for the authenticated user.

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production",
    "maskedKey": "sk_live_a1b2c3d4...",
    "prefix": "a1b2c3d4",
    "createdAt": "2026-02-15T10:00:00.000Z",
    "revokedAt": null
  }
]

Create API Key

POST /api/api-keys

Body:

{
  "name": "string (required)"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production",
  "key": "sk_live_a1b2c3d4e5f6...",
  "createdAt": "2026-02-15T10:00:00.000Z"
}

The full API key is returned only once at creation time. Store it securely.

Error responses:

400 — Name is required, or maximum of 5 active keys reached

Rename API Key

PATCH /api/api-keys/{id}

Body:

{
  "name": "string (required)"
}

Error responses:

400 — Name is required
404 — API key not found

Revoke API Key

DELETE /api/api-keys/{id}

Revokes the key immediately. Any requests using this key will be rejected.

Error responses:

404 — API key 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)

Receive a notification when an interview completes. Webhooks are configured per interview via the notifications field in the Create Interview request.

Setup

Add a notifications array when creating an interview:

{
  "title": "Technical Interview",
  "interviewType": "FULL_INTERVIEW",
  "notifications": [
    {
      "endpoint": "https://your-server.com/webhook",
      "attributes": {
        "method": "POST",
        "headers": {
          "Authorization": "Bearer your-token",
          "x-custom-header": "value"
        }
      }
    }
  ]
}

Field

Type

Description

endpoint

string

The URL to receive the webhook POST

attributes.method

string

HTTP method (defaults to POST)

attributes.headers

object

Custom headers sent with each request

You can configure multiple webhook endpoints per interview.

Webhook Payload

When the interview completes, each configured endpoint receives:

{
  "interviewId": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "completedAt": "2026-02-17T15:30:00.000Z",
  "transcriptionUrl": "https://api.insightagent.io/api/interviews/{id}/transcription",
  "audioUrl": "https://api.insightagent.io/api/interviews/{id}/audio"
}

Field

Type

Description

interviewId

string

UUID of the completed interview

success

boolean

Whether the interview completed successfully

completedAt

string

ISO8601 timestamp of completion

transcriptionUrl

string

URL to fetch the full transcript (requires API key)

audioUrl

string

URL to fetch the audio recording (requires API key)

The payload is sent as Content-Type: application/json.

Authentication

There is no platform-level request signing (HMAC, etc.) at this time. To secure your webhook endpoint, pass your own authentication headers via attributes.headers — these are included with every webhook request.

Retries

Webhooks are attempted once. If your endpoint is unreachable or returns an error, the notification is marked as failed with no automatic retry. We recommend ensuring high availability on your receiving endpoint, or polling GET /api/interviews/{id} as a fallback.

PreviousAuthentication NextWhat's New

Last updated 1 month ago

Good morning

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

hashtagAPI Keys

hashtagList API Keys

hashtagCreate API Key

hashtagRename API Key

hashtagRevoke API Key

hashtagAuth

hashtagGet Current User

hashtagWebhooks (Post-Interview)

hashtagSetup

hashtagWebhook Payload

hashtagAuthentication

hashtagRetries

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

API Keys

List API Keys

Create API Key

Rename API Key

Revoke API Key

Auth

Get Current User

Webhooks (Post-Interview)

Setup

Webhook Payload

Authentication

Retries