Give your AI agent the ytapis manual

# ytapis — Master Build Prompt for AI Coding Agents

You are my coding assistant. I want you to build an application that uses **ytapis**, a free, unofficial YouTube data API. It needs no API key, no OAuth, and no sign-up. Read this whole document before you write any code.

---

## 1. What ytapis is

- **Purpose:** Search YouTube and read public video, channel, playlist, comment, transcript, live-stream, and Shorts data as clean JSON.
- **Base URL (HTTP API, hosted on Cloudflare Workers):** `https://ytapis.djalokyt27.workers.dev`
- **No authentication.** Do not add an API key, token, or OAuth header. None is needed.
- **CORS is open** (`Access-Control-Allow-Origin: *`), so browser JavaScript can call the API directly.
- **Unofficial.** ytapis reads public YouTube pages. It is not affiliated with or endorsed by YouTube or Google. It can break whenever YouTube changes its pages, so the code you write must handle failure gracefully.
- **Responses are JSON.** Errors look like `{ "error": "message" }` with a 4xx or 5xx status.

---

## 2. Ground rules for you (the agent)

1. **Use only the endpoints and fields listed in this document.** Do not invent endpoints, query parameters, or fields. If you need something that is not listed, say so and ask me.
2. **Prefer plain HTTP** (`fetch` in JavaScript/TypeScript, `requests` or `httpx` in Python, `curl` for testing) unless I explicitly ask for an SDK.
3. **Treat every field as optional.** Strings can be empty, numbers can be 0, and some fields can be `null`. Arrays can be empty `[]`. Never assume a result has data.
4. **Be a polite client.**
   - Cache responses (5 to 10 minutes is a good default).
   - Add a 200 to 500 ms delay between bulk requests.
   - Do not fire many requests in parallel.
   - Retry transient failures (HTTP 429, 5xx, network errors) with exponential backoff: about 3 to 5 attempts, starting near 500 ms and capping near 8 seconds.
5. **Respect YouTube and creators.** Do not download, re-host, or re-encode video files. Show attribution when you display results: the channel name, plus a link to the video on YouTube. Do not build a tool that scrapes YouTube at scale or bypasses protections.
6. **Show empty states honestly.** If an endpoint returns `[]`, display a clear message such as "No results right now." Never fabricate data to fill the gap.
7. **Validate input before you call the API.**
   - Video IDs are exactly 11 characters from `A-Z a-z 0-9 _ -`.
   - Limits are integers from 1 to 50 (see section 4 for the exact limits per endpoint).
   - Search queries must not be empty.
8. **Work in small verified steps.** Run the code, call the real API, and show me the actual output before you say the work is finished.

---

## 3. Known behaviour (read carefully)

- **Search and Shorts return a plain JSON array**, not an object such as `{ "results": [...] }`. The array is the top-level JSON value.
- **`limit` is a maximum, not a guarantee.** YouTube often returns fewer items than requested. For example, `limit=100` returned only 13 results when last tested. Never assume you receive exactly `limit` items. A non-numeric `limit` such as `limit=abc` is not rejected, so validate it yourself.
- **Some endpoints return empty results right now.** When last tested, these returned `[]`: `/trending`, `/video/{id}/comments`, `/video/{id}/related`, `/video/{id}/transcript`, `/channel/{id}`, and `/playlist/{id}`. `/channel/{id}/metadata` returned mostly empty fields. Treat these endpoints as optional. Build the UI so it still works when they return nothing, and say so in the UI.
- **Some requests succeed with placeholder data.** `/video/{id}` returns a fallback object (for example, title "Video abc") for an invalid or unknown ID. It does not return a 404. Validate IDs yourself before you call it.
- **Missing required parameters.**
  - `/shorts` without `q` returns `400 {"error":"Missing query param \"q\""}`.
  - `/` without `q` returns an HTML landing page, not JSON. Always send `q`.
  - Unknown routes return `404 {"error":"Not found"}`.
