Get started with Yep API

To get started, sign up for free. Once you have your API key, you're ready to make your first API call.

Authentication

All API requests require authentication using your API key. Pass it in the Authorization header:

Authorization: Bearer $YEP_API_KEY

Keep your API key secure! Never expose it in client-side code or public repositories.

You can manage your API keys in the API Keys section.

Rate Limits

To ensure optimal performance for all users, the API enforces the following rate limits:

60 requests per minute per API key
3,600 requests per hour per API key
86,400 requests per day per API key

If you exceed any of these limits, you'll receive a 429 Too Many Requests response.

All API responses include rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Seconds until the rate limit window resets

Org admins can tighten these per-key via the management keys API.

Need higher limits? Contact our support team to discuss enterprise options.

Error Handling

The API uses standard HTTP status codes and returns error details in the response body:

Status code	Description
200	Success
400	Bad Request — Missing or invalid parameters
401	Unauthorized — Invalid API credentials
402	Payment Required — Insufficient account balance
403	Forbidden — Insufficient permissions
404	Not Found — Endpoint or resource not found
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Error response format

{
  "error": "Error message describing the issue",
  "request_id": "req_abc123"
}

Search Endpoint

POST /api/search

Search for content across the platform. Returns a list of matching items by proxying to our advanced search service.

Base cost: $0.004/request (balanced) or $0.008/request (advanced) for up to 20 results. Each additional result adds $0.001. Only returned results are charged. Highlights are included at no extra cost.

Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query string (1–1,000 characters)
type	string	No	Type of search: "basic" (default) or "highlights". The basic search includes URL, meta titles, and meta descriptions. The highlights search additionally includes relevant text highlights from the page content.
limit	integer	No	Maximum number of results to return (default: 10, max: 100)
language	array	No	Filter results by language using ISO 639-1 codes. Pass as an array (e.g., ["en"], ["fr", "en"]). See Supported Languages.
search_mode	string	No	Search mode: "balanced" (default) or "advanced". Balanced combines speed and relevance ($0.004 base). Advanced adds LLM ranking for highest quality ($0.008 base). Additional results above 20 cost $0.001 each.
content_type	string	No	Filter by content type. Selecting a type includes all its subtypes. See Content Types.
safe_search	boolean	No	Exclude pages classified under the Adult category (default: false).
include_domains	string	No	Comma-separated full URLs. Only return results from these domains (e.g., `https://example.com,https://other.com`).
exclude_domains	string	No	Comma-separated full URLs. Exclude results from these domains.
start_published_date	string	No	Filter by page published date (start). ISO 8601 format: `2024-01-15` or `2024-01-15T12:30:00Z`.
end_published_date	string	No	Filter by page published date (end). ISO 8601 format.
start_crawl_date	string	No	Filter by when the page was last crawled (start). ISO 8601 format.
end_crawl_date	string	No	Filter by when the page was last crawled (end). ISO 8601 format.

Example Request

curl -X POST "https://platform.yep.com/api/search" \
     -H "Authorization: Bearer $YEP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "saratoga spring water", "type": "basic", "limit": 10, "language": ["en"]}'

const YEP_API_KEY = process.env.YEP_API_KEY;

fetch('https://platform.yep.com/api/search', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${YEP_API_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
    "query": "saratoga spring water",
    "type": "basic",
    "limit": 10,
    "language": [
        "en"
    ]
})
})
.then(response => response.json())
.then(data => console.log(data));

import os
import requests

response = requests.post(
    'https://platform.yep.com/api/search',
    headers={'Authorization': f'Bearer {os.environ["YEP_API_KEY"]}'},
    json={
        'query': 'saratoga spring water',
        'type': 'basic',
        'limit': 10,
        'language': ['en']
    }
)
print(response.json())

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://platform.yep.com/api/search');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . getenv('YEP_API_KEY'),
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"query": "saratoga spring water", "type": "basic", "limit": 10, "language": ["en"]}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Example Responses

{
  "success": true,
  "request_id": "req_abc123",
  "query": "saratoga spring water",
  "type": "basic",
  "language": "en",
  "results": [
    // Array of search results from our backend search service
  ],
  "response_time_ms": 145.67,
  "api_cost": {
    "cost": 0.004,
    "details": "(4/1000)"
  },
  "balance": {
    "before": 9.50,
    "after": 9.496
  }
}

