InsightAgent

https://docs.insightagent.io
Admin
AI-powered platform for conducting and managing expert interviews with real-time voice interaction,...
Tokens:30,224
Snippets:340
Trust Score:3.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Agent Response

Source: https://docs.insightagent.io/api-reference/endpoints

Example response for a single agent's detailed configuration.

```JSON
{
  "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",
  "role": "ROOT",
  "voiceId": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f",
  "isDefault": false,
  "versionNumber": 3,
  "createdAt": "2025-12-06T20:04:24.513Z",
  "updatedAt": "2025-12-08T11:10:44.837Z"
}
```

--------------------------------

### Prompt Boundary Example

Source: https://docs.insightagent.io/product-guides/agents/prompts

Provides an example of how to instruct the AI on handling specific edge cases, such as inquiries about pricing.

```text
If asked about pricing, politely explain that a sales  
representative will follow up with that information.  

```

--------------------------------

### Prompt Pace Example

Source: https://docs.insightagent.io/product-guides/agents/prompts

Guides the AI on managing the pace of the conversation and response length.

```text
After each expert response, pause briefly before responding.  
Keep your responses under 3 sentences when possible.  

```

--------------------------------

### Get Agent Variables Response

Source: https://docs.insightagent.io/api-reference/endpoints

Example response detailing agent variables, their display names, descriptions, and whether they are required.

```JSON
[
  {
    "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"
  }
]
```

--------------------------------

### List Agents Response

Source: https://docs.insightagent.io/api-reference/endpoints

Example response showing a list of agents with their configurations.

```JSON
[
  {
    "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",
    "role": "ROOT",
    "voiceId": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f",
    "isDefault": false,
    "versionNumber": 3,
    "createdAt": "2025-12-06T20:04:24.513Z",
    "updatedAt": "2025-12-08T11:10:44.837Z"
  }
]
```

--------------------------------

### Example AI Interview Agent Prompt

Source: https://docs.insightagent.io/product-guides/agents/prompts

Use this prompt structure to guide the AI in conducting a market research interview. It includes placeholders for dynamic content like expert and client names, and interview questions.

```text
You are conducting a market research interview with {{expert_name}}  
about their experience at {{client_name}}.  
  
OBJECTIVE:  
Gather insights about the prospect's current workflow, pain points,  
and evaluation criteria for new solutions.  
  
APPROACH:  
- Start with rapport-building questions  
- Listen actively and ask clarifying follow-ups  
- Dig deeper when you hear interesting points  
- Keep responses concise  
- Summarize key points periodically  
  
FOCUS AREAS:  
{{questions_list}}  
  
CONSTRAINTS:  
- Never discuss pricing or make commitments  
- Don't speak for more than 30 seconds at a time  
- Stay on topic - redirect politely if needed  

```

--------------------------------

### API Key Authentication

Source: https://docs.insightagent.io/api-reference/authentication

Include your API key in the `x-api-key` header for authentication. This example shows how to make a GET request to the /api/interviews endpoint.

```APIDOC
## GET /api/interviews

### Description
Retrieves a list of interviews. Requires API key authentication.

### Method
GET

### Endpoint
/api/interviews

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your API key for authentication.

### Request Example
```curl
curl -X GET "https://api.insightagent.io/api/interviews" \
  -H "x-api-key: <your-api-key>"
```

### Response
#### Success Response (200)
(Response structure not detailed in source)

#### Error Responses
- **400 Bad Request**: Missing Authentication Headers.
  ```json
  {
    "error": "Missing authentication headers, provide either an x-api-key or a Authorization header"
  }
  ```
- **401 Unauthorized**: Invalid Credentials.
  ```json
  {
    "error": "Invalid authentication headers"
  }
  ```
```

--------------------------------

### Prompt Specificity Example

Source: https://docs.insightagent.io/product-guides/agents/prompts

Illustrates how to make prompts more effective by being specific about the information the AI should gather.

```text
// Less effective  
Ask about their job  
  
// More effective  
Ask about their specific responsibilities in evaluating  
and purchasing software solutions  

```

--------------------------------

### Setup Webhook

Source: https://docs.insightagent.io/api-reference/endpoints

Configures webhook notifications for an interview. This involves adding a `notifications` array to the interview creation payload.

