API Reference

Introduction

Base URL

https://tubepull.com/api/v1

Authentication

Authenticate every request with a Bearer token in the Authorization header. Generate a key from your API keys dashboard.

Authorization: Bearer tp_live_your_api_key_here

Responses

All responses are Content-Type: application/json and use a consistent envelope.

On success:

{ "success": true, "data": { ... } }

On error, the error field is an object with a machine-readable code and a human-readable message:

{ "success": false, "error": { "code": "error_code", "message": "Human-readable message" } }

Rate limit headers

Every response includes your current limit state:

• X-RateLimit-Limit — your plan's hourly request cap
• X-RateLimit-Remaining — requests left in the current hourly window
• X-RateLimit-Reset — Unix timestamp when the window resets
• X-Credits-Remaining — download credits left this billing period

GET /video/metadata

Returns metadata for a YouTube video without consuming a download credit.

Parameters

Example request

curl -X GET "https://tubepull.com/api/v1/video/metadata?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer tp_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "platform": "youtube",
    "video_id": "dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up",
    "duration": 213,
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

duration is in seconds. A successful lookup consumes one metadata credit.

Error codes

POST /video/download

Queues a video for download. Returns a request_token to poll via /video/status.

Request body

Example request

curl -X POST "https://tubepull.com/api/v1/video/download" \
  -H "Authorization: Bearer tp_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "video",
    "quality": "1080"
  }'

Example response

Returns 202 Accepted with a request_token. Poll /video/status with this token to retrieve the download URL.

{
  "success": true,
  "data": {
    "request_token": "9f8c1a2b3d4e5f60718293a4b5c6d7e8",
    "status": "queued",
    "platform": "youtube",
    "video_id": "dQw4w9WgXcQ",
    "format": "video",
    "quality": "1080",
    "overage": false
  }
}

A successful queue consumes one download credit. On paid tiers, overage is true when the request is billed past your included allowance; on the free tier the allowance is a hard cap (402).

Error codes

GET /video/status

Poll job status. Returns a secure, signed download URL when complete. Download links expire 1 hour after they are issued.

Parameters

Status values

queued · claimed · running · done · failed

Example request

curl -X GET "https://tubepull.com/api/v1/video/status?token=9f8c1a2b3d4e5f60718293a4b5c6d7e8" \
  -H "Authorization: Bearer tp_live_your_api_key_here"

Example response (done)

{
  "success": true,
  "data": {
    "status": "done",
    "request_token": "9f8c1a2b3d4e5f60718293a4b5c6d7e8",
    "video_id": "dQw4w9WgXcQ",
    "download_url": "https://dl.tubepull.com/d/...&sig=...",
    "expires_in": 3600,
    "file_size_bytes": 41884320,
    "file_mime": "video/mp4"
  }
}

Example response (failed)

{
  "success": true,
  "data": {
    "status": "failed",
    "request_token": "9f8c1a2b3d4e5f60718293a4b5c6d7e8",
    "video_id": "dQw4w9WgXcQ",
    "error": "unavailable",
    "message": "The download failed."
  }
}

Note: download_url expires expires_in seconds (1 hour) after it is issued. Re-poll /video/status to mint a fresh link. A request for another user's token returns 404 not_found.

GET /credits

Returns your current credit balance and billing period. Takes no parameters.

Example request

curl -X GET "https://tubepull.com/api/v1/credits" \
  -H "Authorization: Bearer tp_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "plan": "studio500",
    "downloads": { "limit": 500, "used": 1, "remaining": 499 },
    "metadata": { "limit": 10000, "used": 13, "remaining": 9987 },
    "overage": { "downloads": 0, "cents": 0 },
    "period_start": "2026-06-01 00:00:00.000",
    "period_end": "2026-07-01 00:00:00.000"
  }
}

POST /auth/key

Programmatically generate a new API key. Requires an existing valid API key (or a session cookie for web-authenticated users). The raw key is returned once and never stored — save it immediately.

Request body

Example request

curl -X POST "https://tubepull.com/api/v1/auth/key" \
  -H "Authorization: Bearer tp_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "label": "my-app" }'

Example response

Returns 201 Created. The raw key is shown once — store it immediately.

{
  "success": true,
  "data": {
    "key": "tp_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "key_prefix": "tp_live_a1b2",
    "label": "my-app",
    "created_at": "2026-06-30 14:04:05.123"
  }
}

Error reference

Rate limits

Requests are limited per API key on a rolling hourly window. Exceeding the limit returns 429 RATE_LIMITED.