{
  "error": "Search query (query) is required.",
  "request_id": "req_abc123"
}

{
  "error": "Type parameter must be either \"basic\" or \"highlights\".",
  "request_id": "req_abc123"
}

{
  "error": "Insufficient funds. Please add funds to your account.",
  "balance": 0.002,
  "required": 0.014,
  "request_id": "req_abc123"
}

Content Types

The following content types can be used with the content_type parameter. Selecting a type automatically includes all its subtypes (111 total subtypes across all types).

Type	Example Subtypes
`Article`	How_to, Tutorial_or_Guide, Listicle, Comparisons, Roundup, Product_or_Brand_Review, Opinion_Piece, News_Update, Recipe, FAQ, Wiki
`Video`	How_to, Tutorial_or_Guide, Listicle, Comparisons, Product_or_Brand_Review, News_Update, Interview, Webinar, Vlog
`Image`	Infographic, Photography, Vector_Illustration, Meme, Diagram, Flowchart
`Audio`	Podcast, Webinar, Interview, Music, Audiobook
`Document`	Case_Study, Ebook, White_Paper, Research_Paper, Template, Report, Manual
`Listing`	Product, Property, Job, Service, Event, Location, Business
`Listing_Collection`	Product, Property, Job, Service, Event, Location, Business
`Landing_Page`	Service_Page, Location_Page, Product_Page, Pricing_Page
`Interactive_Tools`	Calculator, SaaS_Software, Map, Quiz, Generator
`User_Generated_Content`	Forum_Thread, Discussions, Social_Media_Post, Reviews, Q_A
`Core_Page`	Homepage, About_Page, Contact_Page, FAQ_Page, Blog_Index, Careers_Page

Supported Languages

The following ISO 639-1 language codes can be used with the language parameter. You can also retrieve this list programmatically via GET /api/languages (no authentication required).

Code	Language
`aa`	Afar
`ab`	Abkhazian
`ae`	Avestan
`af`	Afrikaans
`ak`	Akan
`am`	Amharic
`an`	Aragonese
`ar`	Arabic
`as`	Assamese
`av`	Avaric
`ay`	Aymara
`az`	Azerbaijani
`ba`	Bashkir
`be`	Belarusian
`bg`	Bulgarian
`bi`	Bislama
`bm`	Bambara
`bn`	Bengali
`bo`	Tibetan
`br`	Breton
`bs`	Bosnian
`ca`	Catalan
`ce`	Chechen
`ch`	Chamorro
`co`	Corsican
`cr`	Cree
`cs`	Czech
`cu`	Church Slavonic
`cv`	Chuvash
`cy`	Welsh
`da`	Danish
`de`	German
`dv`	Divehi
`dz`	Dzongkha
`ee`	Ewe
`el`	Greek
`en`	English
`eo`	Esperanto
`es`	Spanish
`et`	Estonian
`eu`	Basque
`fa`	Persian
`ff`	Fulah
`fi`	Finnish
`fj`	Fijian
`fo`	Faroese
`fr`	French
`fy`	Western Frisian
`ga`	Irish
`gd`	Gaelic
`gl`	Galician
`gn`	Guarani
`gu`	Gujarati
`gv`	Manx
`ha`	Hausa
`he`	Hebrew
`hi`	Hindi
`ho`	Hiri Motu
`hr`	Croatian
`ht`	Haitian
`hu`	Hungarian
`hy`	Armenian
`hz`	Herero
`ia`	Interlingua
`id`	Indonesian
`ie`	Interlingue
`ig`	Igbo
`ii`	Sichuan Yi
`ik`	Inupiaq
`io`	Ido
`is`	Icelandic
`it`	Italian
`iu`	Inuktitut
`ja`	Japanese
`jv`	Javanese
`ka`	Georgian
`kg`	Kongo
`ki`	Kikuyu
`kj`	Kuanyama
`kk`	Kazakh
`kl`	Kalaallisut
`km`	Central Khmer
`kn`	Kannada
`ko`	Korean
`kr`	Kanuri
`ks`	Kashmiri
`ku`	Kurdish
`kv`	Komi
`kw`	Cornish
`ky`	Kyrgyz
`la`	Latin
`lb`	Luxembourgish
`lg`	Ganda
`li`	Limburgan
`ln`	Lingala
`lo`	Lao
`lt`	Lithuanian
`lu`	Luba-Katanga
`lv`	Latvian
`mg`	Malagasy
`mh`	Marshallese
`mi`	Maori
`mk`	Macedonian
`ml`	Malayalam
`mn`	Mongolian
`mr`	Marathi
`ms`	Malay
`mt`	Maltese
`my`	Burmese
`na`	Nauru
`nb`	Norwegian Bokmål
`nd`	North Ndebele
`ne`	Nepali
`ng`	Ndonga
`nl`	Dutch
`nn`	Norwegian Nynorsk
`no`	Norwegian
`nr`	South Ndebele
`nv`	Navajo
`ny`	Chichewa
`oc`	Occitan
`oj`	Ojibwa
`om`	Oromo
`or`	Oriya
`os`	Ossetian
`pa`	Punjabi
`pi`	Pali
`pl`	Polish
`ps`	Pashto
`pt`	Portuguese
`qu`	Quechua
`rm`	Romansh
`rn`	Rundi
`ro`	Romanian
`ru`	Russian
`rw`	Kinyarwanda
`sa`	Sanskrit
`sc`	Sardinian
`sd`	Sindhi
`se`	Northern Sami
`sg`	Sango
`si`	Sinhala
`sk`	Slovak
`sl`	Slovenian
`sm`	Samoan
`sn`	Shona
`so`	Somali
`sq`	Albanian
`sr`	Serbian
`ss`	Swati
`st`	Southern Sotho
`su`	Sundanese
`sv`	Swedish
`sw`	Swahili
`ta`	Tamil
`te`	Telugu
`tg`	Tajik
`th`	Thai
`ti`	Tigrinya
`tk`	Turkmen
`tl`	Tagalog
`tn`	Tswana
`to`	Tonga
`tr`	Turkish
`ts`	Tsonga
`tt`	Tatar
`tw`	Twi
`ty`	Tahitian
`ug`	Uighur
`uk`	Ukrainian
`ur`	Urdu
`uz`	Uzbek
`ve`	Venda
`vi`	Vietnamese
`vo`	Volapük
`wa`	Walloon
`wo`	Wolof
`xh`	Xhosa
`yi`	Yiddish
`yo`	Yoruba
`za`	Zhuang
`zh`	Chinese
`zu`	Zulu

