Sign in

v1

latestOpenAPI 3.1.02026-07-1212321.4 KB

Run an Agent

Execute queries using You.com's AI agents. This endpoint supports three agent types:

  • Express Agent: Fast responses with optional web search (max 1 search)
  • Advanced Agent: Complex queries with multi-turn reasoning, planning, and tool usage
  • Custom Agent: User-configured assistants created in the You.com UI

The response format depends on the stream parameter - either a complete JSON payload or Server-Sent Events (SSE).

post/v1/agents/runs

Request body

OR
OR

Example request

{
  "agent": "express",
  "input": "What are some great recipes I can make in under half an hour"
}

Response

Successful agent response. The content type depends on the stream parameter:

  • When stream: false - Returns complete JSON response (application/json)
  • When stream: true - Returns Server-Sent Events stream (text/event-stream)
agentstring required

The id of the agent populated in the request.

modestring

The mode of the agent

Example response

{
  "agent": "express",
  "mode": "express",
  "input": [
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "output": [
    {
      "text": "#### Capital of France\n\nThe capital of France is **Paris**. It is not only the capital but also the most populous city in the country. Paris is situated on the Seine River in the northern part of France, within the Île-de-France region. It serves as the main cultural, economic, and political center of France [[1]](https://www.coe.int/en/web/interculturalcities/paris)[[2]](https://en.wikipedia.org/wiki/Paris).",
      "type": "web_search.results",
      "content": [
        {
          "source_type": "web_search",
          "citation_uri": "https://www.foodnetwork.com/recipes/photos/30-minute-dinner-recipes",
          "title": "103 Easy 30-Minute Dinner Recipes That Will Save Your Weeknights",
          "snippet": "Apr 11, 2025 ... These quick dinner ideas will help you get a meal on the table in half an hour or less. ... It's a simple recipe ready in under half an hour with ...",
          "thumbnail_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQJTNucjGK8ZqfurwAmyuyhQ-7n7AVZHoJwUqfsqRYuCqlIpMwepNDEE_M&s",
          "url": "https://www.foodnetwork.com/recipes/photos/30-minute-dinner-recipes"
        }
      ]
    }
  ]
}
All 1 operations