Response API Migration

Note: The deprecation date starts from 15-Oct-2025. The following old endpoints will be sunset on 14-Nov-2025

Old Endpoints (Deprecated)
POST https://{{your-server-name}}/v2/api/agent/{agent_id}/response
POST https://{{your-server-name}}/api/v2/agents/{agent_id}/responses

New Endpoint (Recommended)
POST https://{{your-server-name}}/response-service/api/v2/agents/{agent_id}/responses

This document provides a migration guide for updating from the legacy Response APIs to the latest one. It highlights the differences in request and response formats, field changes, and migration notes for developers.

⚡ Key Features of new Response endpoint:

New inference strategies like Reflection (self-checking answers) and CodeAct (on-the-fly code execution) improve accuracy, handle complex multi-step questions, and adapt dynamically to different contexts.

Upgraded retrievers and richer data connectors allow the Agent to search, filter, and combine information from more sources, producing answers that are both deeper and more precise, ideal for knowledge-heavy or compliance-sensitive use cases.

Endpoint with Streaming Support is also available in the same new format.

Streaming Support path:

https://{{your-server-name}}/response-service/api/v2/agents/{agent_id}/responses/stream

1. Request Body Comparison

Old Request Body Example

{ 
  "history": [{"user": "string", "bot": "string"}], 
  "model": "string", 
  "chat_thread_id": 0, 
  "overrides": {"sources": true, "corpus_ids": [0]}, 
  "query_source": "string" 
}

New Request Body Example

{ 
  "chat_thread_id": 1, //Optional. If not provided, a new chat thread will be created
  "history": [{"bot": "string", "user": "string"}], //Useful for maintaining chat context.
  "query_source": "web", //Source from where the query is being sent.
  "user_query": "How is the weather?" //New, Required field for sending chat query.
}

Key Changes in Request

Field	Old	New	Notes
user_query	-	Required	Explicitly include the current user query.
model	Required	Deprecated	Model selection now handled server-side.
chat_thread_id	Required	Optional	Omit or use `null` to auto-create a thread.
history	Required	Optional	Same structure. Essential to pass when past conversation needs to be taken into account.
overrides	Optional	Optional	Can include extra control flags.

2. Response Comparison

Old Response Example

{ 
  "message": "string", 
  "success": true, 
  "data": { 
    "answer": "string", 
    "sources": "string", 
    "followup_questions": ["string"], 
    "indexes": ["string"], 
    "query": "string", 
    "total_tokens": 0, 
    "prompt_tokens": 0, 
    "completion_tokens": 0, 
    "cache_hit": true, 
    "history": [{"user": "string", "bot": "string"}], 
    "prompt_prefix": "string", 
    "instructions": ["string"], 
    "agent_mode": "string", 
    "references": [{"number": 0, "url": "string", "order": 0}], 
    "success": true, 
    "corpus_ids": [0], 
    "run_id": "string", 
    "chat_thread_name": "string", 
    "thread_id": 0, 
    "agent_response_id": 0 
  } 
}

New Response Example

{ 

  "message": "Successfully fetched the response", 
  "success": true 
  "data": { 
    "agent_response_id": 1, 
    "answer": "The capital of France is Paris.", 
    "blocked": false, 
    "cache_hit": false, 
    "chat_thread_name": "Chat Thread Name", 
    "references": [], 
    "thread_id": 1 
  } 
}

Key Changes in Response

Field	Old	New	Notes
blocked	-	Optional	Indicates safety blocking.
cache_hit	Present	Same	Now optional and nullable.
chat_thread_name	Present	Same	Now optional and nullable.
references	Optional	Optional	Use generic parsing.

The following fields from old response are deprecated in new endpoint,

sources, followup_questions, indexes, query, total_tokens, prompt_tokens, completion_tokens, history, prompt_prefix, instructions, agent_mode, success, corpus_ids, run_id

3. Migration Notes

Add user_query to every request.

Remove model and deprecated fields.

Simplify response parsing (agent_response_id, answer, cache_hit, references).

Handle nullable fields (chat_thread_name, cache_hit).

Response API Migration

Endpoint with Streaming Support is also available in the same new format.#

1. Request Body Comparison#

Old Request Body Example#

New Request Body Example#

Key Changes in Request#

2. Response Comparison#

Old Response Example#

New Response Example#

Key Changes in Response#

3. Migration Notes#