Developers
Recipe: publish blog posts to your site
Have your website fetch and publish new Lumina blog posts automatically.
Video walkthrough
How to use automated blog posts
6:54 · recorded October 2026Write a post on demand or schedule automatic runs, then hand the API and MCP configuration to your coding agent so new posts land on your website.
What looks different now
- Blogs is out of beta. Access tokens are created under Developers, on the API tab.
Lumina writes blog posts for your agency (or a client) on demand or on a schedule. This recipe gets them onto your own website automatically, so a scheduled post goes live without anyone copying and pasting.
Lumina does not host your blog. Your website pulls the posts from the API, or receives them by webhook, and publishes them itself.
Before you start
- Fill in the brand brief on the Blogs page: Niche or category, Primary audience, and Offers are required. Without them, generation fails with
409 profile_incomplete. - Credits. Each generated post costs 1 Lumina AI credit. Pro includes 50 a month, shared with Lumina Assistant and Landers. A post that fails costs nothing.
- Optional: turn on the schedule. On the Blogs page, under Schedule, switch on Automatic generation, choose a Cadence (every week, every two weeks, or monthly), a Day, a Local time and Timezone, and a Recurring topic direction. Press Save automation. A run is skipped cleanly when the month's credits are gone.
See Automated blog posts for the dashboard side.
Pick an approach
| Pull (polling) | Push (webhook) | |
|---|---|---|
| How | Your site asks the API for ready posts every so often | Lumina calls your URL the moment a post is ready |
| Works with | Any site with a server or build step | A site that can receive a POST request |
| Setup | A token with Read and export Blogs | A webhook URL plus its signing secret |
| Best for | Static sites, Next.js with revalidation | Instant publishing |
You can use both: the webhook for speed, polling as a safety net.
Pull: fetch posts from the API
1. Make a read-only token
As the owner, create a token with only Read and export Blogs (blogs:read) at app.luminasales.io/developers/api. Store it as an environment variable on your server, for example LUMINA_BLOG_TOKEN. See Access tokens.
2. List ready posts
curl "https://luminasales.io/api/v1/blogs?status=ready&limit=100" \
-H "Authorization: Bearer $LUMINA_BLOG_TOKEN"Query parameters:
| Parameter | Values |
|---|---|
status | generating, ready, draft, failed, archived |
limit | 1–100, default 25 |
offset | For paging |
search | Matches title and topic |
The response wraps the posts like this:
{
"data": {
"posts": [
{
"id": "…",
"title": "Why med spas miss calls after 6pm",
"slug": "why-med-spas-miss-calls-after-6pm",
"status": "ready",
"excerpt": "…",
"markdown": "…",
"seo_title": "…",
"seo_description": "…",
"keywords": ["med spa", "missed calls"],
"generated_at": "…",
"updated_at": "…"
}
],
"total": 12,
"limit": 100,
"offset": 0
},
"request_id": "…"
}Posts come newest-edited first. The body is Markdown in markdown. Each post also carries more fields; the REST API reference has the full schema.
3. Render it in Next.js
A server-side example with revalidation every 10 minutes. It uses react-markdown; any Markdown renderer works.
// lib/lumina-blog.ts (server only)
const BASE = "https://luminasales.io/api/v1";
export interface LuminaPost {
id: string;
title: string;
slug: string;
excerpt: string;
markdown: string;
seo_title: string;
seo_description: string;
updated_at: string;
}
export async function getPosts(): Promise<LuminaPost[]> {
const response = await fetch(`${BASE}/blogs?status=ready&limit=100`, {
headers: { Authorization: `Bearer ${process.env.LUMINA_BLOG_TOKEN}` },
next: { revalidate: 600 },
});
if (!response.ok) throw new Error(`Lumina blogs: ${response.status}`);
const body = await response.json();
return body.data.posts as LuminaPost[];
}
export async function getPost(slug: string): Promise<LuminaPost | undefined> {
return (await getPosts()).find((post) => post.slug === slug);
}// app/blog/[slug]/page.tsx
import ReactMarkdown from "react-markdown";
import { notFound } from "next/navigation";
import { getPost } from "@/lib/lumina-blog";
export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
const post = await getPost((await params).slug);
if (!post) notFound();
return (
<article>
<h1>{post.title}</h1>
<ReactMarkdown skipHtml>{post.markdown}</ReactMarkdown>
</article>
);
}
export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
const post = await getPost((await params).slug);
return post ? { title: post.seo_title || post.title, description: post.seo_description } : {};
}With more than 100 posts, page through with offset.
Polling once every few minutes is plenty. The API allows 120 requests a minute, so caching matters more for speed than for limits.
Push: receive a webhook
1. Add your webhook
On the Blogs page, under Schedule, enter your Webhook URL and save. It must be a public https:// address. Lumina then shows Copy the signing secret now. Press Copy secret and store it on your server, for example as LUMINA_WEBHOOK_SECRET. It is shown once. Rotate signing secret makes a new one; Remove webhook turns it off.
The webhook fires as soon as a post is generated, however it was made: the dashboard, the API, MCP, or the schedule. There is no review step in between, so publishing straight from the webhook publishes every post unread.
2. What Lumina sends
POST /your/webhook/path
Content-Type: application/json
User-Agent: Lumina-Sales-Blogs/1.0
X-Lumina-Timestamp: 1762790400
X-Lumina-Signature: v1=5d41402abc4b2a76b9719d911017c592...
{"id":"evt_…","type":"blog.post.ready","created_at":"…","agency_id":"…","data":{"post":{ … }}}data.post has the same fields as a post from the API.
Lumina waits 10 seconds for a 2xx answer, does not follow redirects, and does not retry. If delivery fails, the Blogs page shows the error under Last delivery. Run the pull approach as a backup so a missed webhook never means a missed post.
3. Verify the signature
The signature is a hex HMAC-SHA256 of <timestamp>.<raw body> using your signing secret, prefixed with v1=. Always verify it against the raw body, before parsing JSON, and reject old timestamps so a captured request cannot be replayed.
// app/api/lumina-webhook/route.ts (Next.js route handler, Node runtime)
import { createHmac, timingSafeEqual } from "node:crypto";
const MAX_AGE_SECONDS = 300;
function isValid(rawBody: string, timestamp: string | null, signature: string | null): boolean {
const secret = process.env.LUMINA_WEBHOOK_SECRET;
if (!secret || !timestamp || !signature?.startsWith("v1=")) return false;
const sentAt = Number(timestamp);
if (!Number.isInteger(sentAt)) return false;
if (Math.abs(Date.now() / 1000 - sentAt) > MAX_AGE_SECONDS) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
const received = Buffer.from(signature.slice(3), "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
}
export async function POST(request: Request) {
const rawBody = await request.text();
const ok = isValid(
rawBody,
request.headers.get("x-lumina-timestamp"),
request.headers.get("x-lumina-signature"),
);
if (!ok) return new Response("invalid signature", { status: 401 });
const event = JSON.parse(rawBody);
if (event.type === "blog.post.ready") {
const post = event.data.post;
// Save or publish the post here. Use post.id as the key, so receiving
// the same post twice updates it instead of creating a duplicate.
}
return new Response("ok");
}Answer quickly. If publishing takes more than a few seconds, store the post and finish the work in the background.
Let an AI build it for you
Not a developer? Hand this to Lovable, Base44, Claude Code, Cursor, or whatever builds your site. Create the token first and give it to the tool as a secret, not in the chat.
Add a blog to my website that publishes posts from Lumina Sales automatically.
- Fetch posts on the server only, from GET https://luminasales.io/api/v1/blogs?status=ready&limit=100
with the header "Authorization: Bearer <LUMINA_BLOG_TOKEN>". Read the token from a server-side
environment variable / secret called LUMINA_BLOG_TOKEN. Never expose it in browser code.
- The response is { "data": { "posts": [...], "total", "limit", "offset" } }. Each post has
id, title, slug, excerpt, markdown, seo_title, seo_description, keywords, updated_at.
- Build a /blog index page listing posts (title, excerpt, link) and a /blog/[slug] page that
renders post.markdown as HTML (no raw HTML in the Markdown), with seo_title and
seo_description as the page title and meta description.
- Refresh the list at least every 10 minutes (cache or revalidate), so new posts appear on their own.
- Match the design of the rest of my site.If something goes wrong
401or403 insufficient_scope: the token needs Read and export Blogs. See API and MCP.- No new posts: check the brand brief is complete, that you have credits left, and that the schedule is saved. See Billing and usage.
- Webhook shows an error under Last delivery: make sure the URL is public
https://, answers within 10 seconds, and does not redirect.
Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.