```APIDOC
### Setup Webhook

Add a `notifications` array when creating an interview:

### Request Body Example
```json
{
  "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"
        }
      }
    }
  ]
}
```

#### Parameters
- **endpoint** (string) - Required - The URL to receive the webhook POST.
- **attributes.method** (string) - Optional - HTTP method (defaults to `POST`).
- **attributes.headers** (object) - Optional - Custom headers sent with each request.

You can configure multiple webhook endpoints per interview.
```

--------------------------------

### Prompt Edge Case Handling Example

Source: https://docs.insightagent.io/product-guides/agents/prompts

Shows how to instruct the AI to handle situations where the expert seems rushed or goes off-topic.

```text
If the expert seems rushed, offer to schedule a follow-up.  
If they go off-topic, gently redirect with "That's interesting,  
and I'd love to hear more about [original topic]..."  

```

--------------------------------

### Get Audio Recording URL

Source: https://docs.insightagent.io/api-reference/endpoints

Provides a signed URL for the audio recording of the primary session, valid for 1 hour. For multi-session interviews, individual session recordings are accessible via `sessions` array from the Get Interview endpoint.

```HTTP
GET /api/interviews/{id}/audio
```

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

--------------------------------

### Prompt Context Variable Example

Source: https://docs.insightagent.io/product-guides/agents/prompts

Demonstrates how to use context variables to tailor questions based on the expert's background and the call's subject.

```text
Given {{expert_name}}'s background as {{expert_current_role}},  
focus on questions about {{call_subject}}.  

```

--------------------------------

### Get Audio

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves a signed URL for the audio recording from the primary session of an interview.

```APIDOC
## GET /api/interviews/{id}/audio

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

### Method
GET

### Endpoint
/api/interviews/{id}/audio

### Response
#### Success Response (200)
- **url** (string) - A signed URL for the audio recording.
- **expiresIn** (number) - The time in seconds until the URL expires.

### Response Example
```json
{
  "url": "https://storage.example.com/signed-audio-url",
  "expiresIn": 3600
}
```

**Note:** 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.
```

--------------------------------

### Example Agent Prompt with Custom Variables

Source: https://docs.insightagent.io/product-guides/agents/variables

Reference custom variables within your agent prompts using double curly braces. This allows for dynamic content insertion based on interview-specific data.

```text
You are researching {{company_background}} for {{client_name}}.  
  
Focus on understanding:  
- Their position in {{industry_context}}  
- Competition with {{competitor_list}}  
- Specific areas: {{research_focus}}  
  
QUESTIONS:  
{{questions_list}}  

```

--------------------------------

### Full Interview Object Response

Source: https://docs.insightagent.io/api-reference/endpoints

Example of the detailed JSON response for a single interview, including all associated data like sessions, expert details, and analysis.

```JSON
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Technical Interview",
  "interviewType": "FULL_INTERVIEW",
  "status": "COMPLETED",
  "statusReason": null,
  "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,
      "platform": "WEB",
      "isActive": true,
      "isProcessed": true,
      "disconnectReason": "completed_by_expert",
      "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"
  }
}
```

--------------------------------

### Get Current User

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the profile and account information for the currently authenticated user.

```APIDOC
## GET /api/auth/me

### Description
Retrieves the profile and account information for the currently authenticated user.

### Method
GET

### Endpoint
/api/auth/me

### Response
#### Success Response
Returns user and account details.

### Response Example
```json
{
  "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"
  }
}
```
```

--------------------------------

### Get Transcription

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the transcript from the primary session of an interview.

