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 your_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
  • 3,600 requests per hour
  • 86,400 requests per day

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

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
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error response format

{
  "error": "Error message describing the issue"
}

Search Endpoint

POST /api/search

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

Each call to this endpoint costs $0.0001.

Request Parameters

Parameter Type Required Description
query string Yes Search query string
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: "fast" or "balanced" (default). Fast returns results quickly, Balanced combines speed and relevance.
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 your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"query": "saratoga spring water", "type": "basic", "limit": 10, "language": ["en"]}'
fetch('https://platform.yep.com/api/search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_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 requests

response = requests.post(
    'https://platform.yep.com/api/search',
    headers={'Authorization': 'Bearer your_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 your_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,
  "query": "saratoga spring water",
  "type": "basic",
  "language": "en",
  "results": [
    // Array of search results from our backend search service
  ],
  "response_time_ms": 145.67
}
{
  "error": "Search query (query) is required."
}
{
  "error": "Type parameter must be either \"basic\" or \"highlights\"."
}
{
  "error": "Insufficient funds. Please add funds to your account.",
  "balance": 0.05,
  "required": 0.0001
}

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
ArticleHow_to, Tutorial_or_Guide, Listicle, Comparisons, Roundup, Product_or_Brand_Review, Opinion_Piece, News_Update, Recipe, FAQ, Wiki
VideoHow_to, Tutorial_or_Guide, Listicle, Comparisons, Product_or_Brand_Review, News_Update, Interview, Webinar, Vlog
ImageInfographic, Photography, Vector_Illustration, Meme, Diagram, Flowchart
AudioPodcast, Webinar, Interview, Music, Audiobook
DocumentCase_Study, Ebook, White_Paper, Research_Paper, Template, Report, Manual
ListingProduct, Property, Job, Service, Event, Location, Business
Listing_CollectionProduct, Property, Job, Service, Event, Location, Business
Landing_PageService_Page, Location_Page, Product_Page, Pricing_Page
Interactive_ToolsCalculator, SaaS_Software, Map, Quiz, Generator
User_Generated_ContentForum_Thread, Discussions, Social_Media_Post, Reviews, Q_A
Core_PageHomepage, 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