Developer API

Read your projects and render panels from your own code or an AI agent. Renders use the same credits as the app.

Authentication

Create a key in Settings and send it as a Bearer token. A key is shown once; revoke it there if it leaks. Open Settings

Authorization: Bearer pf_live_…

Key access

A key can be limited in Settings; a new key has full access unless you narrow it. Scopes: read (projects, pages, balance) and generate (estimate, start, cancel). Any key can read prices and poll operations. A call outside its scopes gets 403 insufficient_scope, and over MCP the tools a key can't use aren't listed. A key limited to some projects sees no others: they answer 404. A key's credit limit is checked when a render starts, so concurrent calls can't pass it: over the limit, start gets 403 key_credit_limit. Refunded renders don't count. GET /api/v1/credits shows the key's limit and spending.

Render a panel

Paid work takes four steps: estimate (free, valid 10 minutes), start with the price you accept and an Idempotency-Key, then poll. If the project changed since the estimate, start is refused: estimate again. A failed or cancelled render is refunded.

KEY=pf_live_…

# 1. Estimate (free). Returns estimate_id, credits and page_version.
curl -X POST https://www.palmframe.com/api/v1/estimates \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"project_id": "…", "panel_id": "…", "prompt": "rooftop chase at night"}'

# 2. Start: charges the estimate. Retrying with the same key is safe.
curl -X POST https://www.palmframe.com/api/v1/generations \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"estimate_id": "…", "page_version": 12, "max_credits": 20}'

# 3. Poll until succeeded (result.image_url), failed or cancelled.
curl https://www.palmframe.com/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $KEY"

# Cancel and refund a queued or running render.
curl -X POST https://www.palmframe.com/api/v1/operations/OPERATION_ID/cancel \
  -H "Authorization: Bearer $KEY"

Projects and credits

curl https://www.palmframe.com/api/v1 -H "Authorization: Bearer $KEY"            # prices, limits
curl https://www.palmframe.com/api/v1/credits -H "Authorization: Bearer $KEY"
curl https://www.palmframe.com/api/v1/projects -H "Authorization: Bearer $KEY"
curl https://www.palmframe.com/api/v1/projects/PROJECT_ID -H "Authorization: Bearer $KEY"

MCP

The same operations are MCP tools at /mcp (Streamable HTTP), with the same key.

claude mcp add --transport http palmframe https://www.palmframe.com/mcp \
  --header "Authorization: Bearer $KEY"

# Tools: get_capabilities, get_credit_balance, list_projects, get_project,
# estimate_panel_generation, start_panel_generation, get_operation,
# cancel_operation

Limits

120 reads and 20 writes per minute per key. 2 active renders per account and 8 in total; the renderer draws one panel at a time.