```APIDOC
## GET /api/interviews/{id}/transcription

### Description
Returns the transcript from the primary session as an array of entries.

### Method
GET

### Endpoint
/api/interviews/{id}/transcription

### Response
#### Success Response (200)
- **role** (string) - The role of the speaker ('agent' or 'user').
- **message** (string) - The transcribed message.
- **timestamp_secs** (number) - The timestamp of the message in seconds.

### Response Example
```json
[
  {
    "role": "agent",
    "message": "string",
    "timestamp_secs": number
  }
]
```

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

--------------------------------

### Get Current User Information

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieve the profile and account details for the currently authenticated user.

```http
GET /api/auth/me
```

```json
{
  "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"
  }
}
```

--------------------------------

### Paginated Interview List Response

Source: https://docs.insightagent.io/api-reference/endpoints

Example of a paginated response when 'page' and 'limit' query parameters are provided for the list interviews endpoint.

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

--------------------------------

### Get Agent Variables

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves variables used by an agent's prompt, including their definitions and requirements.

```HTTP
GET /api/agents/{id}/variables
```

--------------------------------

### Default Value Example for Optional Variable

Source: https://docs.insightagent.io/product-guides/agents/variables

Set a default value for an optional variable to ensure the prompt always contains meaningful content, even if no specific value is provided during interview creation.

```text
Variable: industry_context  
Default: "the technology industry"  
  
Prompt: "...their position in {{industry_context}}"  
  
Result when no value provided: "...their position in the technology industry..."  
Result when value is "healthcare": "...their position in healthcare..."  

```

--------------------------------

### Get Interview

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the full details of a specific interview, including sessions with media URLs and AI-generated analysis.

```APIDOC
## GET /api/interviews/{id}

### Description
Retrieves the full details of a specific interview, including sessions with media URLs and AI-generated analysis.

### Method
GET

### Endpoint
/api/interviews/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the interview.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the interview.
- **title** (string) - The title of the interview.
- **interviewType** (string) - The type of interview.
- **status** (string) - Lifecycle stage: `NOT_SCHEDULED`, `SCHEDULED`, `DIALING`, `WAITING_FOR_EXPERT`, `IN_PROGRESS`, `COMPLETED`.
- **statusReason** (string | null) - Human-readable reason the interview reached its current status.
- **questions** (array) - List of questions asked during the interview.
- **expertData** (object) - Information about the expert.
  - **name** (string) - Expert's name.
  - **title** (string) - Expert's title.
  - **employmentHistory** (array) - Expert's employment history.
- **scheduledAt** (string) - The scheduled start time of the interview (ISO 8601).
- **completedAt** (string) - The completion time of the interview (ISO 8601).
- **totalConversationSeconds** (number) - Total duration of the conversation in seconds.
- **sessionCount** (number) - The number of sessions in the interview.
- **summary** (string) - AI-generated summary of the interview.
- **quotes** (array) - Key quotes from the interview.
  - **quote** (string) - The quote text.
  - **speaker** (string) - The speaker of the quote (e.g., 'expert').
  - **context** (string) - The context in which the quote was said.
  - **timestamp_secs** (number) - The timestamp in seconds when the quote occurred.
- **analysisGeneratedAt** (string) - The timestamp when the analysis was generated (ISO 8601).
- **sessions** (array) - Details of each session.
  - **id** (string) - Session ID.
  - **startedAt** (string) - Session start time (ISO 8601).
  - **endedAt** (string) - Session end time (ISO 8601).
  - **durationSeconds** (number) - Session duration in seconds.
  - **platform** (string) - The platform used for the session (e.g., 'WEB').
  - **isActive** (boolean) - Whether the session is active.
  - **isProcessed** (boolean) - Whether the session has been processed.
  - **disconnectReason** (string) - Reason for session disconnection.
  - **audioUrl** (string) - URL for the session's audio recording.
  - **transcriptUrl** (string) - URL for the session's transcript.
- **resolvedAgent** (object) - Information about the resolved agent.
  - **id** (string) - Agent ID.
  - **name** (string) - Agent name.
  - **agentType** (string) - Type of agent.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Technical Interview",
  "interviewType": "FULL_INTERVIEW",
  "status": "COMPLETED",
  "statusReason": null,
  "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,
      "platform": "WEB",
      "isActive": true,
      "isProcessed": true,
      "disconnectReason": "completed_by_expert",
      "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"
  }
}
```
```

--------------------------------

### Get Agent Variables

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the variables used by an agent's prompt, including their definitions and requirements.

```APIDOC
## GET /api/agents/{id}/variables

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

### Method
GET

### Endpoint
/api/agents/{id}/variables

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **name** (string) - The internal name of the variable.
- **displayName** (string) - The user-friendly display name of the variable.
- **description** (string) - A description of what the variable represents.
- **isRequired** (boolean) - Indicates if the variable is required.
- **defaultValue** (string) - The default value of the variable, or `null` if none is set.

### Response Example
```json
[
  {
    "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"
  }
]
```
```

