Blog Get Started›

Best Practices for AI Agents

Guidelines for building reliable AI agent integrations with PageGun.

Content Quality

Generate unique content — Avoid duplicate or thin pages
Use proper heading hierarchy — H1 → H2 → H3, don't skip levels
Write compelling descriptions — Every page needs a good description for SEO
Set OG images — Use og_image_url for social sharing

API Usage

Create as draft first — Don't auto-publish; let humans review
Use descriptive slugs — best-ai-tools-2024 not page-47
Batch operations carefully — Respect rate limits (60/min free, 300/min pro)
Handle errors gracefully — Check for error in responses and retry with backoff
Include all sections on update — config replaces the entire object

Section Best Practices

Hero — Keep headlines under 10 words; description under 30 words
Features — 3-6 features is ideal; each needs a title and content
FAQ — 4-8 questions; answer common objections
CTA — Use action verbs: "Start", "Get", "Try", not "Click here"
Problem/Solution — 3 items each for visual balance

Directory Sites

Consistent attributes — All items should use the same attribute types
Category organization — Use consistent category naming for filter tabs
Rich descriptions — Each item should have meaningful markdown_content
Images — Always include og_image_url for item cards

Error Handling

response = requests.post(url, json=data, headers=headers)
result = response.json()

if "error" in result:
    code = result["error"]["code"]
    if code == "rate_limited":
        time.sleep(int(response.headers.get("Retry-After", 60)))
        # retry
    elif code == "validation_error":
        # fix input and retry
    else:
        # log and alert

Idempotency Pattern

To avoid duplicate pages, check before creating:

# List existing pages
existing = pagegun.list_pages(project_id=PROJECT_ID, type="article")
existing_slugs = {p["slug"] for p in existing["data"]}

# Only create if slug doesn't exist
if "my-new-post" not in existing_slugs:
    pagegun.create_page(slug="my-new-post", ...)

Rate Limit Strategy

Batch creates with 1-second delays between requests
Cache project/page lists to reduce read calls
Use webhooks instead of polling for status changes