Send your first request

Set the key

Create an API key in Settings → API keys and store the secret in the YEP_API_KEY environment variable. Every request sends it as a Bearer token.

Authorization: Bearer <API_KEY>

Send a request

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

query holds 1 to 512 characters and limit 1 to 50 results; add lang with a two-letter code to prefer one language. The API does not paginate.

Two spellings in the query are operators: site:example.com and a quoted phrase. Query syntax lists what they do.

Read the response

{
  "request_id": "0b9f2c3e-6f1d-4c1a-9a43-2d6f1e0c8b7a",
  "duration_ms": 412,
  "select": ["url", "title", "description", "language"],
  "results": [
    {
      "rank": 1,
      "fields": {
        "url": "https://example.com/carbon-border-tax",
        "title": "Carbon border adjustment mechanisms",
        "description": "A guide to carbon border taxes and their implementation.",
        "language": "en"
      }
    }
  ]
}

• results is in rank order, and fields holds exactly the selected fields. GET always returns url, title, description and language; POST chooses them with select.
• request_id matches the X-Request-ID response header. Keep it with your logs and quote it to support.
• Only a 2xx status is a success. A malformed success body is an integration failure; do not fill in defaults.

Filter with POST

POST /api/v1/search takes the same query with a filter, a field projection and a language. This request keeps to news published in the last day and returns matching passages:

curl 'https://platform.yep.com/api/v1/search' \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "semiconductor export controls",
    "limit": 20,
    "lang": "en",
    "filter": "(@categories INCLUDES ANY [\"/News\"] AND @publish_time >= now-1d)",
    "select": ["url", "title", "publish_time", "highlights"]
  }'

Handle failures

• 429: wait the seconds in Retry-After, then retry with backoff. Other 502 and 503: retry with capped exponential backoff and jitter.
• 400, 401, 402 and 403: correct the request, the key, the funds or the permission. Do not retry an unchanged request.
• Log the status, the stable reason and the request id. Never log the key.

Before production, test one successful query, an invalid query, an invalid key and a rate-limited request.