--------------------------------

### Get Agent by ID

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves a specific agent's configuration using its unique identifier.

```HTTP
GET /api/agents/{id}
```

--------------------------------

### Get Live Transcript

Source: https://docs.insightagent.io/api-reference/endpoints

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

```APIDOC
## GET /api/interviews/{id}/transcript/live

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

### Method
GET

### Endpoint
/api/interviews/{id}/transcript/live

### Response
#### Success Response (200)
- **events** (array) - An array of transcript events.
  - **type** (string) - The type of speaker ('agent' or 'user').
  - **text** (string) - The transcribed text.
  - **timestamp** (string) - The timestamp of the event (ISO 8601 format).
  - **sessionId** (string) - The UUID of the session.

### Response Example
```json
{
  "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 Specific Interview Details

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the full details of a specific interview, including session information, media URLs, and AI-generated analysis.

```HTTP
GET /api/interviews/{id}
```

--------------------------------

### Transcript Entry JSON Format

Source: https://docs.insightagent.io/product-guides/interviews/transcripts

This is an example of the JSON structure for a single transcript entry. Each entry includes the speaker's role, their message, and the timestamp in seconds.

```json
[
  {
    "role": "agent",
    "message": "Hello, thank you for joining...",
    "timestamp_secs": 0
  },
  {
    "role": "user",
    "message": "Thanks for having me...",
    "timestamp_secs": 5
  }
]
```

--------------------------------

### Get Agent

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the configuration of a specific agent using its unique identifier.

```APIDOC
## GET /api/agents/{id}

### Description
Retrieve a specific agent configuration by its unique identifier.

### Method
GET

### Endpoint
/api/agents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the agent.
- **name** (string) - The name of the agent.
- **agentType** (string) - The type of agent (e.g., `FULL_INTERVIEW`, `VETTING_INTERVIEW`).
- **language** (string) - The primary language of the agent (ISO 639-1 code).
- **agentPersonaName** (string) - The name of the agent's persona.
- **firstMessage** (string) - The initial message the agent sends.
- **customPrompt** (string) - The custom prompt defining the agent's behavior.
- **description** (string) - A brief description of the agent.
- **role** (string) - The role of the agent (`ROOT` or `TRANSFER_ONLY`).
- **voiceId** (string) - The ID of the voice the agent uses, or `null`.
- **isDefault** (boolean) - Indicates if the agent is a default agent.
- **versionNumber** (integer) - The version number of the agent.
- **createdAt** (string) - The timestamp when the agent was created.
- **updatedAt** (string) - The timestamp when the agent was last updated.

### Response Example
```json
{
  "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",
  "role": "ROOT",
  "voiceId": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f",
  "isDefault": false,
  "versionNumber": 3,
  "createdAt": "2025-12-06T20:04:24.513Z",
  "updatedAt": "2025-12-08T11:10:44.837Z"
}
```
```

--------------------------------

### Get Variable by ID

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieve details for a specific variable using its unique identifier.

```http
GET /api/account/variables/{id}
```

--------------------------------

### Get Interview Stats

Source: https://docs.insightagent.io/api-reference/endpoints

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

```APIDOC
## GET /api/interviews/stats

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

### Method
GET

### Endpoint
/api/interviews/stats

### Response
#### Success Response (200)
- **notScheduled** (number) - Interviews created but not yet scheduled.
- **scheduled** (number) - Interviews scheduled for a future time.
- **inProgress** (number) - Interviews currently active (includes `DIALING` status).
- **completed** (number) - Finished interviews.
- **total** (number) - Total interview count.
- **abandoned** (number) - In-progress interviews with no activity for 5+ minutes.

### Response Example
```json
{
  "notScheduled": 5,
  "scheduled": 12,
  "inProgress": 2,
  "completed": 87,
  "total": 106,
  "abandoned": 1
}
```
```

--------------------------------

### Create Interview

Source: https://docs.insightagent.io/api-reference/endpoints

Use this endpoint to create a new interview. Ensure all required fields are provided in the request body. Optional fields can be included to customize scheduling, agent selection, custom variables, and webhook notifications.

```bash
POST /api/interviews  
```

```json
{
  "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" }
      }
    }
  ]
}
```

--------------------------------

### Create Agent

Source: https://docs.insightagent.io/api-reference/endpoints

Creates a new agent configuration. Agent creation is asynchronous and results in both PHONE and WEB platform versions.

```APIDOC
## POST /api/agents

### Description
Create a new agent configuration. Agent creation is asynchronous and creates both PHONE and WEB platform versions.

### Method
POST

### Endpoint
/api/agents

### Parameters
#### Request Body
- **name** (string) - Required - The name of the agent.
- **agentType** (string) - Required - The type of agent. Values: `FULL_INTERVIEW`, `VETTING_INTERVIEW`.
- **language** (string) - Required - The primary language of the agent (ISO 639-1 code).
- **agentPersonaName** (string) - Optional - The name of the agent's persona.
- **customPrompt** (string) - Optional - The custom prompt defining the agent's behavior (max 10000 characters).
- **description** (string) - Optional - A brief description of the agent (max 500 characters).
- **firstMessage** (string) - Optional - The initial message the agent sends.
- **role** (string) - Optional - The role of the agent. Values: `ROOT`, `TRANSFER_ONLY`. Default: `ROOT`.
- **voiceId** (string) - Optional - The UUID of the voice the agent uses (see List Voices).

### Request Example
```json
{
  "name": "New Support Agent",
  "agentType": "FULL_INTERVIEW",
  "language": "en",
  "description": "Agent for handling customer support inquiries",
  "role": "TRANSFER_ONLY",
  "voiceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

### Response
#### Success Response (202)
- Agent creation is asynchronous. Returns `202 Accepted` upon successful initiation of the creation process.
```

--------------------------------

### Configure Webhook for Interview Notifications

Source: https://docs.insightagent.io/api-reference/endpoints

Set up webhook notifications for interview completion by including the 'notifications' field in the Create Interview request. Multiple endpoints can be configured.

```json
{
  "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"
        }
      }
    }
  ]
}
```

--------------------------------

### Get Variable

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves a specific variable by its ID, including information about its usage in agent prompts.

```APIDOC
## GET /api/account/variables/{id}

