Skip to main content
POST
/
v1
/
agents
/
runs
cURL
curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": "express",
  "input": "What is the capital of France?"
}'
{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "The capital of France is Paris.",
      "content": "What is the capital of France?",
      "agent": "express"
    }
  ]
}

​
Description

This endpoint answers the user’s query with an LLM using web results (max 1 web search) to ground the answer. Use it for answering simple questions that involve a web search that require a low latency agent.

​
Errors

The endpoint returns as a structured JSON object with status, code, title, and detail fields:
HTTPCodeWhen it happens
400bad_requestInvalid request body (e.g., tools must be an array of objects)
401unauthorizedMissing or invalid Authorization header (use a valid <API_KEY>)
403forbiddenYou are not allowed to run this agent or the requested tool

​
Streaming Example (SSE)

curl -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -X POST https://api.you.com/v1/agents/runs \
  -d '{
    "agent": "express",
    "input": "What is the capital of France?",
    "stream": true
  }'
Summary excerpt of streaming events: 
id: 0
event: response.created
data: {"seq_id": 0, "type": "response.created"}

id: 1
event: response.starting
data: {"seq_id": 1, "type": "response.starting"}

id: 2
event: response.output_item.added
data: {"seq_id": 2, "type": "response.output_item.added",
"response": {"output_index": 0}}

id: 3
event: response.output_text.delta
data: {"seq_id": 3, "type": "response.output_text.delta",
"response": {"output_index": 0, 
"type": "message.answer", "delta": "####"}}

id: 4
event: response.output_text.delta
data: {"seq_id": 4, "type": "response.output_text.delta",
"response": {"output_index": 0, "type": "message.answer",
"delta": " Capital"}}

// Omitted for brevity

id: 32
event: response.output_text.delta
data: {"seq_id": 32, "type": "response.output_text.delta",
"response": {"output_index": 0, "type": "message.answer",
"delta": ","}}

id: 33
event: response.output_text.delta
data: {"seq_id": 33, "type": "response.output_text.delta",
"response": {"output_index": 0, "type": "message.answer",
"delta": " and economic center."}}

id: 34
event: response.output_item.done
data: {"seq_id": 34, "type": "response.output_item.done",
"response": {"output_index": 0}}

id: 35
event: response.done
data: {"seq_id": 35, "type": "response.done",
"response": {"run_time_ms": "2.286", "finished": true}}

Authorizations

​
Authorization
string
header
required

The unique API Key required to authorize API access. Learn how to get yours in the “Get your API key” section of the documentation.

Body

application/json
​
agent
string
default:express
required

The agent mode that will be used to execute your request. This parameter must be set as 'express'.

​
input
string
required

The input for the agent. This can be a query or a prompt.

Example:

"What is the capital of France?"

​
stream
boolean
default:false

When set to "true", it will enable SSE (server side events) response. This is useful if you want to stream the response to your applications (e.g., with chatbots).

​
tools
object[]

Add tools the system can call to expand its capabilities, providing more precise answers to the input query. Currently supports only the Web Search tool. See Web Search Tool for more details.

Response

Inference response in application/json or text/event-stream format.

​
output
object[]
⌘I