- **Parameters the Worker reads:** `q` and `limit` (search and list routes), `lang` (transcript), and `token` (continue). It ignores `sort` on comments and does not read `gl` or `hl`.
- **Pagination over HTTP is limited.** The HTTP API does not hand you a continuation token. The `/continue` endpoint needs a token that comes from the SDK. Do not build pagination on the HTTP API unless you have a token. Use a larger `limit` instead.
- **Type notes:**
  - `durationSeconds`, `viewCountRaw`, and `viewCount` (in stats) are numbers.
  - `isLive`, `isUpcoming`, and `isVerified` are booleans. `/video/:id` always returns `isLive` and `isUpcoming` as false, so use `/video/:id/live` for live state.
  - `viewCount` and `duration` in `VideoResult` are display strings such as `"1.8B views"` and `"3:33"`. Use the numeric fields for sorting and math.

---

## 4. HTTP endpoints

All endpoints use `GET`. Replace `https://ytapis.djalokyt27.workers.dev` with the base URL shown in section 1.

| # | Path | Parameters | Returns |
|---|------|-----------|---------|
| 1 | `/?q=QUERY&limit=N` | `q` required. `limit` 1 to 50, default 15. | `VideoResult[]` |
| 2 | `/trending?limit=N` | `limit` 1 to 50, default 15. May be empty. | `VideoResult[]` |
| 3 | `/shorts?q=QUERY&limit=N` | `q` required. `limit` 1 to 50, default 15. | `VideoResult[]` |
| 4 | `/continue?token=TOKEN&limit=N` | Token must come from the SDK. | `VideoResult[]` |
| 5 | `/channel/CHANNEL_ID?limit=N` | Channel ID, for example `UC...`. May be empty. | `VideoResult[]` |
| 6 | `/channel/CHANNEL_ID/metadata` | Channel ID. | `ChannelMetadata` object (fields may be empty) |
| 7 | `/playlist/PLAYLIST_ID?limit=N` | Playlist ID. May be empty. | `VideoResult[]` |
| 8 | `/video/VIDEO_ID` | 11-character video ID. | `VideoResult` object |
| 9 | `/video/VIDEO_ID/comments?limit=N` | `limit` 1 to 100, default 20. Any `sort` value is ignored. May be empty. | Array of comment objects (`id`, `text`, `likeCount`, `publishedTime`, `replyCount`, `isPinned`, `isLikedByCreator`, `replies`, `author`) |
| 10 | `/video/VIDEO_ID/related?limit=N` | `limit` 1 to 50, default 15. May be empty. | Array of related-video objects |
| 11 | `/video/VIDEO_ID/stats` | 11-character video ID. | `VideoStats` object |
| 12 | `/video/VIDEO_ID/live` | 11-character video ID. | `LiveStreamInfo` object |
| 13 | `/video/VIDEO_ID/transcript?lang=en` | `lang` is an optional language code. May be empty. | `TranscriptEntry[]` |
| 14 | `/health` | none | `{ "status": "ok", "version": "2.0.0" }` |

### Example requests

```
GET https://ytapis.djalokyt27.workers.dev/?q=lofi%20hip%20hop&limit=10
GET https://ytapis.djalokyt27.workers.dev/video/dQw4w9WgXcQ
GET https://ytapis.djalokyt27.workers.dev/video/dQw4w9WgXcQ/stats
GET https://ytapis.djalokyt27.workers.dev/video/dQw4w9WgXcQ/live
GET https://ytapis.djalokyt27.workers.dev/health
```

Always URL-encode query strings. In JavaScript, use `encodeURIComponent(query)`. In Python, pass a `params` dictionary to `requests`.

---

## 5. Data shapes

### VideoResult (18 fields). Returned by search, trending, shorts, channel, playlist, and video.

| Field | Type | Example or notes |
|-------|------|------------------|
| `id` | string | `"dQw4w9WgXcQ"` |
| `title` | string | Video title |
| `author` | string | Channel name |
| `channelUrl` | string | Sometimes relative, such as `/@handle`. Prefix `https://www.youtube.com` when it starts with `/`. |
| `thumbnail` | string | Image URL, may be empty |
| `thumbnails` | array | `[{ "url", "width", "height" }]` |
| `fullUrl` | string | `https://www.youtube.com/watch?v=ID` |
| `embedUrl` | string | `https://www.youtube.com/embed/ID?rel=0` |
| `duration` | string | `"3:33"` or `"1:00:17"`. May be empty for live streams. |
| `durationSeconds` | number | `213` |
| `viewCount` | string | `"1.8B views"` (display text) |
| `viewCountRaw` | number | `1824726106` |
| `publishedTime` | string | `"3 years ago"` (display text, may be empty) |
| `description` | string | First part of the description |
| `channelAvatar` | string | Channel picture URL, may be empty |
| `isLive` | boolean | |
| `isUpcoming` | boolean | Unreliable. Returned as true for any non-live video with zero viewers on `/live`. Check `isLive` and `scheduledStartTime` together. |
| `isVerified` | boolean | |

