Skip to main content
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 @- <<EOF
{
  "agent": "550e8400-e29b-41d4-a716-446655440000",
  "input": "Summarize today's top AI research headlines and cite sources.",
  "stream": false
}
EOF
{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "Here are today's top AI research headlines...",
      "content": "Summarize today's top AI research headlines and cite sources.",
      "agent": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
WARNING: Access to this endpoint requires a paid subscription plan.

​
Description

This endpoint 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. Before using it, create a custom agent and retrieve its ID.

​
Features

Custom Agent include the following features:
  • Document upload: Provide the agent with documents to process.
  • Model selection: Specify a preferred large language model (LLM) or use “auto” to optimize performance for specific tasks.
  • Web access control: Enable or disable the ability of an agent to access the web.
  • Advanced tools: Use additional tools for research and reasoning tasks.

​
Enterprise 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.
WARNING: Privacy settings can only be managed by You.com Enterprise or team admins.

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
required

The custom agent that will be used to execute your request.

Example:

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

​
input
required

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

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).

Response

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

​
output
object[]