# Yep Platform API — reference for tools and assistants

Use this document to integrate with or answer questions about the Yep Platform search API. For formal schemas and codegen, also use the OpenAPI document at `https://platform.yep.com/openapi.yaml`.

**Base URL:** `https://platform.yep.com`

---

## Authentication

Protected endpoints require an API key created in the platform dashboard. Send it as a Bearer token:

```http
Authorization: Bearer $YEP_API_KEY
```

Never expose API keys in client-side code or public repositories.

---

## Rate limits

Per API key:

- 60 requests per minute
- 3,600 requests per hour
- 86,400 requests per day

Responses include:

| Header | Meaning |
|--------|---------|
| `X-RateLimit-Limit` | Max requests per minute |
| `X-RateLimit-Remaining` | Remaining in the current window |
| `X-RateLimit-Reset` | Seconds until the window resets |

HTTP `429` when exceeded.

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

---

## Errors

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Bad request (validation) |
| 401 | Invalid or missing API credentials |
| 402 | Insufficient account balance |
| 429 | Rate limit exceeded |
| 500 | Server error |

Error bodies are JSON, typically:

```json
{
  "error": "Error message describing the issue",
  "request_id": "…"
}
```

---

## GET /api/languages

**Authentication:** none.

Returns supported ISO-style language codes and names for use with the search `language` parameter.

```http
GET https://platform.yep.com/api/languages
```

---

## POST /api/search

**Authentication:** required (Bearer).

Search the web index. Pricing is usage-based on search mode and result count. Base cost: **$0.004** (balanced) or **$0.008** (advanced) per request for up to 20 results. Each additional result above 20 adds **$0.001**. Only returned results are charged. Highlights (page excerpts) are included at no extra cost.

```http
POST https://platform.yep.com/api/search
Content-Type: application/json
Authorization: Bearer $YEP_API_KEY
```

### Request body (JSON)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | yes | Search query, 1–1000 characters |
| `type` | string | no | `basic` (default) or `highlights` (includes content snippets / chunks) |
| `limit` | integer | no | Max results (default 10, max 100) |
| `language` | array of strings | no | ISO 639-1 codes, e.g. `["en"]` or `["fr","en"]`. Full list: `GET /api/languages` |
| `search_mode` | string | no | `balanced` (default) or `advanced` (higher quality, LLM-assisted ranking) |
| `content_type` | string | no | One of the top-level types below; includes all subtypes |
| `safe_search` | boolean | no | If true, exclude Adult-category pages (default false) |
| `include_domains` | string | no | Comma-separated full URLs — only these domains |
| `exclude_domains` | string | no | Comma-separated full URLs — exclude these domains |
| `start_published_date` | string | no | ISO 8601 date (start of published range) |
| `end_published_date` | string | no | ISO 8601 date (end of published range) |
| `start_crawl_date` | string | no | ISO 8601 — crawl time range start |
| `end_crawl_date` | string | no | ISO 8601 — crawl time range end |

### Content types (`content_type`)

Selecting a type includes all ML subtypes under it (e.g. Article includes How_to, News_Update, etc.).

| Type | Example subtypes |
|------|------------------|
| Article | How_to, Tutorial_or_Guide, Listicle, Comparisons, News_Update, FAQ, Wiki, … |
| Video | How_to, Interview, Webinar, Vlog, … |
| Image | Infographic, Photography, Meme, Diagram, … |
| Audio | Podcast, Webinar, Interview, … |
| Document | Case_Study, White_Paper, Research_Paper, Report, … |
| Listing | Product, Property, Job, Service, Event, Location, Business |
| Listing_Collection | Same family as Listing |
| Landing_Page | Service_Page, Product_Page, Pricing_Page, … |
| Interactive_Tools | Calculator, SaaS_Software, Map, Quiz, … |
| User_Generated_Content | Forum_Thread, Reviews, Q_A, … |
| Core_Page | Homepage, About_Page, Contact_Page, Blog_Index, … |

### Successful response (shape)

JSON includes at least:

- `success` (boolean)
- `request_id` (string)
- `query`, `type`, `language`
- `results` — array of objects with whitelisted fields: `url`, `title`, `description`, `published_date`, `domain`, `content_type`; with `type: "highlights"`, results may also include `highlights` (snippets)
- `response_time_ms`
- `api_cost` — `{ "cost": number, "details": string }`
- `balance` — `{ "before": number, "after": number }`

Exact numeric fields depend on account balance and result count.

### Example (curl)

```bash
export YEP_API_KEY="your-api-key-here"

curl -sS -X POST 'https://platform.yep.com/api/search' \
  -H "Authorization: Bearer $YEP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"example search","type":"basic","limit":10}'
```

---

## Management keys API

Programmatically provision API keys for a single organization. Authenticates with a **management key** (distinct from search API keys), minted by an org admin at `https://platform.yep.com/app/management-keys`.

```http
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

A management key is bound to one `(organization, member)` pair — 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 **≤ the platform default for their window** — higher values are rejected with `422`.

### Key object

```json
{
  "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 (override ?? default).

### Errors

| Status | Meaning |
|--------|---------|
| 401 | Missing/invalid management key, or key lacks tenant binding |
| 404 | Unknown hash (also returned for hashes belonging to another organization) |
| 422 | Validation failure, including overrides above the platform default |

### List keys

```http
GET https://platform.yep.com/api/management/keys
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

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**

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

**Example response**

```json
{
  "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

```http
POST https://platform.yep.com/api/management/keys
Content-Type: application/json
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

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. Must be ≤ 60. Omit for the platform default. |
| `limit_per_hour` | integer | No | Per-hour request cap. Must be ≤ 3,600. Omit for the platform default. |
| `limit_per_day` | integer | No | Per-day request cap. Must be ≤ 86,400. Omit for the platform default. |

**Example request**

```bash
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**

```json
{
  "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

```http
GET https://platform.yep.com/api/management/keys/{hash}
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

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**

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

**Example response**

```json
{
  "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

```http
PATCH https://platform.yep.com/api/management/keys/{hash}
Content-Type: application/json
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

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**

```bash
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**

```json
{
  "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

```http
DELETE https://platform.yep.com/api/management/keys/{hash}
Authorization: Bearer $YEP_MANAGEMENT_KEY
```

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**

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

**Example response**

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

---

## Machine-readable spec

- **OpenAPI 3.1:** `https://platform.yep.com/openapi.yaml`

---

## Support

Questions: support@yep.com