### Description
Retrieves a specific variable by its ID, including information about its usage in agent prompts.

### Method
GET

### Endpoint
/api/account/variables/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the variable to retrieve.
```

--------------------------------

### Create an interview

Source: https://docs.insightagent.io/api-reference

Creates a new interview with specified details. Requires authentication and a JSON payload.

```APIDOC
## POST /api/interviews

### Description
Creates a new interview.

### Method
POST

### Endpoint
/api/interviews

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **interviewType** (string) - Required - The type of interview (e.g., "FULL_INTERVIEW").
- **title** (string) - Required - The title of the interview.
- **callSubject** (string) - Required - The subject of the call.
- **expertData** (object) - Required - Information about the expert.
  - **name** (string) - Required - The name of the expert.
  - **title** (string) - Required - The title of the expert.
  - **employmentHistory** (array) - Optional - The employment history of the expert.
    - **title** (string) - Required - The job title.
    - **company** (string) - Required - The company name.
    - **period** (string) - Required - The employment period.
- **questions** (array) - Optional - A list of questions for the interview.
  - (string) - A question.

### Request Example
```json
{
  "interviewType": "FULL_INTERVIEW",
  "title": "Market Research Interview",
  "callSubject": "Enterprise software market trends",
  "expertData": {
    "name": "John Doe",
    "title": "VP Engineering",
    "employmentHistory": [
      {"title": "VP Engineering", "company": "Acme Corp", "period": "2020-Present"}
    ]
  },
  "questions": ["What are the key challenges in your role?"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created interview.
- **title** (string) - The title of the created interview.

#### Response Example
```json
{
  "id": "...",
  "title": "..."
}
```
```

--------------------------------

### Create Agent

Source: https://docs.insightagent.io/api-reference/endpoints

Creates a new agent. Agent creation is asynchronous and supports various configuration options.

```HTTP
POST /api/agents
```

--------------------------------

### Create Interview

Source: https://docs.insightagent.io/api-reference

