When you run a batch of fifty programmatic articles through an API, sending only a list of target keywords results in generic, repetitive content. Standard LLM APIs without specific guidance per row default to the most common public data. They ignore your actual product features and your unique point of view.
To produce search content that actually converts, you must give the generator specific instructions for every single page. Managing these instructions at scale requires a structured approach to your metadata.
What is per-topic guidance in programmatic SEO?
Per-topic guidance consists of article-specific instructions passed alongside a keyword in a generation payload. This is different from your global brand guidelines. Global rules define your brand's overall tone, style, and banned words—per-topic guidance tells the generator what to say about a highly specific subject.
Content operations teams typically manage these inputs in databases like Airtable, Google Sheets, or Postgres. When exporting these records to run a batch job, the instructions map to a dedicated JSON field—such as topicGuidance or anchor_instructions.
Without this field, a batch run of ten articles about "fleet management" will sound identical. By injecting unique angles into each row, you ensure that an article about fuel tracking focuses strictly on fuel sensors—while an article about safety compliance focuses on driver cameras and local laws.
The anatomy of a structured topicGuidance field
A vague prompt produces a vague article. To get predictable results from your batch runs, structure your per-topic guidance field with three core components:
- The target reader's specific pain point: Identify exactly who is reading this specific page and what problem they are trying to solve.
- The exact product feature to highlight: State which part of your software or service directly solves that pain point.
- Factual data points or references: Provide real numbers or specific industry standards the AI must mention.
For example, if you are writing an article about routing efficiency, your guidance field should not just say "write about routing." Instead, specify: "Target regional delivery dispatchers who struggle with last-mile delays. Focus on our dynamic dispatching feature. Mention that manual routing typically wastes up to two hours per driver daily [illustrative example]."
Best practices for writing per-topic instructions
Writing instructions for an AI pipeline is similar to delegating tasks to a human freelance writer. You must be direct, specific, and brief.
Use imperative verbs
Start your instructions with strong, active verbs. Use directives like "Explain," "Compare," "Analyze," or "Highlight." Avoid passive phrasing like "This article should ideally talk about..." or "It would be good to include..."
Avoid vague adjectives
Do not tell the generator to write an "engaging," "high-quality," or "thought-provoking" article. These words do not contain actionable formatting or conceptual instructions. The AI cannot translate "high-quality" into concrete paragraphs. Instead, define quality by what is included: "Provide a step-by-step checklist for compliance."
Keep instructions under 150 words
Long, rambling instructions dilute the core message. When a prompt contains too many competing ideas, the model may ignore the most important constraints. Keep your per-topic field between 50 and 150 words. Focus only on the unique angle of that specific article.
Common mistakes to avoid in batch JSON payloads
When scaling up content production to dozens or hundreds of pages, minor errors in your data preparation can ruin an entire batch.
Repeating global brand rules
Do not write "Write in a friendly tone and do not use jargon" in every single row of your database. Repeating these rules increases your API token costs and distracts the model from the unique instructions for that topic. Keep your global rules in your global configuration file and reserve the per-topic field for article-specific details.
Using conflicting instructions
Ensure your per-topic guidance does not contradict your global settings. If your global profile bans the word "synergy," but your per-topic guidance says "Explain our API synergy," the generator will struggle to resolve the conflict.
Leaving the field blank for complex topics
If a topic covers a highly technical or regulated subject, leaving the guidance field empty forces the AI to guess the details. This often leads to hallucinations or generic advice that fails to address the reader's actual problem. If a topic is complex, it requires specific guidance.
A concrete JSON example for batch generation
When sending data to a programmatic SEO pipeline, your JSON payload must map your keywords and specific instructions clearly.
Below is a realistic example of a B2B SaaS payload structured for a batch run:
{
"articles": [
{
"keyword": "construction fleet maintenance scheduling",
"title": "How to set up a preventative maintenance schedule for construction fleets",
"topicGuidance": "Target construction project managers. Focus on the cost of unexpected heavy equipment downtime. Highlight our automated engine hour tracking feature. Mention that unplanned repairs cost fleets an average of $300 more per incident than scheduled maintenance [illustrative example]."
},
{
"keyword": "cold chain temperature monitoring",
"title": "A guide to cold chain temperature compliance for food distributors",
"topicGuidance": "Target logistics directors in food distribution. Address the risk of cargo spoilage during transit. Highlight our real-time Bluetooth temperature sensors and automated alert system. Reference FDA food safety modernization act compliance requirements."
}
]
}
This structure allows the generation engine to parse the unique requirements for each article, ensuring the output matches your product's actual use cases.
How TopicForge applies your per-topic guidance
TopicForge handles complex, structured batch runs without losing editorial control. Instead of relying on a single prompt to write an entire page, TopicForge uses a four-stage AI pipeline powered by Gemini via Vertex AI.
When you submit a batch job via the TopicForge API, the platform processes each article through four distinct stages:
- Outline: The system reads your
topicGuidanceto build a custom outline that prioritizes your specified features and target audience. - Draft: The pipeline drafts the body copy, integrating your specific data points and product angles.
- Voice pass: The draft is refined to ensure it adheres to your global voice profile, brand facts, and banned phrases.
- CTA + SEO metadata: The system generates a relevant call-to-action, meta description, and FAQ schema based on the unique angle of the article.
By separating these steps, TopicForge ensures that your specific per-topic instructions are followed at every stage of the writing process—while your global brand guardrails remain completely secure.
If you need to scale your B2B search content without managing complex prompt engineering or hiring writers, you can run your content operations directly through TopicForge. The platform offers a programmatic batch jobs API. Pricing starts at $10 for a single article, drops to $49 for a 10-pack—about $4.90 per article—and goes down to $399 for a 100-pack, which is about $3.99 per article.
FAQs
What is the difference between global voice profiles and per-topic guidance?
A global voice profile defines your brand's overall tone, style, and banned phrases across all content. Per-topic guidance is article-specific, telling the generator which exact features, angles, or data points to focus on for that single piece of content.
How long should the topic guidance field be in my JSON payload?
Keep your instructions concise, ideally between 50 and 150 words. Focus on concrete directives like target audience, key product features to mention, and specific data points rather than generic writing advice.
Can I include HTML or Markdown inside the topic guidance field?
It is best to use plain text inside the JSON string for your instructions. The generation pipeline handles the Markdown formatting for the final output, so your instructions only need to focus on the content and angle.
How does TopicForge handle conflicting instructions between global rules and topic guidance?
TopicForge's four-stage pipeline evaluates both global guardrails and per-topic guidance. If there is a conflict, global brand safety rules and banned phrases take precedence to ensure your brand standards are never compromised.