API Integration

Generate prompts from your own apps

5 min read

The PromptAnvil REST API lets you generate prompts programmatically from any application. Authenticate with an API key, browse available packs, and create prompt batches — all without touching the web interface.

🔑

API Keys

Create & manage from your profile

📦

Prompt Packs

Browse demo & hub packs via API

⚡

Free Quota

25–1000 free requests/day

Base URL & Authentication

All API requests go to the same base URL and require a Bearer token:

text
Base URL: https://www.promptanvil.com/api/v1
Authorization: Bearer pa_xxxxxxxxxxxxx

Getting Your API Key

  1. Sign in to your profile
  2. Scroll to the "API Keys" section
  3. Click "Create New Key", give it a name
  4. Copy the key immediately — it's shown only once

Security: Never share your API key or commit it to version control. API keys are hashed with SHA-256 on our servers — we can't recover a lost key.

API Endpoints

1

List Available Packs

GET/api/v1/packs

Returns all available prompt packs. Filter by source (demo, hub, or all), search by keyword, or filter by tag.

bash
# List all packs
curl -s https://www.promptanvil.com/api/v1/packs \
  -H "Authorization: Bearer pa_xxxxxxxxxxxxx"

# Filter by source and search
curl -s "https://www.promptanvil.com/api/v1/packs?source=demo&search=portrait" \
  -H "Authorization: Bearer pa_xxxxxxxxxxxxx"

Response Shape

json
{
  "success": true,
  "data": {
    "packs": [
      {
        "slug": "cinematic-photography",
        "title": "Cinematic Photography",
        "description": "Film-inspired shots with dramatic lighting",
        "source": "demo",
        "categories": 3,
        "templates": 12,
        "tags": ["Photography", "Cinematic"]
      }
    ],
    "total": 11
  }
}
2

Generate Prompts

POST/api/v1/generate

Generate prompt variations from a pack. Specify the pack slug and the number of prompts you want (1–200).

bash
curl -s -X POST https://www.promptanvil.com/api/v1/generate \
  -H "Authorization: Bearer pa_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"pack": "cinematic-photography", "count": 10}'

Response Shape

json
{
  "success": true,
  "data": {
    "pack": { "slug": "cinematic-photography", "title": "Cinematic Photography" },
    "prompts": [
      "A cinematic shot of a lone figure walking through fog-covered streets...",
      "Golden hour portrait with soft bokeh and vintage film grain..."
    ],
    "count": 10,
    "generated_at": "2026-04-07T12:00:00.000Z"
  },
  "meta": {
    "quota": { "daily_used": 3, "daily_limit": 25, "is_free": true },
    "coal_charged": 0,
    "coal_remaining": 98
  }
}

Quota & Pricing

Every plan includes free daily API requests. Once you exceed your daily quota, each additional request costs 2 Coal. Quotas reset at midnight UTC.

PlanFree Requests/DayAfter Quota
Free252 Coal / request
Pro2002 Coal / request
Team1,0002 Coal / request

💡 Tip: Check the meta.quota object in every response to track your remaining daily free requests. When is_free becomes false, Coal will be charged.

Error Handling

All errors follow a consistent format with an error code and message:

json
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  }
}
HTTPCodeMeaning
401MISSING_AUTH / INVALID_API_KEYMissing or invalid API key
402INSUFFICIENT_COALNot enough Coal after quota exceeded
404PACK_NOT_FOUNDPack slug doesn't exist
429RATE_LIMITEDToo many requests (3s cooldown)

Complete Example

Here's a complete workflow: list packs, pick one, and generate prompts.

bash
# 1. List packs and pick a slug
PACKS=$(curl -s https://www.promptanvil.com/api/v1/packs \
  -H "Authorization: Bearer $API_KEY")
echo "$PACKS" | jq '.data.packs[] | .slug'

# 2. Generate 20 prompts from a pack
curl -s -X POST https://www.promptanvil.com/api/v1/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack": "cinematic-photography", "count": 20}' \
  | jq '.data.prompts[]'

Rate Limits

📦 /api/v1/packs

1 second cooldown per IP address

⚡ /api/v1/generate

3 seconds cooldown per IP address

Batch WorkflowsGet Your API Key