For agent builders.

# 1. Discover the base URL + MCP endpoint + docs (unauthenticated)
curl https://relay.cumulush.com/.well-known/relay.json

# 2. Prove the token works
curl -H "Authorization: Bearer agt_..." \
     https://relay.cumulush.com/v1/whoami

# 3. Browse the provider catalog in chunks (see next section)
curl -H "Authorization: Bearer agt_..." \
     https://relay.cumulush.com/v1/index

The three-step flow

# Step 1 — what categories exist right now?
#   Returns:  { categories:[{ slug, displayName, count, providerIds }],
#              aliases:{ "hoster":"hosting", "mail":"email", ... } }
curl -H "Authorization: Bearer agt_..." \
     https://relay.cumulush.com/v1/index

# Step 2 — full details for just the category you need.
#   Optional: ?capability=postgres&pricing=free-tier
#   Returns:  { category, displayName, providers:[ProviderSummary...] }
curl -H "Authorization: Bearer agt_..." \
     "https://relay.cumulush.com/v1/index/database?capability=postgres"

# Step 3 — pick one + sign up as usual.
curl -X POST -H "Authorization: Bearer agt_..." \
     -H "Content-Type: application/json" \
     -d '{"provider":"neon","input":{"name":"my-app-db"}}' \
     https://relay.cumulush.com/v1/signups

The MCP equivalents are list_categories and list_providers_by_category. list_categories does not take an agent_token — the overview is public discovery data.

Canonical categories

Every category query is normalized server-side. Aliases like hoster → hosting, mail → email, or logs → observabilityresolve automatically so an agent's fuzzy guess still lands on the right chunk. The full alias map is returned on GET /v1/index.

Fields on each provider

• pricingModel: one of free, free-tier, paid, usage-based, freemium — or null if unspecified.
• pricingUrl, freeTierSummary: one-line human-readable pointers so an agent can show the user a sane comparison without scraping.
• capabilities: array of lower-case tags (e.g. ["postgres", "serverless", "branching"]). Filter with ?capability=… on the HTTP side, or the capability:[…] argument on the MCP tool — multiple values AND together.
• categories, displayName, description, docsUrl, homepage, npmPackage, inputSchema — all the usual provider metadata.

Worked example

User says "I need a free Postgres database." Agent runs:

list_providers_by_category({
  category: "database",
  capability: ["postgres"],
  pricing: "free-tier"
})

# → { category: "database",
#     providers: [
#       { id: "neon",
#         pricingModel: "free-tier",
#         freeTierSummary: "0.5 GB storage and ~190 compute hours per month…",
#         capabilities: ["postgres","serverless","branching", ...],
#         … }
#     ] }

create_signup({
  provider: "neon",
  input: { name: "my-app-db" }
})

# REST discovery
curl https://relay.cumulush.com/v1/index
curl "https://relay.cumulush.com/v1/index/database?capability=agent-memory"
curl "https://relay.cumulush.com/v1/index/ai"

# REST signup
curl -X POST -H "Authorization: Bearer agt_..." \
     -H "Content-Type: application/json" \
     -d '{
       "provider": "cumulus-database",
       "input": {
         "email": "alex@example.com",
         "purpose": "project memory"
       }
     }' \
     https://relay.cumulush.com/v1/signups

# Poll until status is "complete".
curl -H "Authorization: Bearer agt_..." \
     https://relay.cumulush.com/v1/signups/<signup_id>

# First complete response only:
{
  "signup_id": "<signup_id>",
  "status": "complete",
  "account_id": "<account_id>",
  "initial_credentials": {
    "endpoint": "https://db.cumulush.com",
    "database_id": "db_...",
    "data_token": "cdb_data_...",
    "admin_token": "cdb_admin_..."
  }
}

MCP agents use the same flow with list_categories, list_providers_by_category, create_signup, and get_signup_status. The initial_credentials object is returned exactly once. Put data_token in the project runtime and treat admin_token as a one-time administrative secret.

create_signup({
  provider: "cumulus-database",
  input: {
    email: "alex@example.com",
    purpose: "project memory"
  }
})

get_signup_status({ signup_id: "<signup_id>" })

# "Wire up Postgres and transactional email for this workspace."
curl -X POST -H "Authorization: Bearer agt_..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "goal": "Postgres + transactional email for a Next.js app",
       "workspaceId": "ws_..."
     }' \
     https://relay.cumulush.com/v1/intent

# Response (always 200; partial success is normal):
# {
#   "resolutions": [
#     { "category": "database", "alias": null, "provider": "neon",
#       "status": "existing", "accountId": "acc_...",
#       "envVar": "DATABASE_URL",
#       "revealUrl": "/v1/accounts/acc_.../api-keys/key_.../reveal" },
#     { "category": "email", "alias": null, "provider": "resend",
#       "status": "provisioning", "signupJobId": "sj_...",
#       "pollUrl": "/v1/signups/sj_...",
#       "envVar": "RESEND_API_KEY" }
#   ],
#   "envBlock": "DATABASE_URL=__reveal_required__\nRESEND_API_KEY=__pending__\n",
#   "pending": ["sj_..."],
#   "unsatisfied": [],
#   "unmatchedTerms": [],
#   "revealAllUrl": "/v1/accounts/keys/reveal-batch",
#   "notes": [
#     "Resend signup requires email verification — poll /v1/signups/sj_..."
#   ]
# }

