POST
/
v1
/
agents
/
runs
Run a Custom Agent
curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": "your_agent_ID",
  "input": "Summarize today'\''s top AI research headlines and cite sources.",
  "stream": false,
  "tools": []
}'
{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "Here are today's top AI research headlines...",
      "content": {}
    }
  ],
  "agent": "550e8400-e29b-41d4-a716-446655440000"
}
The Custom Agents API lets you run an assistant you can configure in the UI. Users can create a custom AI agent by providing a description of the desired functionality using natural language. The system supports both conversational inputs and advanced prompting techniques to define the agent’s behavior.

​
Enteprise Settings

To maintain enterprise security, enable Zero Data Retention on your enterprise account. Manage this setting at you.com/settings/privacy. When enabled, the platform does not retain your data and does not use customer data for model training.

​
Get Your Custom Agent ID

Visit you.com/agents and create a new custom agent with your personalized parameters:New agent settings for custom agents in you.comThe platform automatically populates the Agents section with all of the agents you’ve created. This is where you can retrieve each agent’s ID:The agent's ID in custom agent in you.comPaste the ID in the agent parameter to call it via API.

​
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": "your_agent_ID",
    "input": "Summarize today\'s top AI research headlines and cite sources.",
    "stream": true,
    "tools": [{ "type": "web_search" }]
  }'
Small excerpt of streaming events:
id: 0
event: response.output_item.added
data: {"seq_id":0,"type":"response.output_item.added","response":{"type":"chat_node.answer","output_index":0,"delta":"The capital of France is Pa"}}

id: 1
event: response.output_item.delta
data: {"seq_id":1,"type":"response.output_item.delta","response":{"output_index":0,"delta":"ris."}}

​
Tools

  • web_search: Lets the agent ground answers with fresh web results and citations
The system returns a 403 error if your agent requests a tool that it or the tenant is not authorized to use. Make sure to synchronize the agent’s allowlist with the tools it requests. Providing an empty array disables tools for the current run.

​
Limitations

Custom Agents configured with Advanced Reasoning or Research modes are not supported via the API.
Files attached to a Custom Agent are not accessible when the agent is invoked via the API.

​
Errors

Errors are returned 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
404agent_not_found, agent_not_supported_yetThe agent ID does not exist (or was deleted), or the agent uses an unsupported model/feature

Authorizations

​
Authorization
string
header
required

API key. Example: Authorization: Bearer $API_KEY

Body

application/json
​
agent
string
required

ID (v4) of your Custom Agent from you.com/agents.

Example:

"your_agent_ID"

​
input
required

User input prompt for the inference request.

Example:

"Summarize today's top AI research headlines and cite sources."

​
stream
boolean
default:false

When true, responses stream over SSE (text/event-stream). When false, returns JSON (application/json).

​
tools
object[]

Allowed tools for this run (must also be enabled for the agent). Currently supports web_search. See Web Search Tool for more details

Response

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

​
output
object[]
​
agent
string

The agent identifier used to generate the response.

Example:

"550e8400-e29b-41d4-a716-446655440000"