Management Keys

Programmatically provision API keys for your organization. Authenticates with a management key, distinct from the search API keys above. Org admins mint management keys at Management keys.

Authorization: Bearer $YEP_MANAGEMENT_KEY

A management key is bound to one organization and one member; every call operates inside that scope. Keys are identified by their SHA-256 hash in all URLs.

Per-key limits

Each API key has three optional overrides: limit_per_minute, limit_per_hour, limit_per_day. When null, the platform defaults apply (60 / 3,600 / 86,400). Overrides must be at most the platform default for their window — higher values are rejected with 422.

Key object

{
  "hash": "6b3c…",
  "label": "yep_1a2b3c4d",
  "name": "production",
  "disabled": false,
  "limit_per_minute": 10,
  "limit_per_hour": null,
  "limit_per_day": null,
  "effective_limit_per_minute": 10,
  "effective_limit_per_hour": 3600,
  "effective_limit_per_day": 86400,
  "last_used_at": "2026-04-17T10:42:11+00:00",
  "created_at": "…",
  "updated_at": "…"
}

limit_per_* is the stored override; null means the platform default applies.
effective_limit_per_* is what's enforced right now.

List keys

GET /api/management/keys

List every API key in the organization. Results are ordered newest first.

Request parameters (query string)

Parameter	Type	Required	Description
offset	integer	No	Pagination offset (default 0).
limit	integer	No	Page size (default 100, max 100).

Example request

curl -sS 'https://platform.yep.com/api/management/keys?limit=50' \
  -H "Authorization: Bearer $YEP_MANAGEMENT_KEY"

Example response

{
  "data": [
    {
      "hash": "6b3c…",
      "label": "yep_1a2b3c4d",
      "name": "production",
      "disabled": false,
      "limit_per_minute": 10,
      "limit_per_hour": null,
      "limit_per_day": null,
      "effective_limit_per_minute": 10,
      "effective_limit_per_hour": 3600,
      "effective_limit_per_day": 86400,
      "last_used_at": "2026-04-17T10:42:11+00:00",
      "created_at": "…",
      "updated_at": "…"
    }
  ]
}

