Skip to content
Ctrl/⌘ K

Agent API

Choose the Search API or Agent API

Choose ranked results or a model-written report for each workload.

Use the Search API when your application needs ranked pages that it will filter, rerank, or pass to its own model.

Request cURL 
curl --get "https://yep.com/api/v1/search" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --data-urlencode 'query=carbon border tax 2026'

The Search API is plain search: one query enters, ranked results return, and the request ends. Use GET for a small query or POST when you need typed filters and an explicit result projection.

Run one agent

Use the Agent API when the output should be a sourced report rather than a result list.

Request cURL 
curl --request POST "https://yep.com/api/v1/agent" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "mode": "light",
  "input": "Summarize the latest carbon border tax guidance.",
  "model": {
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4.5"
  },
  "background": false
}
JSON

The agent searches the same index, decides which evidence to inspect, and writes a report with sources. light is the shorter evidence pass. deep is the longer research pass. Set background when the caller should receive polling credentials instead of holding one connection open.

Choose by output

  • Choose the Search API when your code owns ranking, extraction, prompting, and presentation.
  • Choose the Agent API when Yep should search, inspect evidence, and assemble the report.
  • Choose domain search when the items you need are sites rather than pages.
  • Choose the query builder when a model should construct a typed Search API request without executing it.

Search API requests use search permission and Search API billing. Agent runs and query-builder calls use agent permission, a stored model provider key, and Agent API billing. The provider also charges model usage to that provider key. Read errors, limits, and billing before deploying either path.

Use REST or MCP

REST exposes the same operations as stable HTTP contracts. MCP exposes search, domain search, model discovery, query building, and agent execution as typed tools through OAuth. Use REST when your application controls the calls. Use MCP when an AI client should choose and call the tools.

Continue with BYOK model setup or open the Agent API reference.

Commands