Quickstart for agents

Bonus: generate an SEO article

curl -X POST https://serp-agent.com/v1/projects/proj_01h9x2/articles \
  -H "Authorization: Bearer $SERP_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-wp-migration-1" \
  -d '{"topic": "How to migrate a WordPress site without losing rankings", "primary_keyword": "wordpress migration seo"}'

# → 202 { "article_id": "art_01h9x5", "status": "queued", "poll": "/v1/articles/art_01h9x5" }
# Poll every ~60s; generation typically takes 10-30 minutes.
curl https://serp-agent.com/v1/articles/art_01h9x5 \
  -H "Authorization: Bearer $SERP_AGENT_API_KEY"

Status walks generating → qa → ready. Once ready, the response carries title, meta_description, content_markdown, word_count, qa_score, and language. Articles are drafts — publishing is yours. One article generates per project at a time (409 article_in_progress otherwise); sandbox articles carry a watermark object.

Webhooks instead of polling

curl -X POST https://serp-agent.com/v1/webhooks \
  -H "Authorization: Bearer $SERP_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://agent.example.com/hooks/serp-agent", "events": ["audit.completed", "article.published"]}'

# → 201 includes "secret" (shown once). Verify every delivery:
#   expected = hex(hmac_sha256(secret, raw_request_body))
#   compare with the X-SerpAgent-Signature header
# Dedupe on X-SerpAgent-Delivery (stable across retries); respond 2xx within 10s.

Omit events (or pass []) to subscribe to everything. Failed deliveries retry with exponential backoff (max 8 attempts); 50 consecutive failures deactivate the endpoint.

Error handling conventions

• Every non-2xx response has the same body: {"error": {"code": "...", "message": "...", "doc_url": "..."}}. Branch on code, not on message text. Full catalog: /docs/errors.
• 429 rate_limited: wait the number of seconds in the Retry-After header, then retry. Budgets: 600 requests/minute per API key (authenticated routes), 5 signups/hour per IP. Every response carries X-RateLimit-Limit / -Remaining / -Reset.
• Idempotency: send an Idempotency-Key header (any unique string, ≤200 chars) on every creating POST. Retries replay the stored response verbatim — including one-time secrets — with Idempotent-Replayed: true. Never reuse a key across different endpoints (409 idempotency_conflict).
• 402 payment_required / insufficient_credits: the project needs an active subscription, or the credit balance is short (the body carries required_credits / balance_credits and both purchase paths). See the billing section below. 403 sandbox_limit_reached: trial budget exhausted — upgrade to continue.
• 404 not_found: the id does not exist on your account (foreign ids look identical to missing ones).

Billing: two ways to pay

Machine-readable pricing lives at GET /v1/plans (public, no auth). Creem is the merchant of record; there is no base platform fee. Live keys (sk_live_) can pay two ways — sandbox keys are never billable (403 sandbox_not_billable):

• Per-project subscription (all-inclusive): POST /v1/subscriptions with {"project_id": "...", "plan_id": "basic"|"pro"} — Basic $199/mo, Pro $299/mo, one subscription per project. Subscribed projects run audits and articles with no per-unit charges. Status: GET /v1/subscription?project_id=....
• Prepaid credits (à la carte): 1 credit = $1 list price. Without a subscription, work endpoints charge your balance per unit (technical audit 25, article 15 — full price list at GET /v1/credits). Buy packs with POST /v1/credits/purchases — larger packs carry bonus credits ($500 → 500, $2,000 → 2,200, $10,000 → 12,500).

The checkout handoff pattern

Payment itself always happens in a browser (Creem checkout) — the API never takes card details. Both purchase endpoints return status: "pending_payment" plus a checkout_url: surface that URL to your human, then poll until the webhook lands.

# 1. Create the checkout (subscription shown; credits work the same)
curl -X POST https://serp-agent.com/v1/subscriptions \
  -H "Authorization: Bearer $SERP_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-proj_01h9x2-1" \
  -d '{"project_id": "proj_01h9x2", "plan_id": "pro"}'
# → 201 { "status": "pending_payment", "checkout_url": "https://checkout.creem.io/...", ... }

# 2. Hand checkout_url to your human — they pay in the browser.

# 3. Poll until active (activation is automatic via webhook):
curl "https://serp-agent.com/v1/subscription?project_id=proj_01h9x2" \
  -H "Authorization: Bearer $SERP_AGENT_API_KEY"
# → { "project_id": "proj_01h9x2", "plan": "pro", "status": "active", "paid_until": "..." }

# Credits: POST /v1/credits/purchases {"pack_id": "pack_2000"} → same handoff,
# then poll GET /v1/credits for balance_credits. Or subscribe to the
# "subscription.updated" / "credits.updated" webhook events instead of polling.

Honest v1 limits: article_published (+5 credits) is not auto-charged — credit-funded articles are draft-only (fetch content_markdown and publish yourself); automated publishing to a connected CMS requires a project subscription. Monthly-priced units (AI visibility monitoring, local SEO autopilot) are not yet purchasable with credits. If a pack returns 503 billing_not_configured, that product is not set up yet on the server — use a subscription or retry later.