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": {}
    }
  ],
  "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

Authorizations

Authorization
string
header
required

A unique API Key required to authorize API access. Ensure it is kept confidential. Get a free API Key at you.com/platform. Example: Authorization: Bearer $API_KEY

Body

application/json
agent
string
default:express
required

The agent must be set as 'express'.

input
string
required

User input prompt.

stream
boolean
default:false
tools
object[]

Response

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

output
object[]
agent
string

The type of agent used to generate the response.

Example:

"express"