Pasting a raw list of keywords into an AI prompt box produces generic content. If you queue up 50 articles using only a keyword like "best CRM for real estate agents," the generator must guess your target audience, your product's value proposition, and your brand tone. This guesswork results in repetitive drafts that fail to convert readers.
To scale content without losing quality, you must feed structured metadata to your generation engine. A structured JSON payload defines the exact audience, product angle, and editorial constraints for every page in your campaign.
Why structured JSON is the foundation of programmatic SEO
Programmatic SEO requires publishing highly targeted pages that address specific search intents. A basic spreadsheet or a simple text list of keywords strips away the context. Standard AI writers treat every keyword the same way—they produce generic overviews.
By structuring your input as a JSON payload, you pass specific variables for every article. For example, instead of generating a generic article about "data integration," your JSON payload can specify that the ideal customer profile (ICP) is a data engineer. You can direct the product angle to focus on your API's low latency, and use the guidance to forbid the mention of legacy database systems. This structure ensures that every generated draft reads as if a specialized writer wrote it for a specific buyer.
The TopicForge batch API endpoint
If your team uses Postman, curl, or custom Python scripts to manage your marketing stack, you can trigger your programmatic SEO campaigns directly through the TopicForge API.
The standard endpoint for batch generation is POST /v1/jobs. This endpoint accepts a single JSON payload containing an array of topic objects. When you send a request to this endpoint, the system queues the entire batch—it processes each topic through our four-stage pipeline and prepares the drafts for your review.
Using the API allows you to connect your keyword research tools or internal databases directly to your content pipeline. You pull search terms from your SEO tools, format them into the required JSON schema, and push them to TopicForge in one automated call.
Example JSON payload for a 50-topic batch run
Below is a realistic example of a JSON payload that you would send to the POST /v1/jobs endpoint. This snippet contains three sample topics designed for a B2B software company targeting different customer segments.
{
"jobName": "Q3 Growth Campaign",
"topics": [
{
"title": "How to automate inventory tracking for mid-market retail",
"slug": "automate-inventory-tracking-mid-market-retail",
"icp": "Operations managers at retail brands with 50 to 500 employees",
"productAngle": "Highlight how our real-time inventory syncing prevents stockouts without manual audits.",
"topicGuidance": "Focus on the transition from spreadsheets to automated systems. Do not mention enterprise ERP software."
},
{
"title": "Scaling warehouse logistics with barcode scanning APIs",
"slug": "warehouse-logistics-barcode-scanning-api",
"icp": "Technical product managers and logistics developers",
"productAngle": "Emphasize our API's sub-100ms response times and pre-built SDKs for iOS and Android.",
"topicGuidance": "Include code-like logic examples or pseudo-code for API initialization. Avoid overly sales-heavy language."
},
{
"title": "Reducing fulfillment errors in multi-channel e-commerce",
"slug": "reduce-fulfillment-errors-multi-channel-ecommerce",
"icp": "E-commerce directors managing Shopify and Amazon stores",
"productAngle": "Show how our unified dashboard flags shipping discrepancies before orders leave the warehouse.",
"topicGuidance": "Address the pain point of split inventory across multiple warehouses. Keep the tone practical and action-oriented."
}
]
}
Understanding the key fields in your topic schema
To get the best results from your programmatic batch, you need to understand how each field in the JSON schema shapes the final output.
title: This is the working title of the article. It sets the primary focus of the piece and guides the initial outline generation.slug: The URL-friendly version of the title. Defining this in your JSON ensures your CMS integration can publish the article to the exact URL path you planned.icp: The Ideal Customer Profile. This field tells the generation engine exactly who is reading the article. An article written for a technical product manager uses different terminology and depth than one written for a small business owner.productAngle: This field dictates how your product or service is introduced. Instead of generic pitches, you tailor the product mention to solve the specific problem discussed in the article. For example, if the topic is about API speed, your product angle focuses on low latency.topicGuidance: These are specific editorial guardrails for the individual article. You can use this field to list specific terms to include, topics to avoid, or structural preferences—such as including a comparison table or writing a step-by-step tutorial.
Alternative: Using the admin UI for batch uploads
You do not need to be a developer to use structured JSON. While developers can interact directly with the API, marketers can use the TopicForge admin interface.
By navigating to /jobs/new in your web browser, you can paste the exact same JSON payload into a visual input field. This allows growth marketers and SEO managers to design their content clusters in a spreadsheet, convert the rows to JSON using an online converter, and run the batch without writing code.
How the four-stage generation pipeline processes your JSON
Once you submit your JSON payload—either through the API or the admin UI—the system does not run a single prompt to generate your articles. One-shot AI generation often leads to repetitive phrasing and structural errors.
Instead, TopicForge processes each topic in your array through a distinct four-stage pipeline powered by Gemini via Vertex AI:
- Outline: The system creates a detailed structural outline based on your title and topic guidance.
- Draft: The outline is expanded into a full-length draft, ensuring all technical points are thoroughly explained.
- Voice Pass: The draft is edited to match your account-level voice profile—this step removes generic AI filler and applies your brand's tone.
- CTA + SEO Metadata: The system generates a tailored call-to-action based on your
productAngle, creates a meta description, and formats the final output.
This multi-stage process guarantees that the specific instructions you provided in your JSON payload are applied at every step of the writing process. The output includes a markdown body, meta description, FAQ JSON-LD, and CTA copy.
If you are ready to scale your content production without hiring writers or paying monthly agency fees, you can start planning your batch jobs today. TopicForge has planned self-serve pricing of $10 for a single article, $49 for a 10-pack (about $4.90 per article), and $399 for a 100-pack (about $3.99 per article). There are no monthly agency retainers.
FAQs
What is the maximum number of topics I can send in one batch?
While you can technically send larger payloads, we recommend batching your runs in groups of 50 to 100 topics to easily review and manage the generated drafts.
Can I update the voice profile or brand guardrails inside the JSON payload?
No. Global guardrails—like your voice profile, product facts, and banned phrases—are configured at the account level. The JSON payload is used to specify topic-level details like the specific ICP and product angle for each article.
What formats does the API return once the batch job is complete?
The API returns a complete payload for each article. This includes the markdown body, meta description, FAQ JSON-LD, and custom CTA copy based on your product angle.
Do I need a developer to run a programmatic SEO batch?
No. While developers can use the POST /v1/jobs API, marketers can copy and paste the exact same JSON payload into the TopicForge admin UI at /jobs/new to trigger the batch run.