Keyword → Blog API
DocsLog inSign up

Getting started

Quickstart

This walks through your first successful request — synchronous generation first, then the asynchronous job + webhook pattern most pipelines use in production.

1. Get an API key

  1. Sign in to your dashboard and open Settings → API keys.
  2. Click “Create key”, choose a scope (generate, jobs, usage), and name it.
  3. Copy the key immediately — it’s shown only once.
.env
KEYWORD_TO_BLOG_API_KEY="ktb_live_xxxxxxxxxxxxxxxxxxxxxxxx"

2. Synchronous generation

Best for interactive use or low-volume calls where you can wait a few seconds for the full post inline.

shell
curl -X POST ${NEXT_PUBLIC_API_BASE_URL}/v1/generate \
  -H "Authorization: Bearer $KEYWORD_TO_BLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keywords": [
    "ai content marketing",
    "small business seo"
  ],
  "topic": "How small businesses can use AI content marketing without losing their voice",
  "language": "en",
  "region": "US",
  "tone": "friendly",
  "targetAudience": "small business owners with no in-house marketing team",
  "brandVoice": "warm, practical, no jargon",
  "industry": "marketing services",
  "targetUrl": "https://example.com/blog/ai-content-marketing",
  "constraints": {
    "maxWords": 900,
    "minWords": 600,
    "maxSections": 5,
    "includeFAQs": true,
    "includeInternalLinksPlaceholders": true,
    "keywordUsageStrategy": "natural"
  },
  "format": {
    "responseTypes": [
      "json",
      "markdown"
    ]
  },
  "clientProvidedRequestId": "req_local_0192"
}'

Example response:

200 OK
{
  "requestId": "req_9f3a1c2e4b",
  "post": {
    "title": "AI Content Marketing for Small Businesses: A Practical Starting Point",
    "slugSuggestion": "ai-content-marketing-small-business",
    "meta": {
      "description": "A practical guide to using AI content marketing as a small business, without losing the voice your customers already trust.",
      "primaryKeyword": "ai content marketing"
    },
    "outline": {
      "h1": "AI Content Marketing for Small Businesses: A Practical Starting Point",
      "h2": [
        "Why small businesses are turning to AI content marketing",
        "Where AI helps most, and where it doesn't",
        "Keeping your brand voice consistent",
        "A simple weekly workflow",
        "Frequently asked questions"
      ]
    },
    "sections": [
      {
        "type": "introduction",
        "contentMarkdown": "Most small business owners don't have a marketing department. AI content marketing tools promise to fill that gap, but the real question isn't whether AI can write — it's whether it can write like *you*."
      },
      {
        "type": "body",
        "heading": "Why small businesses are turning to AI content marketing",
        "contentMarkdown": "Small business SEO used to mean choosing between hiring a writer or falling behind. AI content marketing changes that math by making a consistent publishing schedule achievable without a full-time hire."
      },
      {
        "type": "body",
        "heading": "Where AI helps most, and where it doesn't",
        "contentMarkdown": "AI is strongest at first drafts, outlines, and repetitive formats like FAQs. It's weakest at judgment calls that depend on knowing your actual customers — so keep a human review step for anything customer-facing."
      },
      {
        "type": "callout",
        "contentMarkdown": "A five-minute voice check before publishing catches most AI-sounding phrasing.",
        "callout": {
          "label": "Quick tip",
          "text": "Read the draft aloud. If it doesn't sound like something you'd actually say to a customer, rewrite that line."
        }
      },
      {
        "type": "body",
        "heading": "Keeping your brand voice consistent",
        "contentMarkdown": "Give the tool a short brand voice brief once, then reuse it: three adjectives, one thing you never say, and one real customer question you hear often."
      },
      {
        "type": "body",
        "heading": "A simple weekly workflow",
        "contentMarkdown": "Draft on Monday, review and edit Tuesday, publish Wednesday. Keeping a fixed cadence matters more than any individual post."
      },
      {
        "type": "faq",
        "heading": "Frequently asked questions",
        "contentMarkdown": ""
      },
      {
        "type": "conclusion",
        "contentMarkdown": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass."
      }
    ],
    "faqs": [
      {
        "question": "Will AI-written content hurt my SEO?",
        "answer": "Search engines rank content on quality and usefulness, not on how it was drafted. Editing for accuracy and voice before publishing is what matters."
      },
      {
        "question": "How much editing does an AI draft usually need?",
        "answer": "Expect to adjust specific claims, add real examples from your business, and tighten anything that reads generic."
      }
    ],
    "conclusion": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass.",
    "coverageNotes": {
      "keywordCoverage": [
        {
          "keyword": "ai content marketing",
          "covered": true,
          "evidence": "Appears in title, H1, and introduction."
        },
        {
          "keyword": "small business seo",
          "covered": true,
          "evidence": "Appears in the second H2 section."
        }
      ]
    }
  },
  "rendered": {
    "markdown": "# AI Content Marketing for Small Businesses: A Practical Starting Point\n\nMost small business owners don't have a marketing department..."
  },
  "debug": {
    "generationModel": "claude-haiku-4-5-20251001"
  },
  "quality": {
    "status": "pass",
    "score": 91,
    "revisionCount": 0,
    "qualityVersion": "1.0.0"
  }
}

3. Asynchronous generation + webhook

Best for batch pipelines: create a job, then either poll it or let your webhook endpoint receive the result.

