Skip to main content
The AI Agents v2 create, list, get, update and delete operations are deprecated. Move to v3 before November 30, 2026. This page lists every difference you have to handle.

​
Endpoint map

Authentication is unchanged: the same Authorization: Bearer <API_KEY> header, the same tenant scoping and the same base URL.

​
What is not deprecated

Only the five agent CRUD operations above are deprecated. These operations keep their /v2/ai-agents/{ai_agent_id}/… paths and keep working: An agent created with v3 has the same ai_agent_id you pass to those operations.

​
1. Every response is wrapped

v2 returned the agent at the top level, with status and message added next to the agent’s own fields. v3 wraps the result in a standard envelope: status, message, data, and error_details on some errors.
status is lowercase on v3 (success or error). v2 returned SUCCESS in uppercase. If your code compares status, update the comparison.

​
The list moves one level down

The agents move from the top-level data array to data.items. The cursor moves from the top-level next_page_token to data.next_page_token.
next_page_token is omitted on the last page in both versions.

​
Errors on get now have a body

Errors already used the { "status": "error", "message", "error_details" } shape on both versions, with one exception. GET /v2/ai-agents/{agent_id} answered 404 and 403 with an empty body. The v3 get answers with the error envelope and a message:
If your client skips parsing the body on a 404 or 403, it keeps working. If you want the message, parse the body.

​
2. Delete returns 200, not 204

DELETE /v3/ai-agents/{agent_id} answers 200 with the envelope. data holds the agent as it was before the delete. v2 answered 204 with no body. Update client code that treats 204 as the only success code, or that never reads the body.

​
3. LLM, STT and TTS are selected by id

This is the main change. v2 took provider and model names. v3 takes catalog ids, and the server resolves them.
llm.system_prompt, llm.tools, llm.required_dynamic_data and tts.voice_temperature are unchanged. Provider credentials are no longer sent with the agent. A custom model’s endpoint and key are part of the model catalog entry. The name fields still come back on reads. The server copies them from the catalog when it stores the agent. Treat them as read-only.
To migrate stored configuration, list each catalog once and build a name-to-id table, for example deepgram + nova-2-phonecall to provider_id + model_id. Then rewrite your stored request bodies with it. The ids are stable.

​
4. Update rejects the LLM name fields

Update AI Agent returns 400 when the body contains llm.model_provider, llm.model_name or llm.model_display_name. Send llm.llm_id to change the model.
Get AI Agent returns those three fields inside data.llm. A client that reads an agent and sends the same llm object back gets this 400. Remove the three fields first, or send only the fields you change.

​
5. Agentic agents cannot be created

llm_type: "agentic" returns 422. This already applies on v2. Use flow for new multi-step agents. Existing agentic agents stay readable and updatable.

​
6. Flow agents carry their selections in the graph

For llm_type: "flow", the root llm object holds only llm_type and graph_data. The root stt and tts objects are ignored. The flow-default references live in graph_data.agentDefaults:
In responses, the root llm of a flow agent also carries llm_id and the model fields, filled from the flow-default model. A flow agent has no root stt, tts, agent_owner_id or pronunciations. On update, graph_data is not merged: a sent graph replaces the stored one. Send llm_type: "flow" with the complete graph.

​
7. Null handling differs between list and get

GET /v3/ai-agents/{agent_id} omits fields that have no value. List items include every field, with an explicit null. If you read both into the same type, make every field optional and treat a missing field and null the same way.

​
What has not changed

  • The agent’s own field names and meanings, and snake_case JSON.
  • Cursor pagination with page_size, page_token and next_page_token.
  • The list filters and tenant scoping.
  • Validation errors return 422. Out-of-range list parameters return 422.

​
Operations with no v3 equivalent yet

If your integration uses these operations, keep calling them on v2 and migrate the CRUD calls separately:
  • GET /v2/ai-agents/by-workspaces
  • GET /v2/ai-agents/metrics/concurrent
  • The agent versions API under /v2/ai-agents/{agent_id}/versions