> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Agent
> Updates an existing agent scoped to the API key's company.
Updates an existing agent (interview template) using partial updates. Only provided fields will be updated; omitted fields remain unchanged.
## Overview
The update agent endpoint allows you to modify agent configuration without recreating it. This supports partial updates, meaning you only need to provide the fields you want to change. This is useful for refining agent questions, updating evaluation criteria, or adjusting voice settings.
## Use Cases
* **Refine Questions**: Update interview questions based on feedback
* **Adjust Settings**: Change voice, duration, or interview type
* **Update Criteria**: Modify evaluation criteria as requirements evolve
* **Iterative Improvement**: Continuously improve agent configurations
## Partial Updates
You can update any combination of fields:
```javascript theme={null}
// Update only questions
PATCH /agents/{id}
{
"questions": [
"New question 1",
"New question 2"
]
}
// Update multiple fields
PATCH /agents/{id}
{
"name": "Updated Agent Name",
"focus": "SCREENING",
"duration": 45,
"questions": [
"Updated question 1",
"Updated question 2"
]
}
```
## Fields That Can Be Updated
* `name`: Agent display name
* `type`: Agent type (ONLINE, PHONE)
* `focus`: Agent focus (GENERIC, SCREENING, OUTREACH, LANGUAGE\_TEST)
* `language`: Interview language code
* `duration`: Interview duration in minutes (max 180)
* `questions`: Array of interview questions
* `instructions`: Additional instructions for the interview
* `voiceId`: Voice ID for the AI interview
* `cefrLevel`: CEFR level for language test agents
* `backgroundSound`: Ambient background sound during calls (`OFFICE` or `OFF`)
## Company Isolation
You can only update agents that belong to your API key's company. Attempting to update an agent from another company will result in a `403 Forbidden` error.
## Phone Agents
If you update an agent's `type` to `PHONE`, you **must** also provide a `companyPhoneNumberId` in the same request.
```javascript theme={null}
PATCH /agents/{id}
{
"type": "PHONE",
"companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000"
}
```
## Background Sound
Use `backgroundSound` to change the ambient noise played during calls for this agent. Accepted values are `"OFFICE"` (subtle office noise, default) and `"OFF"` (silence).
```javascript theme={null}
PATCH /agents/{id}
{
"backgroundSound": "OFF"
}
```
Omitting `backgroundSound` keeps the existing value on the agent.
## Impact on Existing Interviews
Updates to agent configuration do not affect interviews that have already been
scheduled or completed. Only new interviews created after the update will use
the new configuration.
## Error Scenarios
* **404 Not Found**: Agent doesn't exist or has been deleted
* **403 Forbidden**: Agent belongs to a different company
* **400 Bad Request**: Invalid field values or validation errors
## Related Resources
Learn about agent configuration best practices
Retrieve current agent configuration
Create new agents
## OpenAPI
````yaml PATCH /agents/{id}
openapi: 3.0.0
info:
title: InstaView API
description: |-
InstaView API Documentation
## Authentication
All endpoints require API key authentication using Bearer token:
```
Authorization: Bearer sk_your_api_key_here
```
## API Key Management
The API Key module provides comprehensive key management for:
- **Direct Client Keys**: Company-scoped keys for your applications
- **ATS Partner Keys**: Resource-scoped keys for ATS integrations
### Key Features
- HMAC-SHA256 hashing for API key storage
- Configurable rate limiting
- Comprehensive audit logging
- Company-level isolation
- Resource scoping for ATS partners
version: 1.0.0
contact: {}
servers:
- url: https://api.instaview.sk
description: Production API Gateway
security: []
tags: []
paths:
/agents/{id}:
patch:
tags:
- Agents
summary: Update agent
description: Updates an existing agent scoped to the API key's company.
operationId: PublicAgentsController_updateAgent_v1
parameters:
- name: id
required: true
in: path
schema:
type: string
format: uuid
- name: companyId
required: false
in: query
description: >-
Required for ATS API keys to specify which company to access.
Ignored for standard company API keys.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUpdateAgentDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentDto'
security:
- bearer: []
components:
schemas:
PublicUpdateAgentDto:
type: object
properties:
name:
type: string
description: Agent name
example: Updated Senior Developer Interview
minLength: 2
maxLength: 100
type:
type: string
description: Type of the agent
enum:
- UNDEFINED
- ONLINE
- PHONE
example: ONLINE
focus:
type: string
description: >-
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.
enum:
- GENERIC
- SCREENING
- OUTREACH
- LANGUAGE_TEST
example: SCREENING
questions:
description: List of questions for the interview
example:
- What is your experience with React?
maxItems: 50
type: array
items:
type: string
instructions:
type: string
description: Additional instructions for the interview
example: Focus on system design and communication
maxLength: 2000
language:
type: string
description: Language of the interview
enum:
- 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:
type: number
description: Duration of the interview in minutes
example: 45
minimum: 1
maximum: 180
voiceId:
type: string
description: Voice ID for the AI interview (null clears existing voice)
enum:
- ALEX
- PETER
- MIRIAM
- SUE
- VIERA
- CASANDRA
- SILVIA
- MICHAEL
- LUKE
- EMMA
- SARAH
- EVA
nullable: true
cefrLevel:
type: string
description: CEFR level for language test agents
enum:
- A1
- A2
- B1
- B2
- C1
- C2
example: B2
companyPhoneNumberId:
type: string
description: >-
ID of the company phone number assignment to use for calls from this
agent (CompanyPhoneNumber.id)
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
metadata:
type: object
description: >-
Custom metadata (merged with existing metadata, max 10KB, 5 levels
deep, 50 keys)
example:
department: Engineering
backgroundSound:
type: string
description: >-
Ambient background sound during calls (`OFFICE` or `OFF`). Omit to
keep the existing value, set `null` to clear override.
enum:
- 'OFF'
- OFFICE
example: OFFICE
nullable: true
PublicAgentDto:
type: object
properties:
id:
type: string
description: Agent ID
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description: Agent name
example: Frontend Developer Interview
type:
type: string
description: Type of the agent
enum:
- UNDEFINED
- ONLINE
- PHONE
example: ONLINE
focus:
type: string
description: >-
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.
enum:
- GENERIC
- SCREENING
- OUTREACH
- LANGUAGE_TEST
example: SCREENING
questions:
description: List of questions for the interview
example:
- What is your experience with React?
type: array
items:
type: string
instructions:
type: string
description: Additional instructions for the interview
example: Focus on technical skills and previous project experience
language:
type: string
description: Language of the interview
enum:
- 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:
type: number
description: Duration of the interview in minutes
example: 30
voiceId:
type: string
description: Voice ID for the AI interview
enum:
- ALEX
- PETER
- MIRIAM
- SUE
- VIERA
- CASANDRA
- SILVIA
- MICHAEL
- LUKE
- EMMA
- SARAH
- EVA
companyId:
type: string
format: uuid
description: Company ID that owns the agent
example: 123e4567-e89b-12d3-a456-426614174000
metadata:
type: object
description: Custom metadata
example:
department: Sales
cefrLevel:
type: string
description: CEFR level for language test agents
enum:
- A1
- A2
- B1
- B2
- C1
- C2
example: B1
backgroundSound:
type: string
description: >-
Ambient background sound during calls (`OFFICE` or `OFF`). Null
means no override is set and the default applies.
enum:
- 'OFF'
- OFFICE
example: OFFICE
nullable: true
createdAt:
type: string
description: Agent creation timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
updatedAt:
type: string
description: Agent last update timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
required:
- id
- name
- type
- focus
- language
- duration
- createdAt
- updatedAt
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````