Prompt Mode

Prompt mode lets you describe a page in natural language and have AI generate the full page spec: components, theme, and optional scoped CSS.

How it works

1. Send prompt instead of components to POST /api/page-jobs
2. Include Idempotency-Key header
3. Receive 202 with a job ID
4. Poll GET /api/page-jobs/{jobId} until status === "succeeded"
5. Optionally send model (gpt-5-mini or gpt-5.2)
6. ChatBlocks generates a structured page spec
7. The generated spec is validated and saved like any other page

Usage

curl -X POST https://chatblocks.app/api/page-jobs \
  -H "Authorization: Bearer cb_live_YOUR_KEY" \
  -H "Idempotency-Key: prompt-my-portfolio-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-portfolio",
    "prompt": "A dark-themed portfolio page for a software engineer with a hero section, project cards, skills timeline, and contact info",
    "model": "gpt-5-mini"
  }'

Model selection

• gpt-5-mini — default, faster and cheaper
• gpt-5.2 — more capable

Model selection is per request. If omitted, gpt-5-mini is used.

Rules

• prompt and components are mutually exclusive
• Prompt max length: 5,000 characters
• Rate limit is tiered by auth type (API key vs session)
• Prompt mode is supported in bulk page jobs (POST /api/page-jobs/bulk)
• Prompt text is not stored on the page record (generated output is stored)

Output fields

Rate limiting

AI generation attempts are tracked in ai_generation_logs. At limit, the API returns 429:

{
  "error": "Rate limit exceeded. You can generate 60 prompt pages per hour."
}