Create key

POST /api/management/keys

Create a new API key under this organization, owned by the member bound to your management key. The plaintext token is returned once; only its hash is stored.

Request parameters (JSON body)

Parameter	Type	Required	Description
name	string	Yes	Human-readable label (max 100 characters).
limit_per_minute	integer	No	Per-minute request cap for this key. Must be ≤ 60. Omit for the platform default.
limit_per_hour	integer	No	Per-hour request cap for this key. Must be ≤ 3,600. Omit for the platform default.
limit_per_day	integer	No	Per-day request cap for this key. Must be ≤ 86,400. Omit for the platform default.

Example request

curl -sS -X POST 'https://platform.yep.com/api/management/keys' \
  -H "Authorization: Bearer $YEP_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"production","limit_per_minute":10}'

Example response

{
  "key": "plaintext-token-shown-once",
  "data": {
    "hash": "6b3c…",
    "label": "yep_1a2b3c4d",
    "name": "production",
    "disabled": false,
    "limit_per_minute": 10,
    "limit_per_hour": null,
    "limit_per_day": null,
    "effective_limit_per_minute": 10,
    "effective_limit_per_hour": 3600,
    "effective_limit_per_day": 86400,
    "last_used_at": null,
    "created_at": "2026-04-17T10:42:11+00:00",
    "updated_at": "2026-04-17T10:42:11+00:00"
  }
}

Get key

GET /api/management/keys/{hash}

Fetch a single key by its SHA-256 hash. Returns 404 when the hash is unknown or belongs to another organization.

Request parameters (path)

Parameter	Type	Required	Description
hash	string	Yes	64-character SHA-256 hash of the target API key.

Example request

curl -sS 'https://platform.yep.com/api/management/keys/6b3c…' \
  -H "Authorization: Bearer $YEP_MANAGEMENT_KEY"

Example response

{
  "data": {
    "hash": "6b3c…",
    "label": "yep_1a2b3c4d",
    "name": "production",
    "disabled": false,
    "limit_per_minute": 10,
    "limit_per_hour": null,
    "limit_per_day": null,
    "effective_limit_per_minute": 10,
    "effective_limit_per_hour": 3600,
    "effective_limit_per_day": 86400,
    "last_used_at": "2026-04-17T10:42:11+00:00",
    "created_at": "…",
    "updated_at": "…"
  }
}

Update key

PATCH /api/management/keys/{hash}

Partially update a key. Any limit_per_* field may be set to null to clear the override and revert to the platform default.

Request parameters (JSON body — all optional)

Parameter	Type	Required	Description
name	string	No	New label (max 100 characters).
disabled	boolean	No	`true` blocks all `/api/search` calls using this key.
limit_per_minute	integer \| null	No	New per-minute override (must be ≤ 60), or `null` to clear.
limit_per_hour	integer \| null	No	New per-hour override (must be ≤ 3,600), or `null` to clear.
limit_per_day	integer \| null	No	New per-day override (must be ≤ 86,400), or `null` to clear.

Example request

curl -sS -X PATCH 'https://platform.yep.com/api/management/keys/6b3c…' \
  -H "Authorization: Bearer $YEP_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"disabled":true,"limit_per_minute":5}'

Example response

{
  "data": {
    "hash": "6b3c…",
    "label": "yep_1a2b3c4d",
    "name": "production",
    "disabled": true,
    "limit_per_minute": 5,
    "limit_per_hour": null,
    "limit_per_day": null,
    "effective_limit_per_minute": 5,
    "effective_limit_per_hour": 3600,
    "effective_limit_per_day": 86400,
    "last_used_at": "2026-04-17T10:42:11+00:00",
    "created_at": "…",
    "updated_at": "2026-04-17T10:50:00+00:00"
  }
}

Delete key

DELETE /api/management/keys/{hash}

Revoke a key (soft-delete). Subsequent calls to /api/search with the underlying token return 401.

Request parameters (path)

Parameter	Type	Required	Description
hash	string	Yes	64-character SHA-256 hash of the target API key.

Example request

curl -sS -X DELETE 'https://platform.yep.com/api/management/keys/6b3c…' \
  -H "Authorization: Bearer $YEP_MANAGEMENT_KEY"

Example response

{
  "data": {
    "hash": "6b3c…",
    "deleted": true
  }
}