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.
/api/v1/jobsHeaders
- 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. Itsformat.responseTypesdecides which representations (markdown,html) appear in the finished job’srenderedfield and webhook payload.format.responseTypes: required by validation (at least one ofjson/markdown/html). Send the same value asgenerateRequest.format.
Optional fields
webhook.url/webhook.events: omit the wholewebhookobject to poll GET /v1/jobs/{jobId} instead. When present, both are required, andeventslists at least one ofjob.succeededandjob.failed. URLs that resolve to private or local network addresses are never called.idempotencyKey(or theIdempotency-Keyheader): 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 returnsVALIDATION_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
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
{
"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"
}