Guides
Examples
There is no official SDK package for the Keyword-to-Blog API today. Every example below is plain fetch/requests/curl against the real endpoints documented in the API reference, using the base URL https://lexigen.app/api/v1.
Agency / content-team batch workflow
Submitting several briefs as async jobs (POST /v1/jobs) instead of holding several synchronous connections open, with a per-brief idempotency key so a re-run after a partial failure never creates (or counts) the same brief twice.
// Content-team batch workflow: submit several posts as async jobs so you
// never hold N connections open, then let webhooks tell you when each is done.
// There is no official SDK: this is plain fetch() against the real API.
// KEYWORD_TO_BLOG_API_KEY is your own environment variable holding your key.
const API_KEY = process.env.KEYWORD_TO_BLOG_API_KEY;
const BASE_URL = "https://lexigen.app/api/v1";
const briefs = [
{ keywords: ["ai content marketing"], topic: "AI content marketing for agencies" },
{ keywords: ["seo for saas"], topic: "SEO fundamentals for SaaS teams" },
{ keywords: ["content calendar template"], topic: "Building a quarterly content calendar" },
];
async function submitBatch(briefs) {
const jobs = [];
for (const brief of briefs) {
const res = await fetch(`${BASE_URL}/jobs`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
// One key per brief, derived deterministically, so re-running this
// script after a partial failure never repeats work already done.
"Idempotency-Key": `batch-${brief.keywords[0]}`,
},
body: JSON.stringify({
generateRequest: {
keywords: brief.keywords,
topic: brief.topic,
language: "en",
tone: "professional",
constraints: { includeFAQs: true },
format: { responseTypes: ["json", "markdown"] },
},
webhook: {
url: "https://your-app.example.com/webhooks/lexigen",
events: ["job.succeeded", "job.failed"],
},
format: { responseTypes: ["json", "markdown"] },
}),
});
if (!res.ok) {
const error = await res.json();
console.error(`Failed to queue "${brief.topic}":`, error.error.code, error.error.message);
continue;
}
const job = await res.json();
// Store job.webhookSigningSecret with job.jobId now: it is returned only
// once, and you need it to verify that job's webhook delivery.
jobs.push(job);
console.log(`Queued ${job.jobId} for "${brief.topic}" (status: ${job.status})`);
}
return jobs;
}
await submitBatch(briefs);
// Each job's result now arrives at your webhook URL independently. See the
// "Developer pipeline" example below for verifying and handling that delivery.Developer pipeline: queue → API → webhook
Your own worker creates a job, then a webhook receiver verifies the signature (see webhooks) before trusting the payload, including rejecting a stale or replayed delivery.
// Developer pipeline: your own queue enqueues work, calls this API
// asynchronously, and reacts to the signed webhook when a job finishes.
// Node.js, plain fetch()/crypto, no framework assumed.
import { createHmac, timingSafeEqual } from "node:crypto";
const API_KEY = process.env.KEYWORD_TO_BLOG_API_KEY;
const BASE_URL = "https://lexigen.app/api/v1";
// 1. Your own worker picks up a task and calls this API.
async function createGenerationJob(task) {
const res = await fetch(`${BASE_URL}/jobs`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": task.id, // reuse YOUR task id as the idempotency key
},
body: JSON.stringify({
generateRequest: task.generateRequest,
webhook: { url: task.webhookUrl, events: ["job.succeeded", "job.failed"] },
format: { responseTypes: ["json"] },
}),
});
if (res.status === 429) {
const { error } = await res.json();
if (error.code === "QUOTA_EXCEEDED") {
// Monthly allowance used up: retrying won't help before error.details.periodEnd.
throw new Error(`${error.code}: quota resets at ${error.details.periodEnd}`);
}
// RATE_LIMITED carries Retry-After (seconds): respect it instead of retrying immediately.
const retryAfterSeconds = Number(res.headers.get("Retry-After") ?? "5");
throw new Error(`${error.code}: retry after ${retryAfterSeconds}s`);
}
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message}`);
}
// JobV1. Usually "queued", but always read status: it can already be final.
// Save job.webhookSigningSecret for step 3; it is returned only here.
return res.json();
}
// 2. Your webhook receiver verifies the signature before trusting the payload.
function verifyWebhookSignature(rawBody, signatureHeader, webhookSecret) {
const match = /^t=(\d+),v1=([a-f0-9]+)$/i.exec((signatureHeader ?? "").trim());
if (!match) return false;
const [, timestamp, provided] = match;
const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (ageSeconds > 5 * 60) return false; // reject replayed/stale deliveries
const expected = createHmac("sha256", webhookSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const expectedBuf = Buffer.from(expected, "hex");
const providedBuf = Buffer.from(provided, "hex");
return expectedBuf.length === providedBuf.length && timingSafeEqual(expectedBuf, providedBuf);
}
// 3. Example receiver for any fetch-style server (e.g. a Next.js route handler).
// webhookSecretForThisJob is the webhookSigningSecret you stored for this job.
// Reply within 10 seconds; do slow work afterwards.
async function handleWebhook(req, webhookSecretForThisJob) {
const rawBody = await req.text();
const signature = req.headers.get("x-ktb-signature");
if (!verifyWebhookSignature(rawBody, signature, webhookSecretForThisJob)) {
return new Response("invalid signature", { status: 401 });
}
const payload = JSON.parse(rawBody); // WebhookSucceededPayloadV1 | WebhookFailedPayloadV1
if (payload.event === "job.succeeded") {
// A succeeded job can still report quality.status "fail": decide whether to publish.
await saveGeneratedPost(payload.jobId, payload.post, payload.rendered, payload.quality);
} else {
// payload.event === "job.failed": payload.error.code is a normal ErrorCode
await markTaskFailed(payload.jobId, payload.error);
}
return new Response("ok", { status: 200 });
}Single request — curl / JavaScript / Python
The same synchronous call in each of the three most common client contexts. The key comes from your own environment variable (KEYWORD_TO_BLOG_API_KEY here, but any name works), never a literal in code. Each example allows a generous timeout, because generation can take a minute or more.
curl -X POST "https://lexigen.app/api/v1/generate" \
-H "Authorization: Bearer $KEYWORD_TO_BLOG_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"keywords": ["ai content marketing"],
"language": "en",
"tone": "professional",
"constraints": {},
"format": { "responseTypes": ["json", "markdown"] }
}'const API_KEY = process.env.KEYWORD_TO_BLOG_API_KEY;
const BASE_URL = "https://lexigen.app/api/v1";
const res = await fetch(`${BASE_URL}/generate`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
keywords: ["ai content marketing"],
language: "en",
tone: "professional",
constraints: {},
format: { responseTypes: ["json", "markdown"] },
}),
signal: AbortSignal.timeout(300_000), // generation can take a minute or more
});
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message}`);
}
const { post, rendered, quality } = await res.json();
console.log(post.title, quality.status, rendered.markdown);import os
import uuid
import requests
API_KEY = os.environ["KEYWORD_TO_BLOG_API_KEY"]
BASE_URL = "https://lexigen.app/api/v1"
response = requests.post(
f"{BASE_URL}/generate",
headers={
"Authorization": f"Bearer {API_KEY}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"keywords": ["ai content marketing"],
"language": "en",
"tone": "professional",
"constraints": {},
"format": {"responseTypes": ["json", "markdown"]},
},
timeout=300, # generation can take a minute or more
)
if not response.ok:
error = response.json()["error"]
raise RuntimeError(f"{error['code']}: {error['message']}")
body = response.json()
print(body["post"]["title"], body["quality"]["status"])
print(body["rendered"]["markdown"])