---
updatedAt: 2026-04-21T22:56:43.000Z
agentTools:
projectIndex: https://talkpush-apidocs.readme.io/llms.txt
---
# Update an existing agent
Updates an agent's configuration. All fields are optional — only the fields provided will be changed. **Note:** if `data_extractions` is included, it **replaces** the existing extractions entirely (not a partial merge). The same applies to `prompt`.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"description": "Production Base URL to be used during implementation: {your company workspace subdomain}.talkpush.com/api/talkpush_services\n\nWith the Talkpush APIs you can instantly plug your lead source into out platform to enjoy the benefits of Talkpush. You can also synch your existing HR / Recruitment technology stack with your Talkpush account. To be able to use our API you will need pass an api key as a parameter for each API call. In case you do not know your current API key you can contact our support team at cs@talkpush.com.\n",
"version": "2.0",
"title": "Talkpush API",
"contact": {
"email": "admin@talkpush.com"
}
},
"tags": [
{
"name": "Agents API",
"description": "Collection of endpoints related to AI Agents (SmartCall Settings). Agents are configurable AI-powered voice/interview agents that can be linked to campaigns, question sets, and candidate attribute extractions."
}
],
"paths": {
"/agents/{id}": {
"put": {
"tags": [
"Agents API"
],
"summary": "Update an existing agent",
"description": "Updates an agent's configuration. All fields are optional — only the fields provided will be changed. **Note:** if `data_extractions` is included, it **replaces** the existing extractions entirely (not a partial merge). The same applies to `prompt`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The ID of the agent to update.",
"schema": {
"type": "integer"
}
},
{
"name": "api_key",
"in": "query",
"required": true,
"description": "The API key provided for your application.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/agent_update_request"
},
"example": {
"agent": {
"name": "My Agent",
"description": "Evaluates candidate English proficiency",
"category": "screen_interview",
"provider": "elevenlabs",
"provider_agent_id": "agent_abc123xyz456",
"question_set_id": "1",
"is_active": true,
"prompt": "This is the prompt for my agent I need:\n {{messenger_interview_url}}",
"data_extractions": [
{
"candidate_attribute": {
"id": "29"
},
"description": "Candidate English proficiency level",
"data_type": "string",
"enum_values": [
"basic",
"intermediate",
"advanced"
]
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Agent updated successfully. Returns the full updated agent detail.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/agent_detail_response"
}
}
}
},
"404": {
"description": "Agent not found."
},
"422": {
"description": "Validation error. Returned when the request body contains invalid data — e.g. an invalid `category`, an invalid `provider`, or malformed `data_extractions`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"provider must be one of: elevenlabs, vapi",
"category must be one of: screen_interview, phone_call, on_site_interview, event_invitation, passive_candidate_outreach, status_update, reminders"
]
}
}
}
}
}
},
"500": {
"description": "Internal server error, we will provide you with the exception message of the application."
}
}
}
}
},
"servers": [
{
"url": "https://company_subdomain.talkpush.com/api/talkpush_services"
}
],
"components": {
"schemas": {
"agent_detail": {
"type": "object",
"description": "Full agent representation returned by the show and update endpoints.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the agent."
},
"name": {
"type": "string",
"description": "Display name of the agent.",
"nullable": true
},
"description": {
"type": "string",
"description": "Short description of the agent's purpose.",
"nullable": true
},
"category": {
"type": "string",
"description": "Use-case category of the agent.",
"nullable": true,
"enum": [
"screen_interview",
"phone_call",
"on_site_interview",
"event_invitation",
"passive_candidate_outreach",
"status_update",
"reminders"
]
},
"prompt": {
"type": "string",
"description": "The agent's full prompt string. Supports Handlebars-style variables such as `{{messenger_interview_url}}`, `{{interview_page_url}}`, and `{{messenger_interview_link}}`."
},
"provider": {
"type": "string",
"description": "AI provider powering the agent.",
"nullable": true,
"enum": [
"elevenlabs",
"vapi"
]
},
"provider_info": {
"type": "object",
"description": "Human-readable provider metadata.",
"nullable": true,
"properties": {
"name": {
"type": "string",
"description": "Provider key (e.g. `elevenlabs`)."
},
"vendor": {
"type": "string",
"description": "Provider display name (e.g. `ElevenLabs`)."
}
}
},
"provider_agent_id": {
"type": "string",
"description": "The agent identifier on the external provider's platform.",
"nullable": true
},
"question_set_id": {
"type": "string",
"description": "ID of the linked question set, if any.",
"nullable": true
},
"question_set": {
"type": "object",
"description": "Linked question set metadata. Present only when a question set is associated.",
"nullable": true,
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"data_extractions": {
"type": "object",
"description": "Map of data extraction rules keyed by the candidate attribute name. Each value defines the extraction schema for that attribute.",
"additionalProperties": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Data type of the extracted value (e.g. `string`, `integer`)."
},
"description": {
"type": "string",
"description": "Instructions to the AI on what to extract."
},
"enum": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of allowed values for the extraction. Empty array if unconstrained."
},
"candidate_attribute": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the candidate attribute this extraction maps to."
}
}
}
}
}
},
"is_active": {
"type": "boolean",
"description": "`true` if the agent is active (published); `false` if inactive (draft)."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when the agent was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when the agent was last updated."
}
}
},
"agent_detail_response": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/agent_detail"
}
},
"required": [
"data"
]
},
"agent_update_request": {
"type": "object",
"required": [
"agent"
],
"properties": {
"agent": {
"type": "object",
"description": "All fields are optional. Only the fields provided will be updated. If `data_extractions` is sent, it fully replaces the existing extractions.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the agent."
},
"description": {
"type": "string",
"description": "Short description of the agent's purpose."
},
"category": {
"type": "string",
"description": "Use-case category of the agent.",
"enum": [
"screen_interview",
"phone_call",
"on_site_interview",
"event_invitation",
"passive_candidate_outreach",
"status_update",
"reminders"
]
},
"provider": {
"type": "string",
"description": "AI provider powering the agent.",
"enum": [
"elevenlabs",
"vapi"
]
},
"provider_agent_id": {
"type": "string",
"description": "The agent identifier on the external provider's platform."
},
"question_set_id": {
"type": "string",
"description": "ID of the question set to link to this agent."
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to activate the agent (published); `false` to deactivate it (draft)."
},
"prompt": {
"type": "string",
"description": "The agent's prompt. Supports Handlebars-style variables: `{{messenger_interview_url}}`, `{{interview_page_url}}`, `{{messenger_interview_link}}`."
},
"data_extractions": {
"type": "array",
"description": "Fully replaces all existing data extraction rules when provided. Send an empty array to remove all extractions.",
"items": {
"type": "object",
"required": [
"candidate_attribute",
"description",
"data_type"
],
"properties": {
"candidate_attribute": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "ID of the candidate attribute to map the extracted value to."
}
}
},
"description": {
"type": "string",
"description": "Instructions to the AI on what to extract."
},
"data_type": {
"type": "string",
"description": "Data type of the extracted value (e.g. `string`, `integer`)."
},
"enum_values": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of allowed values. Send an empty array for unconstrained extraction."
}
}
}
}
}
}
}
}
}
}
}
```