---
name: yep-search
description: Search the web with the Yep Search API when a task needs current external sources or ranked web results.
---

# Search with Yep

Use the Yep Search API for requests that need web search results.

1. Read `YEP_API_KEY` from the environment. If it is missing, explain that it must be set and stop. Never ask the user to paste the key into chat, print it, or write it to source control.
2. Send the request with cURL, replacing the example query with the user's search terms:

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

3. Keep `query` between 1 and 512 characters. Use `limit` from 1 to 50. Add `lang` only when the user requests a two-letter lowercase language code.
4. The response is a JSON object. Read ranked results from `results`; each result has a `rank` and a `fields` object holding `url`, `title`, `description`, and `language`. Preserve the API's result order. Report each useful result with its title, URL, and description. Treat absent optional language values as absent rather than inventing them.
5. If the request fails, report the HTTP status, stable error reason, and request reference when present. Never expose the API key or raw sensitive diagnostics.

Do not claim that a result is accurate or relevant merely because the API returned it. Distinguish facts supported by the returned sources from your own inference.