Running a programmatic SEO campaign with 50 separate Google Docs or manual ChatGPT prompts slows down your marketing team. Instead, engineering and marketing teams use a single API call with a structured JSON payload to automate the process. You define your topics, brand voice, and product facts in one structured file to generate an entire campaign in a single run.
This guide shows you how to structure a 50-topic batch JSON payload for programmatic SEO. You will learn how to configure global guardrails, format the topic array, and handle the API response.
Why batch JSON structure matters for programmatic SEO
Scaling content to dozens of pages requires strict schema validation. If your JSON structure is malformed, the API parser fails—your batch job stops. If your editorial guardrails are missing, the output quality drifts. One article might sound like a technical manual, while the next sounds like a generic blog post.
A clean, structured JSON payload solves these problems. It ensures that:
- Your API requests succeed—properly nested arrays and objects prevent syntax errors.
- Your brand voice remains consistent—you define your tone, product facts, and banned phrases once at the root level, and the system applies them to all 50 articles.
- You save time on editing—by passing specific topic guidance for each keyword, you get draft outputs that require minimal manual review.
The POST /v1/jobs API payload schema
To generate articles in bulk, you send a POST request to the /v1/jobs endpoint. This endpoint accepts a JSON payload containing your global configuration and an array of individual topics.
TopicForge does not use a simple one-shot prompt. Instead, the TopicForge pipeline processes each topic through four distinct stages:
- Outline generation—the system plans the structure of the article.
- Drafting—the core content is written based on the outline.
- Voice pass—the system refines the text to match your brand voice.
- CTA and SEO metadata generation—the system adds meta descriptions, FAQ JSON-LD, and call-to-action copy.
Gemini via Vertex AI powers this generation. Structuring your JSON payload correctly gives this multi-stage pipeline the exact data it needs for each step.
Breaking down the JSON fields for a 50-topic run
A programmatic SEO payload consists of global fields and topic-specific fields. Here are the key fields you need to define in your schema:
Global guardrails
These fields sit at the root of your JSON payload. They apply to every article in your 50-topic batch unless you override them for a specific topic.
voice_profile—a text description of your brand's tone. For example, "direct, pragmatic, and technical."product_facts—a list of verified facts about your product or service. This prevents the AI from inventing features or pricing tiers.banned_phrases—an array of words and cliches that the generator must avoid.
The topics array
The topics array is the core of your payload. It contains up to 50 objects, with each object representing a single article.
keyword—the primary search term you want to target (example: "how to format a csv for import").title—the specific H1 title for the article.topic_guidance—specific instructions for this single article, such as key points to cover or specific questions to answer.cta_override—a custom call-to-action for this specific topic, allowing you to match the CTA to the user's search intent.
A complete 50-topic batch JSON example
Below is a realistic example of a structured JSON payload for a batch job. This example is truncated for readability. It shows how to define global guardrails and format the first few topics in your 50-item array.
{
"voice_profile": "Write as a pragmatic B2B product marketer. Use short sentences and active voice. Avoid hype.",
"product_facts": [
"TopicForge is a programmatic SEO platform that turns topics into publish-ready articles.",
"The platform uses a four-stage AI pipeline: outline, draft, voice pass, and CTA/metadata generation.",
"Pricing plans include a $49 10-pack and a $399 100-pack."
],
"banned_phrases": [
"in today's digital landscape",
"game-changer",
"revolutionize",
"unlock the power"
],
"topics": [
{
"keyword": "programmatic seo json schema",
"title": "How to design a JSON schema for programmatic SEO",
"topic_guidance": "Explain the difference between global configurations and topic arrays. Use a clear code block as an example."
},
{
"keyword": "b2b content scaling tips",
"title": "How B2B marketing teams scale content without hiring agencies",
"topic_guidance": "Focus on the operational costs of manual writing versus API-driven generation. Mention the TopicForge 100-pack pricing as a cost example."
},
{
"keyword": "automated article metadata",
"title": "Why you should automate your meta descriptions and FAQ schema",
"topic_guidance": "Explain how structured FAQ JSON-LD improves search visibility. Show how automated pipelines generate this metadata alongside the article body."
}
]
}
Best practices for organizing your topic array
Before you write your JSON payload and send it to the API, take these steps to organize your data:
Clean your keyword list
Do not export a raw list of 50 keywords from an SEO tool and paste them directly into your JSON. Remove duplicate search intents. If "how to write a json schema" and "json schema writing guide" both appear in your list, combine them—this avoids self-cannibalization in search results.
Group topics by search intent
If you are generating 50 articles, group them into clusters. For example, you might have 20 "how-to" guides, 20 "integration" pages, and 10 "glossary" definitions. Grouping your topics allows you to apply consistent topic_guidance templates across similar articles in your batch.
Map specific CTAs
A generic "sign up now" CTA does not work for every search query. Use the cta_override field to match the CTA to the reader's stage in the buying journey. For high-intent keywords, direct the reader to your product page. For informational keywords, direct them to a related guide or newsletter signup.
How to execute the API call and handle the output
Once your JSON payload is ready, you can send it to the TopicForge API using a standard HTTP client like curl, Postman, or a Python script.
Here is an example of how to execute the call using curl:
curl -X POST https://api.topicforge.net/v1/jobs \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d @batch_topics.json
When the batch job completes, the API returns a structured JSON response. Instead of raw, unformatted text, the response contains a dedicated object for each of your 50 topics.
The output for each topic includes:
- Markdown body—the complete article text, formatted with sentence-case H2 and H3 headings.
- Meta description—a search-optimized description under 160 characters.
- FAQ JSON-LD—structured schema markup ready to paste into your website's HTML header.
- CTA copy—a tailored call-to-action based on your global settings or topic-level overrides.
You can parse this JSON response with a simple script to automatically upload the articles to your CMS, such as WordPress, Webflow, or a headless setup.
If you want to scale your content production, TopicForge helps you run these batch jobs without monthly agency retainers. You can purchase article packs—such as a 10-pack for $49 or a 100-pack for $399—to match your exact growth goals.
FAQs
What is the maximum number of topics allowed in a single TopicForge batch JSON?
While you can run smaller batches, the API is optimized to handle dozens of articles in a single call. A 50-topic batch is a standard size that balances processing speed with easy review workflows.
Can I apply different brand guardrails to individual topics in the same batch?
Yes. You can define global guardrails like voice profiles and product facts at the root level of the JSON payload, or override them for specific topics within the topics array.
What format does the TopicForge API return for the generated articles?
The API returns a JSON response containing a markdown body, meta description, FAQ JSON-LD, and CTA copy for each successfully processed topic in your batch.
How much does it cost to run a 50-topic batch?
TopicForge uses a pay-per-article pricing model. A 50-topic batch costs approximately $4.90 per article when purchasing a 10-pack—or down to $3.99 per article with a 100-pack—with no monthly agency retainers required.