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

Authorization: Bearer $YEP_API_KEY

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

Rate Limits

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

Error Handling

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

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

Search Endpoint

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"], "location": "US"}'

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"
    ],
    "location": "US"
})
})
.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'],
        'location': 'US'
    }
)
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"], "location": "US"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

{
  "success": true,
  "request_id": "req_abc123",
  "query": "saratoga spring water",
  "type": "basic",
  "language": "en",
  "location": "DE",
  "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).

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).

Supported Locations

The following ISO 3166-1 alpha-2 country codes can be used with the location parameter. Codes are case-insensitive, and UK is accepted as an alias for GB. You can also retrieve this list programmatically via GET /api/locations (no authentication required).

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)

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

{
  "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)

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}'

{
  "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)

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

{
  "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)

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}'

{
  "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)

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

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