What it does for you

• Parses the goal into canonical categories (heuristic keyword match — no LLM, fully deterministic).
• Picks a provider per category by pricing model (free → free-tier → freemium → usage-based → paid, then alphabetical). When two providers tie, the resolution comes back as status: "ambiguous" with a candidates list — pin one to choose.
• Dedups against existing accounts in the workspace. If the user already has a Neon project for the primary alias, the resolution comes back as status: "existing" with the accountId — no duplicate provisioning.
• Kicks signups for the gaps via the standard workflow. The resolution comes back as status: "provisioning" with a signupJobId + pollUrl — poll GET /v1/signups/:id exactly as you would for a direct POST /v1/signups call.
• Builds the env block in deterministic order (canonical category, then alias). Sentinels __pending__ and __reveal_required__ mark the slots a follow-up call needs to fill. Fresh signups inline plaintext on first read.

Pinning a provider or alias

When you need a specific provider, or two distinct accounts inside the same category (a primary + analytics Postgres, for example), pass a pin array. Each pin becomes its own resolution slot:

{
  "goal": "Postgres for the app and a separate Postgres for analytics",
  "workspaceId": "ws_...",
  "pin": [
    { "category": "database", "providerId": "neon", "alias": "primary" },
    { "category": "database", "providerId": "neon", "alias": "analytics" }
  ]
}

# → resolutions[0].envVar = "DATABASE_URL_PRIMARY"
# → resolutions[1].envVar = "DATABASE_URL_ANALYTICS"

Idempotency-Key

Send Idempotency-Key on retries. Relay caches the response per (agent, key) for 24 hours, so a retry after a 5xx never duplicates signups.

Billing

The intent call itself is free. Each spawned signup bills the integrator's quota normally — same gate as a direct POST /v1/signups call. Calling intent on a fully-existing workspace is a free, deterministic dedup check.

MCP equivalent

The MCP tool is resolve_intent — same shape, slimmer response (no reveal URLs, since LLMs would speculatively call them). For an existing account where the agent needs the actual plaintext, follow up with get_api_key to mint a fresh one.

{
  "mcpServers": {
    "relay": {
      "url": "https://relay.cumulush.com/mcp"
    }
  }
}

"Use this Relay agent_token for every tool call you make: agt_XXXX…"

Full schemas are published on the MCP endpoint via tools/list. Browse the same shapes as REST at /docs/api.

## Relay
RELAY_AGENT_TOKEN=agt_XXXXXXXX…
# Expires: 2026-05-21 (30 days from 2026-04-21).
# This token lets your AI agent provision SaaS accounts via Relay.
# Re-run register_tenant in MCP after expiry; or pass never_expires:true
# if the user explicitly asked for a non-rotating token.

• Tokens minted via `submit_verification_code`, `register_tenant`, or the CLI flow default to 30 days. The response includes `agent_token_expires_at` (ISO-8601, or `null` for non-expiring tokens).
• Save the token into the user's project CLAUDE.md under a `## Relay` heading. Include the expiry date as a comment so future sessions know when to rotate.
• On the next call after expiry, Relay returns `{ "error": "agent_token_expired" }`. Tell the user, call `register_tenant` again, and overwrite the CLAUDE.md entry with the new token.
• Only pass `never_expires: true` when the user has explicitly asked for a non-rotating token. A 30-day token is the secure default.

// 1. Hand the user a Stripe Checkout link
start_subscription({ agent_token, tenant_id, plan: "builder" })
// → { checkout_url: "https://checkout.stripe.com/c/pay/cs_..." }

// 2. Human opens the link, pays with a card, is redirected back.
// 3. Stripe's webhook flips the subscription to active; poll:
get_subscription_status({ agent_token, tenant_id })
// → { status: "active", plan: "builder", quota: {…} }

If the tenant is already subscribed, start_subscription returns a Stripe Billing Portal URL under already_active.portal_url so the user can change plan, update their card, or cancel — no duplicate subscription.

When a user mints an agent token, it's pinned to whichever workspace they were viewing at the time. That token can only see the data inside that workspace. You never need to include a workspace id in your calls — the binding is on the token row. A call to GET /v1/user/accounts with a token minted inside Workspace A returns Workspace A accounts; calling with a token minted inside Workspace B returns Workspace B accounts. Cross-workspace access is not possible.

REST surface

# List the caller's workspaces (active marker included).
GET  /v1/user/workspaces
# Create a new workspace. Optional { make_active: true } flips the session.
POST /v1/user/workspaces        { name, slug?, make_active? }
# Rename.
POST /v1/user/workspaces/:id/rename   { name }
# Hard-delete (requires confirm_name to equal the workspace name).
DELETE /v1/user/workspaces/:id        { confirm_name }
# Cookie-session-only: pick a different active workspace.
POST /v1/user/workspaces/:id/switch

The switchendpoint is cookie-only because bearer tokens carry an immutable workspace pin. A bearer can still create + delete + rename workspaces on the user's account, but it can never make itself scope to a different workspace.