# VidCrawl API Reference

Canonical HTML UI: https://vidcrawl.com/api-reference
OpenAPI 3.1 JSON: https://vidcrawl.com/docs/json
Canonical Agent Skill: https://vidcrawl.com/skill.md
Remote MCP Endpoint: https://vidcrawl.com/mcp

## Base URL and Authentication

- Base URL: `https://vidcrawl.com`
- Authenticate with `Authorization: Bearer <VIDCRAWL_API_KEY>` or `x-api-key: <VIDCRAWL_API_KEY>`.
- Do not send conflicting values across both headers.
- Request body size limit: 65536 bytes.
- Response headers: `X-Request-Id`, `X-Credits-Used`, `X-Credits-Remaining`, and `X-Cache` (`HIT` or `MISS` on `/v1/scrape`).

## Pricing and Credits

- New accounts receive 100 free credits.
- Starter Pack: 1,000 credits for $9 (never expire).
- Growth Pack: 4,000 credits for $29 (never expire).
- Failed requests caused by invalid input, missing credits, or upstream unavailability before model completion do not deduct credits.

## Endpoints

### POST /v1/scrape (1 credit)

Deterministic Layer 1 extraction (0 LLM tokens). Returns metadata, chapters, outgoing description links, deduplicated timestamped transcript segments, storyboard sheets, and Markdown.

Request body:

```json
{
  "url": "https://www.youtube.com/watch?v=1E3tv_3D95g",
  "formats": ["markdown", "segments", "storyboard"],
  "lang": "en"
}
```

- `url` (required): Public YouTube (including Shorts), TikTok, Instagram Reel, or X video URL.
- `formats` (optional): Non-empty unique subset of `["markdown", "segments", "storyboard"]`. Defaults to all three.
- `lang` (optional): BCP 47 language tag (max 16 chars), default `"en"`.

### POST /v1/frames (1 credit)

Targeted Layer 2A visual inspection. Extracts 1 to 20 JPEG frames at exact `timestamps_sec`.

Request body:

```json
{
  "url": "https://www.youtube.com/watch?v=1E3tv_3D95g",
  "timestamps_sec": [150, 365],
  "max_width": 1280
}
```

- `url` (required): Supported public video URL.
- `timestamps_sec` (required): 1 to 20 non-negative numbers in seconds.
- `max_width` (optional): Integer from 320 to 1920, default 1280.

### POST /v1/search (1 credit)

Layer 2B video discovery on YouTube with optional full Layer 1 scrape enrichment.

Request body:

```json
{
  "query": "MiniMax Chinese AI Lab Scottish Mortgage",
  "platform": "youtube",
  "limit": 5,
  "scrape": false,
  "lang": "en"
}
```

- `query` (required): Non-empty search string (max 200 chars).
- `platform` (optional): `"youtube"` (default). `"tiktok"` returns `UNSUPPORTED_PLATFORM`.
- `limit` (optional): Integer 1 to 20, default 5.
- `scrape` (optional): Boolean, default `false`. When `true`, charges +1 credit per successfully scraped result.

### POST /v1/agent (3 / 5 / 10 credits)

Layer 3 bounded progressive-disclosure video agent. Scrapes context first, inspects storyboard sheets and sharp frames as needed, and returns grounded answers with `[MM:SS]` citations and optional structured JSON.

Request body:

```json
{
  "prompt": "What does Liquid Glass change in iOS 26, and what concerns does the reviewer raise?",
  "urls": ["https://www.youtube.com/watch?v=1E3tv_3D95g"],
  "effort": "low",
  "schema": {
    "type": "object",
    "properties": {
      "highlights": { "type": "array", "items": { "type": "string" } }
    }
  }
}
```

- `prompt` (required): Non-empty string, max 4000 chars.
- `urls` (required): 1 to 10 supported public video URLs.
- `effort` (optional): `"low"` (3 credits, default), `"medium"` (5 credits), or `"high"` (10 credits).
- `schema` (optional): JSON object up to 8192 serialized bytes.

### GET /v1/account (0 credits)

Check authenticated user ID, remaining credits, and current per-endpoint credit costs.

### POST /mcp and GET /mcp

Remote Streamable HTTP JSON-RPC 2.0 MCP server (also available at `https://vidcrawl.com/v1/mcp`). Exposes `vidcrawl_scrape`, `vidcrawl_frames`, `vidcrawl_search`, `vidcrawl_agent`, and `vidcrawl_account`.

### GET /healthz (0 credits, unauthenticated)

Service liveness check returning `{ "ok": true, "service": "vidcrawl-api", "version": "0.1.0" }`.

## Error Codes

All errors follow `{ "ok": false, "error": { "code": "...", "message": "...", "request_id": "..." } }`:

- `UNAUTHORIZED`
- `INSUFFICIENT_CREDITS`
- `INVALID_JSON`
- `PAYLOAD_TOO_LARGE`
- `NOT_FOUND`
- `YOUTUBE_BOT_CHALLENGED`
- `VIDEO_UNAVAILABLE`
- `NO_CAPTIONS_AVAILABLE`
- `INVALID_URL`
- `UNSUPPORTED_PLATFORM`
- `UPSTREAM_ERROR`
- `UPSTREAM_TIMEOUT`
- `MEDIA_UNAVAILABLE`
- `VALIDATION_ERROR`
