Skip to main content

Create an agent response (OpenAI Responses API)

POST 
/agent/:id/responses

OpenAI Responses API-compatible endpoint. Starts a new response for the agent identified by id (the workflow id). When stream: true, returns a text/event-stream of OpenAI ResponseStreamEvent frames with native resume via sequence_number; when stream is false or absent, accumulates the full run and returns a single OpenAI Response JSON object.

The input field follows the OpenAI taxonomy: either a plain string (treated as the user prompt) or an array of structured input items whose content parts may be input_text or input_file. Only input_file references by file_id (uploaded via POST /v1/files) are supported; file_url and file_data modes are rejected with HTTP 400/404.

Multi-turn continuity is expressed via previous_response_id (the id of a prior response); the platform resolves it to the underlying agent session. Free-form metadata is forwarded onto Response.metadata; the platform reserves the x_alien_* key prefix and strips any caller-supplied keys that collide. For multi-agent runs the platform surfaces metadata.x_alien_root_agent_id (root agent) and metadata.x_alien_agent_registry (a JSON-encoded array of every agent that appeared), and encodes per-item agent identity inside each output item's id.

The SSE frame taxonomy (response.created, response.output_text.delta, response.output_item.added / .done, response.function_call_arguments.done, response.completed, response.failed, response.incomplete, plus the platform sidebands response.cost_breakdown and response.tool_call.output) is documented in full in the Responses streaming guide. Out-of-scope request fields: background: true and conversation are rejected with HTTP 400.

Request​

Responses​

When stream: true: an OpenAI Responses-API-conformant SSE stream. When stream is false/absent: the terminal OpenAI Response object as a single JSON body.