Lexigen

API reference

POST /v1/jobs

Creates an asynchronous generation job. Use it when you’d rather not hold a connection open for a minute or more, or when you want a webhook on completion.

POST/api/v1/jobs

Headers

  • AuthorizationBearer <API_KEY> (or X-API-Key: <API_KEY>)required
  • Content-Typeapplication/jsonrequired
  • Idempotency-Key<any string>

Scope

Requires the jobs:create scope (on by default for dashboard-created keys). Rate limits and the monthly quota apply exactly as for POST /v1/generate.

Required fields

  • generateRequest: the same body as POST /v1/generate, validated by the same rules. Its format.responseTypes decides which representations (markdown, html) appear in the finished job’s rendered field and webhook payload.
  • format.responseTypes: required by validation (at least one of json/markdown/html). Send the same value as generateRequest.format.

Optional fields

  • webhook.url / webhook.events: omit the whole webhook object to poll GET /v1/jobs/{jobId} instead. When present, both are required, and events lists at least one of job.succeeded and job.failed. URLs that resolve to private or local network addresses are never called.
  • idempotencyKey (or the Idempotency-Key header): repeating the same key with the same body returns the original job instead of creating a second one. If the original request failed, the repeat returns the same error response and status. Reusing it with a different body returns VALIDATION_ERROR.

Response

202 Accepted with a JobV1. The job is normally queued, but it may already be succeeded or failed when it was processed before the response was sent, so always read status. When you configured a webhook, the response includes webhookSigningSecret. It appears only in this response and can’t be retrieved again, so store it to verify deliveries.

Quality and timing

Jobs run the same facts-first, gated pipeline as POST /v1/generate, including reading generateRequest.targetUrl on every job that has one, and up to 2 automatic repair passes. A job whose quality gates still fail succeeds with its article and reports quality.status: "fail" plus quality.qa.failingGates. Each plan can process a fixed number of jobs at the same time (see plans & limits). Further jobs wait their turn. See the content quality pipeline.

curl example

shell
curl -X POST https://lexigen.app/api/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",
    "constraints": {
      "maxSections": 6,
      "includeFAQs": true,
      "keywordUsageStrategy": "natural"
    },
    "format": {
      "responseTypes": [
        "json",
        "markdown"
      ]
    },
    "clientProvidedRequestId": "req_local_0192"
  },
  "webhook": {
    "url": "https://example.com/webhooks/lexigen",
    "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"
  },
  "webhookSigningSecret": "YOUR_WEBHOOK_SIGNING_SECRET"
}