YouTube to Blog API

Authentication

Create an API key in the dashboard. Keys start with ytb_ and are shown once at creation - store them somewhere safe. You can have up to 5 active keys and revoke any of them at any time.

Send the key with every request, either as a bearer token or in the x-api-key header.

curl https://www.youtube2blog.com/api/v1/blogs \
  -H "Authorization: Bearer ytb_your_api_key"

Create a blog post

POST /api/v1/blogs

Converts a YouTube video into a Markdown blog post. The request is synchronous: the connection stays open while the AI writes the post, which typically takes 20–60 seconds and can take a few minutes for long videos. Set your HTTP client timeout accordingly.

curl -X POST https://www.youtube2blog.com/api/v1/blogs \
  -H "Authorization: Bearer ytb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

A new post returns 201 with status: "created". If a post for that video already exists, the API returns it with 200 and status: "existing" without using any of your quota.

{
  "status": "created",
  "blog": {
    "slug": "dQw4w9WgXcQ",
    "title": "Never Gonna Give You Up: A Deep Dive",
    "author": "Rick Astley",
    "sourceType": "youtube",
    "createdAt": "2026-08-21T09:30:00.000Z",
    "content": "# Never Gonna Give You Up: A Deep Dive\n\n...",
    "url": "https://www.youtube2blog.com/blog/dQw4w9WgXcQ"
  }
}

The content field contains the complete post as Markdown, ready to publish anywhere.

Writing style

Two optional fields control the voice of the generated post. When omitted, the account's saved writing style from settings is used.

• style - one of personal, professional, technical, tutorial, punchy.
• styleInstructions - free-text voice notes (up to 500 characters) applied on top of the selected style.

curl -X POST https://www.youtube2blog.com/api/v1/blogs \
  -H "Authorization: Bearer ytb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "style": "technical",
    "styleInstructions": "Short sentences. Address the reader as you. Never use emoji."
  }'

List blog posts

GET /api/v1/blogs

Returns your blog posts, newest first, without the Markdown body. Use limit (1–100, default 20) and offset (default 0) to paginate.

curl "https://www.youtube2blog.com/api/v1/blogs?limit=10&offset=0" \
  -H "Authorization: Bearer ytb_your_api_key"

{
  "blogs": [
    {
      "slug": "dQw4w9WgXcQ",
      "title": "Never Gonna Give You Up: A Deep Dive",
      "author": "Rick Astley",
      "sourceType": "youtube",
      "createdAt": "2026-08-21T09:30:00.000Z",
      "url": "https://www.youtube2blog.com/blog/dQw4w9WgXcQ"
    }
  ],
  "pagination": { "limit": 10, "offset": 0 }
}

Get a blog post

GET /api/v1/blogs/{slug}

Fetches a single post, including the full Markdown content. The slug is returned by the create and list endpoints.

curl https://www.youtube2blog.com/api/v1/blogs/dQw4w9WgXcQ \
  -H "Authorization: Bearer ytb_your_api_key"

Errors

Every error response has the same shape: an error object with a stable code for your code to branch on and a human-readable message.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "You have used all of this month's blog generations. Upgrade to Pro for a higher limit."
  }
}

MISSING_API_KEY401

No API key was sent. Use the Authorization or x-api-key header.

INVALID_API_KEY401

The key does not exist, is disabled, or has expired.

API_REQUIRES_PRO402

The account that owns this key is no longer on the Pro plan.

QUOTA_EXCEEDED402

The monthly generation quota has been used up.

INVALID_REQUEST400

The request body is not valid JSON or is missing youtubeUrl.

STYLE_REQUIRES_PRO402

styleInstructions was sent but the account is no longer on the Pro plan.

INVALID_YOUTUBE_URL400

The URL is not a valid YouTube video URL.

BLOG_NOT_FOUND404

No blog post exists with the requested slug.

VIDEO_NOT_ACCESSIBLE422

The video is private, deleted, or otherwise unavailable.

RATE_LIMITED429

The key exceeded 10 requests per minute.

AI_GENERATION_FAILED502

Generation failed upstream. Retry the request shortly.

Rate limits & quotas

• Each API key allows 10 requests per minute. Exceeding it returns 429 RATE_LIMITED; wait for the window to reset and retry.
• Blog generation counts against your account's monthly generation quota - the same quota the web app uses. When it runs out, POST /api/v1/blogs returns 402 QUOTA_EXCEEDED.
• Listing and reading posts never consume quota, and neither does creating a post for a video that has already been converted.
• You can hold up to 5 API keys per account.