Developer documentation

The SproutPad API

One REST + MCP surface for agent-provisioned infrastructure: domains, DNS, TLS, hosting, and email — every mutation policy-checked, budget-capped, human-approved when it matters, and written to an append-only audit ledger. This page is the human-readable companion to the machine-readable ground truth at /openapi.json.

Quickstart

1
Create an account

POST /v1/signup (or the homepage form) returns a Stripe Checkout URL, a sessionId, and a claimSecret. Card on file, no upfront charge. Agents: hand the human the URL (keep the claimSecret to yourself), then poll POST /v1/signup/poll (MCP: poll_signup) with the sessionId and claimSecret to receive your agent key directly — no one has to open our site. Already on a scratch account, or replacing an expired card? POST /v1/billing/setup-link + /v1/billing/poll (MCP: setup_billing/poll_billing) run the same flow and upgrade you to a full account.
2
Connect your agent

Paste the MCP config from the claim page into Claude, Cursor, or anything that speaks MCP — or call REST directly with Authorization: Bearer agk_…. OAuth 2.1 (PKCE + dynamic registration) also works.
3
Plan, then launch a service

search_domains and estimate need no auth and create no hold. An authenticated ALLOW quote reserves project budget for 15 minutes; launch_service creates a named service (the thing that runs), then carries domain registration, DNS, deploy, and TLS through a durable task. Projects are billing groups, not containers.

The whole setup, from your agent's point of view:

{
  "mcpServers": {
    "sproutpad": {
      "url": "https://api.sproutpad.ai/mcp",
      "headers": { "Authorization": "Bearer agk_..." }
    }
  }
}

Conventions the whole API follows

Services are the product

A service is a named thing that runs, each with its own preview URL. Projects are billing groups with budgets and policy; domains and email addresses are org-level assets attached to services and inboxes.

Idempotency everywhere

Every mutating endpoint accepts an Idempotency-Key header. Retrying with the same key and body replays the stored response instead of re-executing — safe for flaky networks and looping agents alike.

Responses teach the next step

Success bodies arrive in an envelope: { data, receipt?, undo?, budgetRemainingCents, nextActions }. The receipt is ledger-derived; undo tells you how to reverse the action (or that you can't).

Structured errors, never bare codes

Errors are { blockedBy, message, resolution } with namespaced causes (budget:*, policy:*, plan:*, …). resolution names the exact legitimate path forward — a link, a task to poll, a retry hint — and is absent only when no path exists. Envelopes validate against the published JSON Schema.

Humans hold the irreversible levers

Domain purchases and budget raises wait for a human decision (one-tap link or dashboard) by default — a human can grant a key the buy_domain scope to skip the per-purchase gate. There is deliberately no agent-reachable approval endpoint — a leaked gate id resolves nothing.

Long work is task-shaped

Launches, teardowns, and email setup return 202 with a task handle. Poll GET /v1/tasks/{id}; input_required surfaces the approval URL your human needs.

Rate limits on anonymous surfaces

Search, quotes, and signup are rate-limited per caller. A 429 comes with retryable: true — back off briefly and retry with your idempotency key.

Your domains are yours — leaving is one call

POST /v1/projects/{id}/export returns the full leave package (zone files, site assets, audit ledger); transfer codes take one human approval. Opt in to be the ICANN registrant of record (set_registrant_contact) and ownership never depends on us. The whole governance model is an open spec.

What we run on

Payments: Stripe

Cards go to Stripe Checkout and stay there — numbers never touch our code, logs, or database. Budget caps are enforced server-side before any charge, so your bill can't exceed the cap you approve.

Edge: Cloudflare

The API and this site sit behind Cloudflare (DDoS absorption, WAF, TLS with HSTS). The origin only accepts traffic that came through the edge. Check the response headers of any request to verify.

Your sites: two deploy targets

Server-backed services run on their own isolated virtual machine — not shared hosting — from $3/mo. Static sites you (or your agent) wrote can instead deploy to a global edge network for $0/mo: upload_assets, then launch_service with target: "cloudflare". HTTPS is provisioned automatically either way, and teardown stops the meter the same day.

Registrars: real relationships

Domains are fulfilled through accredited registrar channels (about 40 popular TLDs near wholesale via Cloudflare Registrar; hundreds more via name.com). Registered domains are yours — transfer out anytime.

You own what you buy

Domains, sites, and mailboxes your agent buys belong to you, not to SproutPad. By default we hold the registrant paperwork on your behalf for convenience, but you can opt in to be the ICANN registrant of record yourself (name.com path), transfer any domain out with one click and no exit fee, and take everything with you at any time: export_project returns the full leave package — zone file, site assets, and audit log (transfer auth codes are approval-gated).

Trust you can check, not take

Every action lands in an append-only ledger you can export. Opt into verifiable budget mode and your budget stops being our promise: you sign an AP2 Payment Mandate in your browser (your spend ceiling as a cryptographic credential), we enforce it alongside the project cap, and every committed spend emits proofs anyone can verify at POST /v1/ap2/verify against /.well-known/jwks.json — no access to our database required. Your signature also names SproutPad's published key as the only key allowed to stamp proofs under your mandate, so a proof stamped by any other key, or with the stamp missing, fails verification for everyone.

Launch templates & deploy targets

launch_service deploys to one of two targets. Fly containers (the default) run a real server process on an isolated VM — pick a curated template below by purpose, or bring a public image from docker.io / ghcr.io / quay.io / public.ecr.aws. Cloudflare edge static assets (target: "cloudflare") serve HTML/CSS/JS your agent generated itself from a global edge network — no cold starts, $0/mo: upload_assets returns a bundleId (root index.html required, ≤200 files, ≤10 MB, static content types only), then launch_service with that bundleId. Baseline security headers (HSTS, nosniff, referrer trimming) are added by the platform on edge deploys.

`static-site`	Static web server (unprivileged nginx) for landing pages, portfolios, docs. From $3/mo on a VM — but if the HTML is ready, prefer the edge target instead ($0/mo, faster).
`whiteboard`	Excalidraw — collaborative whiteboard for sketching and diagrams. Runs a server process; Fly only. From $3/mo.
`linktree`	Link-in-bio page (LittleLink) — one tidy page of links. Fly container from $3/mo; plain-HTML equivalents can use the edge target for $0/mo.
`uptime`	Uptime Kuma — self-hosted uptime monitor with public status pages. Needs a persistent volume (1 GB, +$1/mo) and a long-running process; Fly only. From $4/mo.

Agents discover the same list (with keywords and target guidance) via the list_templates tool or GET /v1/templates — no auth required. Edge hosting fair use: $0/mo comfortably covers typical sites (up to ~1M requests/month per site). If a site sustains far more, we'll reach out before anything changes — traffic is never throttled without a human conversation first.

API reference

Rendered live from /openapi.json, and covered by a test that fails the build if an endpoint ships undocumented. Dashboard, session, and operator surfaces are internal and not part of the public API.

Loading the reference…

Changes

The API evolves additively under /v1 — existing fields and endpoints don't break. Spec version dates below mark when the reference last meaningfully changed.

2026-07-07

First complete public reference: all agent-facing endpoints documented with request/response schemas, auth schemes (agent keys + OAuth 2.1), idempotency semantics, and the error/resolution model. This page went live.