Use this cURL command to create a new interview. Provide all required fields, including interview type, title, call subject, expert data, and questions. Ensure your authentication token and content type are correctly set.

```curl
# Create an interview  
curl -X POST "https://api.insightagent.io/api/interviews" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{  
    "interviewType": "FULL_INTERVIEW",  
    "title": "Market Research Interview",  
    "callSubject": "Enterprise software market trends",  
    "expertData": {  
      "name": "John Doe",  
      "title": "VP Engineering",  
      "employmentHistory": [  
        {"title": "VP Engineering", "company": "Acme Corp", "period": "2020-Present"}  
      ]  
    },  
    "questions": ["What are the key challenges in your role?"]  
  }'
```

--------------------------------

### List Interviews

Source: https://docs.insightagent.io/api-reference

Use this cURL command to list all interviews associated with your account. Ensure you include your authentication token.

```curl
# List your interviews  
curl -X GET "https://api.insightagent.io/api/interviews" \
  -H "Authorization: Bearer <your-token>"
```

--------------------------------

### Variable Naming Conventions

Source: https://docs.insightagent.io/product-guides/agents/variables

Use descriptive and consistent names for your variables. Follow snake_case for clarity and avoid inconsistent casing or abbreviations.

```text
// Good - clear and consistent  
company_background  
research_focus  
target_industry  

// Avoid - unclear or inconsistent  
cb  
researchFocus  
INDUSTRY  
```

--------------------------------

### List your interviews

Source: https://docs.insightagent.io/api-reference

Retrieves a list of all interviews associated with your account. Requires authentication.

```APIDOC
## GET /api/interviews

### Description
Retrieves a list of all interviews.

### Method
GET

### Endpoint
/api/interviews

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```
curl -X GET "https://api.insightagent.io/api/interviews" \
  -H "Authorization: Bearer <your-token>"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the interview.
- **title** (string) - The title of the interview.

#### Response Example
```json
{
  "id": "...",
  "title": "..."
}
```
```

--------------------------------

### Interactive API Documentation URL

Source: https://docs.insightagent.io/api-reference

Access the interactive API documentation (Swagger UI) at the provided URL for detailed endpoint information and testing.

```text
https://api.insightagent.io/api-docs
```

--------------------------------

### Get Interview Transcription

Source: https://docs.insightagent.io/product-guides/interviews/transcripts

Retrieves the full transcript for a given interview ID. This endpoint allows programmatic access to the conversation data.

```APIDOC
## GET /api/interviews/{id}/transcription

### Description
Retrieves the full transcript for a given interview ID. This endpoint allows programmatic access to the conversation data.

### Method
GET

### Endpoint
/api/interviews/{id}/transcription

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the interview.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "https://api.insightagent.io/api/interviews/{id}/transcription" \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **role** (string) - The role of the speaker (e.g., 'agent', 'user').
- **message** (string) - The transcribed text of the message.
- **timestamp_secs** (integer) - The timestamp of the message in seconds from the start of the interview.

#### Response Example
```json
[
  {
    "role": "agent",
    "message": "Hello, thank you for joining...",
    "timestamp_secs": 0
  },
  {
    "role": "user",
    "message": "Thanks for having me...",
    "timestamp_secs": 5
  }
]
```
```

--------------------------------

### Create Interview

Source: https://docs.insightagent.io/api-reference/endpoints

Creates a new interview with specified details, including type, title, call subject, expert information, questions, and optional scheduling or notification settings.

```APIDOC
## POST /api/interviews

### Description
Creates a new interview with specified details, including type, title, call subject, expert information, questions, and optional scheduling or notification settings.

### Method
POST

### Endpoint
/api/interviews

### Parameters
#### Request Body
- **interviewType** (string) - Required - Must be `FULL_INTERVIEW` or `VETTING_INTERVIEW`
- **title** (string) - Required - Interview title
- **callSubject** (string) - Required - Subject/topic for the call
- **expertData** (object) - Required - Expert's information
  - **name** (string) - Required - Expert's full name
  - **title** (string) - Required - Expert's job title
  - **employmentHistory** (array) - Required - At least one employment entry
    - **title** (string) - Required - Job title for each employment entry
    - **company** (string) - Required - Company name for each employment entry
