API reference

POST /v1/jobs

Creates an asynchronous generation job. Use this when you’d rather not hold a connection open, or when you want a webhook delivered on completion.

POST/v1/jobs

Headers

AuthorizationBearer <API_KEY>required

Required fields

generateRequest — the same body shape as POST /v1/generate.
format.responseTypes — which representations (json/markdown/html) the finished job’s rendered field and webhook payload will include.

Optional fields

webhook.url / webhook.events — omit to poll GET /v1/jobs/{jobId} instead. When provided, both are required together.
idempotencyKey — replaying the same key with the same body returns the original job instead of creating (and billing) a second one; reusing it with a different body is rejected with VALIDATION_ERROR.

curl example

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"
}'

Example response — 202 Accepted

json

{
  "jobId": "job_5f2a9d3e1b",
  "status": "queued",
  "createdAt": "2026-09-10T14:02:11.000Z",
  "updatedAt": "2026-09-10T14:02:11.000Z",
  "requestId": "req_9f3a1c2e4b",
  "inputSummary": {
    "keywords": [
      "ai content marketing",
      "small business seo"
    ],
    "language": "en",
    "maxWords": 900
  },
  "webhookSigningSecret": "whsec_5f2a9d3e1b4c7a8f0d6e2b1c3a9f8e7d"
}