API Reference

Complete endpoint and error-handling reference based on current backend implementation. Includes routing groups, response behavior, and practical client handling rules.

Public API v1

Direct integration endpoints without signature requirements.

Rate Limited

429 includes `Retry-After` and `resetAt` metadata.

Split Proxy / Download

Preview/stream uses `/proxy`, file output uses `/download`.

Base URL

/

Source: NEXT_PUBLIC_API_URL

POST/api/v1/extract

Extract media information from supported URL with optional cookie lane fallback. Public API endpoint for direct integrations.

Cookie Support

For private content, pass cookie in `cookie` field format: `name=value; name2=value2`.

Request

request.json

curl -X POST /api/v1/extract \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "cookie": "optional_cookie_string"
  }'

Response

response.json

{
  "success": true,
  "data": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "mediaType": "video",
    "author": {
      "name": "Rick Astley",
      "handle": "RickAstleyVEVO"
    },
    "content": {
      "id": "dQw4w9WgXcQ",
      "text": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
      "description": "The official video for Never Gonna Give You Up"
    },
    "engagement": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "bookmarks": 0
    },
    "media": [
      {
        "index": 0,
        "type": "video",
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "variants": [
          {
            "quality": "1080p",
            "url": "https://rr1---sn.example.googlevideo.com/videoplayback?...",
            "resolution": "1920x1080",
            "mime": "video/mp4",
            "format": "mp4",
            "size": 52428800,
            "codec": "avc1",
            "hasAudio": false,
            "requiresMerge": true,
            "requiresProxy": false,
            "formatId": "137"
          },
          {
            "quality": "Audio",
            "url": "https://rr1---sn.example.googlevideo.com/videoplayback?...",
            "mime": "audio/mp4",
            "format": "m4a",
            "size": 4194304,
            "codec": "mp4a.40.2",
            "hasAudio": true,
            "requiresMerge": false,
            "requiresProxy": false,
            "formatId": "140"
          }
        ]
      }
    ],
    "authentication": {
      "used": false,
      "source": "none"
    }
  },
  "meta": {
    "requestId": "req_01J...",
    "timestamp": "2026-03-03T10:20:30Z",
    "responseTime": 342,
    "cookieSource": "guest",
    "accessMode": "public",
    "publicContent": true
  }
}

Other Endpoints

Response envelope is stable across all platforms. Field values vary per source, but array/object shape stays consistent. This section helps clients adapt without platform-specific hardcoding.

Collapsed by default. Click to expand full response field map.

Error Categories

VALIDATION

Invalid request shape/body/URL. Fix input, then resend.

NOT_FOUND

Platform/content/route not found in current runtime/public scope.

NETWORK

Gateway/upstream/proxy timeout or transient network failure.

RATE_LIMIT

Too many requests. Respect `Retry-After` + `resetAt`.

AUTH

Cookie/session/login required or request is forbidden.

EXTRACTION_FAILED

Generic extraction runtime failure on server side.

Cookie/Auth Handling

Lane Order

Guest -> Server -> UserProvided

Escalation Rule

Move to next lane only when current lane fails with AUTH.

Success Metadata

`meta.cookieSource` = `guest | server | userProvided`.

Private Access Flag

If auth lane used: `accessMode=private`, `publicContent=false`.

Expand to view canonical error codes, HTTP status mapping, category group, and handling guidance.

Client Handling Checklist

01Branching

Route UX by `error.category` first, refine with `error.code` second.

02Rate Limit

Use `Retry-After` header and `error.metadata.resetAt` countdown together.

03Auth Recovery

Show cookie settings action and retry with user-provided lane.

04Retry Policy

Retry only `NETWORK` and `RATE_LIMIT` with exponential backoff.

05Canonical vs Cause Code

When code is normalized, inspect `error.metadata.causeCode` for upstream root cause.

This page documents public API v1 endpoints. Frontend uses signed `/api/web/*` routes internally.

Example JSON is representative; payload shape follows runtime extract result and may vary per platform.

Bmbtech