- **questions** (array) - Required - Array with at least one question
- **status** (string) - Optional - Explicitly set the interview status to `NOT_SCHEDULED` or `SCHEDULED`. If omitted, status is derived from `scheduledAt`.
- **scheduledAt** (ISO8601 datetime) - Optional - Used to derive status if `status` is omitted.
- **dialInPhone** (string) - Optional
- **meetingId** (string) - Optional
- **dialInPin** (string) - Optional
- **agentGroupId** (uuid) - Optional - UUID of the agent group to use for this interview. If omitted, the account's default agent for the given `interviewType` is used.
- **compliance** (string) - Optional
- **customVariables** (object) - Optional - 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.
  - **company_background** (string)
  - **research_focus** (string)
- **notifications** (array) - Optional - Array of webhook subscriptions to notify when the interview completes.
  - **endpoint** (string) - Required - Webhook endpoint URL
  - **attributes** (object) - Required - Webhook attributes
    - **method** (string) - Required - HTTP method for the webhook
    - **headers** (object) - Required - Headers for the webhook request
      - **Authorization** (string) - Required - Bearer token for authentication

### Request Example
{
  "interviewType": "FULL_INTERVIEW",
  "title": "Software Engineer Interview",
  "callSubject": "Backend Development",
  "expertData": {
    "name": "Jane Doe",
    "title": "Senior Software Engineer",
    "employmentHistory": [
      {
        "title": "Software Engineer",
        "company": "Tech Corp",
        "period": "2018-2022"
      }
    ]
  },
  "questions": ["What are your strengths?", "Tell me about a challenging project."],
  "scheduledAt": "2023-10-27T10:00:00Z",
  "notifications": [
    {
      "endpoint": "https://your-server.com/webhook",
      "attributes": {
        "method": "POST",
        "headers": { "Authorization": "Bearer your-token" }
      }
    }
  ]
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created interview.
- **status** (string) - The current status of the interview.
- **createdAt** (ISO8601 datetime) - The timestamp when the interview was created.

#### Response Example
{
  "id": "interview-12345",
  "status": "SCHEDULED",
  "createdAt": "2023-10-26T15:30:00Z"
}
```

--------------------------------

### API Authentication using API Key

Source: https://docs.insightagent.io/getting-started/authentication

Use API keys for server-to-server integrations. API keys are provisioned by administrators.

```curl
curl -X GET "https://api.insightagent.io/api/interviews" \
  -H "x-api-key: <your-api-key>"
```

--------------------------------

### Get Interview Transcription

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves the transcript from the primary session of an interview. For interviews with multiple sessions, individual session transcripts can be accessed via their `transcriptUrl`.

```HTTP
GET /api/interviews/{id}/transcription
```

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

--------------------------------

### List Variables

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves all custom variables defined for your account, which can be used to manage agent prompts.

```HTTP
GET /api/account/variables
```

```JSON
{
  "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"
    }
  ]
}
```

--------------------------------

### Missing Authentication Error Response

Source: https://docs.insightagent.io/api-reference/authentication

This error is returned when authentication headers are missing. Ensure you provide either an `x-api-key` or an `Authorization` header.

```json
{
  "error": "Missing authentication headers, provide either an x-api-key or a Authorization header"
}  

```

--------------------------------

### Create API Key

Source: https://docs.insightagent.io/api-reference/endpoints

Generates a new API key for programmatic access. The full key is returned only once upon creation.

```APIDOC
## POST /api/api-keys

### Description
Generates a new API key for programmatic access. The full key is returned only once upon creation.

### Method
POST

### Endpoint
/api/api-keys

### Parameters
#### Request Body
- **name** (string) - Required - The name for the API key.

### Response
#### Success Response (201 Created)
Returns the newly created API key details, including the full key.

### Request Example
```json
{
  "name": "Production"
}
```

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

**Note:** 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
```

--------------------------------

### Get Interview Statistics

Source: https://docs.insightagent.io/api-reference/endpoints

Retrieves aggregate counts of interviews categorized by their status for the current account. This includes counts for notScheduled, scheduled, inProgress, completed, total, and abandoned interviews.

```HTTP
GET /api/interviews/stats
```

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