### VideoStats. Returned by `/video/{id}/stats`.

`views` (number), `likes` (number or null), `comments` (always 0, because the Worker hard-codes it), `isLive` (boolean), `viewerCount` (number or null).

### LiveStreamInfo. Returned by `/video/{id}/live`.

`isLive`, `isUpcoming` (booleans), `viewerCount` (number), `viewerCountStr` (string), `startTime` (string), `scheduledStartTime` (string), `likesCount` (number), `dislikesCount` (number).

### ChannelMetadata. Returned by `/channel/{id}/metadata`.

`id`, `name`, `handle`, `url`, `avatar`, `banner`, `description`, `subscriberCount` (display string), `subscriberCountRaw` (number), `videoCount` (display string), `videoCountRaw` (number), `isVerified` (boolean), `socialLinks` (array).

### TranscriptEntry. Returned by `/video/{id}/transcript`.

`text` (string), `start` (seconds, number), `duration` (seconds, number).

### Comments

Each comment is an object with fields such as `text`, `author` (with a `name`), and `likeCount`. Inspect a real response before you write code that depends on the exact field names.

---

## 6. Optional SDKs (only if I ask for one)

- **TypeScript / JavaScript:** `npm install ytapis-core`. Import from `'ytapis-core'`. Do **not** install a package named `ytapis` on npm, because it does not exist.
  - `search(query, { limit })` returns an object with `results` and `continuation`.
  - Other verified exports: `getVideo`, `getVideoStats`, `getLiveStreamInfo`, `getTranscript`, `getComments`, `getRelatedVideos`, `getChannelMetadata`, `searchTrending`, `searchShorts`, `searchChannel`, `searchPlaylist`, `searchContinue`, `createClient`, `withRetry`, `LRUCache`.
- **Python:** `pip install ytapis`. Import from `ytapis`.
  - `search(query, limit=15)` returns a list of `VideoResult` objects with attributes such as `title`, `view_count`, `duration`, and `is_verified`.
  - Also exported: `get_video(video_id)`, `search_continue(...)`, and `search_dicts(query, limit)`.

---

## 7. Starter recipes

**Search and show results in plain HTML and JavaScript**

```js
const API = 'https://ytapis.djalokyt27.workers.dev';

async function searchVideos(query, limit = 10) {
  const url = `${API}/?q=${encodeURIComponent(query)}&limit=${limit}`;
  const res = await fetch(url, { headers: { Accept: 'application/json' } });
  if (!res.ok) throw new Error(`API returned ${res.status}`);
  const videos = await res.json();      // plain array
  return Array.isArray(videos) ? videos : [];
}
```

**Check which live streams are on air (poll slowly)**

```js
async function isLive(videoId) {
  const res = await fetch(`${API}/video/${videoId}/live`);
  if (!res.ok) return false;
  const info = await res.json();
  return Boolean(info.isLive);
}
```

**Retry with exponential backoff**

```js
async function withBackoff(fn, retries = 4, base = 500, cap = 8000) {
  for (let attempt = 0; ; attempt++) {
    try { return await fn(); }
    catch (err) {
      if (attempt >= retries) throw err;
      const delay = Math.min(cap, base * 2 ** attempt) * (0.5 + Math.random() / 2);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}
```

---

## 8. What I want you to do now

1. **Ask me at most three short questions** if anything is unclear. Cover: the language or framework I want, where the app runs (browser, server, or command line), and what the output should look like. If I do not answer, choose sensible defaults (for example, a single HTML file with plain JavaScript, or Node.js 20 with Express) and state the choice.
2. **Plan** in five bullet points or fewer.
3. **Build** the app in small steps. Keep the code readable, with comments only where they help.
4. **Test with real calls.** Run `/health`, then search for "cats" with `limit=3`, then fetch video `dQw4w9WgXcQ` and its stats. Show me the output.
5. **Handle failure states** in the UI: loading, empty results, API errors, and offline mode.
6. **Finish with** a summary that lists the files you created, the exact command or steps to run the app, and any known limitations, including endpoints that returned empty results during your tests.