Prefill an agent test from a conversation

Build a new Agent Testing definition from append-only conversation events through the selected user or agent message without deriving history from dashboard HTML.

Endpoint

POST/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/agent-tests/prefill

Authentication

Operation class	Authentication	Minimum role	API key
customer-api	Bearer API key or dashboard session cookie; dashboard mutations also require X-CX-Request: 1.	member	Allowed

Parameters

Name	In	Type	Required	Description
`workspace_id`	path	string	Yes	—
`conversation_id`	path	string	Yes	—

Request body

application/json request schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	PrefillBody	—	No	Yes	—	—
`event_seq`	integer	—	—	No	Yes	—	—

Example

curl --request POST 'https://operade.ai/api/v1/workspaces/ws_demo/conversations/conv_demo/agent-tests/prefill' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"event_seq":12}'

{
  "event_seq": 12
}

Responses

Status	Description	Content
`4XX`	Handled client error	application/json: ErrorResponse
`200`	Successful Response	application/json: PrefillResponse

4XX application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	ErrorResponse	—	No	Yes	—	—
`error`	object	ErrorItem	—	No	Yes	—	—
`error.code`	string	—	—	No	Yes	—	—
`error.details`	object	—	—	No	No	—	—
`error.message`	string	—	—	No	Yes	—	—

200 application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	PrefillResponse	—	No	Yes	—	—
`agent_id`	string	—	—	No	Yes	—	—
`definition`	object	PrefillDefinition	—	No	Yes	—	—
`definition.chat_history`	array<HistoryEntry>	—	—	No	Yes	—	—
`definition.chat_history[]`	object	HistoryEntry	—	No	Yes	—	—
`definition.chat_history[].message`	string or null	—	—	Yes	No	—	—
`definition.chat_history[].role`	string	—	—	No	Yes	"user", "agent"	—
`definition.chat_history[].tool_calls`	array<ToolCall>	—	—	No	No	—	—
`definition.chat_history[].tool_calls[]`	object	ToolCall	—	No	Yes	—	Bagian stabil kontrak vendor; detail bertipe baru tetap dipertahankan.
`definition.chat_history[].tool_calls[].params_as_json`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_calls[].request_id`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_calls[].tool_details`	object or null	—	—	Yes	No	—	—
`definition.chat_history[].tool_calls[].tool_has_been_called`	boolean	—	—	No	Yes	—	—
`definition.chat_history[].tool_calls[].tool_name`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_calls[].type`	string or null	—	—	Yes	No	—	—
`definition.chat_history[].tool_results`	array<ToolResult>	—	—	No	No	—	—
`definition.chat_history[].tool_results[]`	object	ToolResult	—	No	Yes	—	—
`definition.chat_history[].tool_results[].is_blocked`	boolean	—	—	No	No	—	—
`definition.chat_history[].tool_results[].is_error`	boolean	—	—	No	Yes	—	—
`definition.chat_history[].tool_results[].request_id`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_results[].result_value`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_results[].tool_has_been_called`	boolean	—	—	No	Yes	—	—
`definition.chat_history[].tool_results[].tool_latency_secs`	number	—	—	No	No	—	—
`definition.chat_history[].tool_results[].tool_name`	string	—	—	No	Yes	—	—
`definition.chat_history[].tool_results[].type`	string	—	—	No	Yes	—	—
`definition.conversation_initiation_source`	string	—	—	No	Yes	"unknown", "telegram_integration"	—
`definition.dynamic_variables`	object	—	—	No	Yes	—	—
`definition.from_conversation_metadata`	object	FromConversationMetadata	—	No	Yes	—	—
`definition.from_conversation_metadata.conversation_id`	string	—	—	No	Yes	—	—
`definition.from_conversation_metadata.event_seq`	integer	—	—	No	Yes	—	—
`definition.from_conversation_metadata.original_agent_response`	string or null	—	—	Yes	No	—	—
`definition.from_conversation_metadata.system__conversation_id`	string or null	—	—	Yes	No	—	—
`definition.from_conversation_metadata.system__time_utc`	string	—	date-time	No	Yes	—	—
`definition.type`	string	—	—	No	Yes	"simulation", "llm"	—

Response example

{
  "agent_id": "string",
  "definition": {
    "type": "simulation",
    "chat_history": [],
    "dynamic_variables": {},
    "conversation_initiation_source": "unknown",
    "from_conversation_metadata": {
      "conversation_id": "string",
      "event_seq": 0,
      "system__time_utc": "2026-01-01T00:00:00Z"
    }
  }
}

Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.

Status	Code	Description
`401`	`unauthenticated`	Authentication is missing, invalid, or revoked.
`403`	`forbidden`	The authenticated caller does not have access to this operation.
`404`	`not_found`	The requested workspace resource was not found.
`422`	`validation_failed`	The request did not pass field or business validation.