shell
curl -X POST ${NEXT_PUBLIC_API_BASE_URL}/v1/jobs \
  -H "Authorization: Bearer $KEYWORD_TO_BLOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "generateRequest": {
    "keywords": [
      "ai content marketing",
      "small business seo"
    ],
    "topic": "How small businesses can use AI content marketing without losing their voice",
    "language": "en",
    "region": "US",
    "tone": "friendly",
    "targetAudience": "small business owners with no in-house marketing team",
    "brandVoice": "warm, practical, no jargon",
    "industry": "marketing services",
    "targetUrl": "https://example.com/blog/ai-content-marketing",
    "constraints": {
      "maxWords": 900,
      "minWords": 600,
      "maxSections": 5,
      "includeFAQs": true,
      "includeInternalLinksPlaceholders": true,
      "keywordUsageStrategy": "natural"
    },
    "format": {
      "responseTypes": [
        "json",
        "markdown"
      ]
    },
    "clientProvidedRequestId": "req_local_0192"
  },
  "webhook": {
    "url": "https://example.com/webhooks/keyword-to-blog",
    "events": [
      "job.succeeded",
      "job.failed"
    ]
  },
  "format": {
    "responseTypes": [
      "json",
      "markdown"
    ]
  },
  "idempotencyKey": "job_create_local_0192"
}'

Then poll for the result:

shell
curl ${NEXT_PUBLIC_API_BASE_URL}/v1/jobs/job_5f2a9d3e1b \
  -H "Authorization: Bearer $KEYWORD_TO_BLOG_API_KEY"

Or receive it automatically at the webhook URL you configured:

POST your-webhook-url
{
  "event": "job.succeeded",
  "jobId": "job_5f2a9d3e1b",
  "requestId": "req_9f3a1c2e4b",
  "post": {
    "title": "AI Content Marketing for Small Businesses: A Practical Starting Point",
    "slugSuggestion": "ai-content-marketing-small-business",
    "meta": {
      "description": "A practical guide to using AI content marketing as a small business, without losing the voice your customers already trust.",
      "primaryKeyword": "ai content marketing"
    },
    "outline": {
      "h1": "AI Content Marketing for Small Businesses: A Practical Starting Point",
      "h2": [
        "Why small businesses are turning to AI content marketing",
        "Where AI helps most, and where it doesn't",
        "Keeping your brand voice consistent",
        "A simple weekly workflow",
        "Frequently asked questions"
      ]
    },
    "sections": [
      {
        "type": "introduction",
        "contentMarkdown": "Most small business owners don't have a marketing department. AI content marketing tools promise to fill that gap, but the real question isn't whether AI can write — it's whether it can write like *you*."
      },
      {
        "type": "body",
        "heading": "Why small businesses are turning to AI content marketing",
        "contentMarkdown": "Small business SEO used to mean choosing between hiring a writer or falling behind. AI content marketing changes that math by making a consistent publishing schedule achievable without a full-time hire."
      },
      {
        "type": "body",
        "heading": "Where AI helps most, and where it doesn't",
        "contentMarkdown": "AI is strongest at first drafts, outlines, and repetitive formats like FAQs. It's weakest at judgment calls that depend on knowing your actual customers — so keep a human review step for anything customer-facing."
      },
      {
        "type": "callout",
        "contentMarkdown": "A five-minute voice check before publishing catches most AI-sounding phrasing.",
        "callout": {
          "label": "Quick tip",
          "text": "Read the draft aloud. If it doesn't sound like something you'd actually say to a customer, rewrite that line."
        }
      },
      {
        "type": "body",
        "heading": "Keeping your brand voice consistent",
        "contentMarkdown": "Give the tool a short brand voice brief once, then reuse it: three adjectives, one thing you never say, and one real customer question you hear often."
      },
      {
        "type": "body",
        "heading": "A simple weekly workflow",
        "contentMarkdown": "Draft on Monday, review and edit Tuesday, publish Wednesday. Keeping a fixed cadence matters more than any individual post."
      },
      {
        "type": "faq",
        "heading": "Frequently asked questions",
        "contentMarkdown": ""
      },
      {
        "type": "conclusion",
        "contentMarkdown": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass."
      }
    ],
    "faqs": [
      {
        "question": "Will AI-written content hurt my SEO?",
        "answer": "Search engines rank content on quality and usefulness, not on how it was drafted. Editing for accuracy and voice before publishing is what matters."
      },
      {
        "question": "How much editing does an AI draft usually need?",
        "answer": "Expect to adjust specific claims, add real examples from your business, and tighten anything that reads generic."
      }
    ],
    "conclusion": "AI content marketing works best as a drafting partner, not a replacement for judgment. Start with one post a week and keep your own voice in the final pass.",
    "coverageNotes": {
      "keywordCoverage": [
        {
          "keyword": "ai content marketing",
          "covered": true,
          "evidence": "Appears in title, H1, and introduction."
        },
        {
          "keyword": "small business seo",
          "covered": true,
          "evidence": "Appears in the second H2 section."
        }
      ]
    }
  },
  "rendered": {
    "markdown": "# AI Content Marketing for Small Businesses: A Practical Starting Point\n\nMost small business owners don't have a marketing department..."
  },
  "quality": {
    "status": "pass",
    "score": 91,
    "revisionCount": 0,
    "qualityVersion": "1.0.0"
  }
}

Base URL

Every example on this site uses NEXT_PUBLIC_API_BASE_URL as the base — replace it with your actual deployment host.