API Documentation

The Social Business Network API.

REST at /api/v1. GraphQL at /api/graphql (Sprint 1). OAuth 2.0 + scopes (Sprint 1). Webhooks signed with HMAC, retried durably.

Get an API key Back to developers home

§1 · Authentication

Three auth shapes. One resolver.

Every authenticated request resolves through a single middleware (resolveRequestAuth) that maps three auth shapes into one typed context. Pick the shape that fits your integration:

API Key

Sprint 1

Server-to-server

Authorization: Bearer ak_live_2f4a…

For backend integrations, scripts, CI. Hashed at rest with argon2id; only the prefix is shown after creation. Scoped — every key declares the scopes it can use. Rotatable from /developers/keys.

OAuth 2.0

Sprint 1

Apps acting on a creator's behalf

Authorization: Bearer eyJhbGc…

Authorization Code with PKCE. JWT access tokens (15min). Opaque rotating refresh tokens (30d). Granular scopes — your integration earns access narrowly, not all-or-nothing.

Zapier Marketplace

live

Existing path

Authorization: Bearer <marketplace-token>

If you came in via the Zapier Marketplace OAuth bridge, your existing token keeps working. Token implicitly carries the full scope set during the transition window.

§2 · Endpoints

REST at /api/v1.

The full machine-readable spec is served live at /api/v1/openapi.yaml — generated from the route handlers themselves and validated by a pre-commit gate, so it never drifts from production. Drop the URL into any OpenAPI viewer (Stoplight Studio, Swagger UI, Redoc) for an interactive reference.

Download spec (YAML)Open in Stoplight Elements →

Method	Path	Scope	Description	Status
GET	/v1/me	identity:read	Authenticated creator context.	live
GET	/v1/profiles/{handle}	public	Public-safe profile snapshot.	live
GET	/v1/categories	public	Full 12-category × 359-subcategory service taxonomy with example skills.	live
GET	/v1/creators/{handle}/reviews	public	Public verified-buyer reviews + aggregate rating + per-star breakdown.	live
GET	/v1/tiers	tiers:read	Active membership tiers owned by the delegated creator.	live
GET	/v1/bookings	bookings:read	Bookings hosted by the delegated creator (sanitized — no guest PII).	live
GET	/v1/posts	posts:read	Cursor-paginated published public posts.	live
POST	/v1/posts	posts:write	Create a post. Requires Idempotency-Key header.	live
GET	/v1/analytics/overview	analytics:read	Lightweight KPIs + counts. Earnings fields require revenue:read.	live
GET	/v1/webhooks/endpoints	webhooks:read	List webhook endpoints owned by the delegated creator.	live
POST	/v1/webhooks/endpoints	webhooks:write	Create a webhook endpoint. Returns the signing secret once.	live
DELETE	/v1/webhooks/endpoints/{id}	webhooks:write	Disable a webhook endpoint.	live
GET	/v1/agents	agents:read	List the creator's agents (Coworker, etc.).	soon
POST	/v1/agents/{id}/runs	agents:write	Trigger an agent run. sync vs async via ?sync=true.	soon
POST	/v1/agents/{id}/intents	agents:write	Intent Mode: high-level intent → decomposed plan.	soon
GET	/v1/reputation/{handle}	reputation:read	On-chain verified earnings + ratings + Founding Creator status.	soon

Premium tier gating

FREE is generous on reads. STARTER unlocks heavy-compute and compliance endpoints. GROWTH and ENTERPRISE inherit every STARTER entitlement plus higher caps. Calls from a tier below the listed minimum return 402 with code: "tier_gate_blocked" and an upgrade hint pointing at /developers/billing.

Endpoint	Min tier	Why
POST /v1/agents/runs	FREE	Open to every tier; FREE gets 10 runs/month, paid tiers get higher caps. The per-month cap is enforced separately via 402 quota_exceeded.
GET /v1/agents/runs/{runId}	FREE	Reading an individual run by id stays free — keeps debugging ergonomic on the free tier.
GET /v1/agents/cost-summary	STARTER	Day-bucketed cost analytics for spend dashboards — STARTER and up.
GET /v1/audit-log	STARTER	Compliance / SIEM mirror (Datadog, Splunk). Web UI at /settings/security stays free.
GET /v1/analytics/overview	FREE	Lightweight KPIs + counts. Earnings fields still require revenue:read.
GET /v1/analytics/cohort-retention	STARTER	Heaviest analytics surface — multi-week cohort pivot. STARTER and up.
GET /v1/reputation/{handle}	FREE	Public reputation is public — stays open on every tier.

§3 · Conventions

Predictable shapes everywhere.

snake_case in JSON. All v1 response fields use snake_case (price_cents, created_at). Internal Prisma models are camelCase — the boundary is at the route handler.

Money in minor units. All monetary fields are integers in minor units — amount_cents for USD, amount_atomic for USDC (atomic-6). Never floats. Convert at the UI boundary only.

Idempotency on writes. Every POST mutation requires an Idempotency-Key header (max 250 chars). Repeats with the same key return the original response, not a duplicate write.

Errors. Structured envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Body title must be ≤ 200 chars.",
    "request_id": "req_2f4a8c…"
  }
}

Request IDs everywhere. Send X-Request-Id: <your-uuid> and we'll echo it back. We mint one if you don't.

Versioning. Path-versioned at /v1. Within v1: additive only — new endpoints, new optional fields, new scopes. Breaking changes route through /v2 with 12-month overlap.

Rate limits. Tier-driven — see the pricing table for current per-tier burst + per-day limits. 429 responses include Retry-After seconds.

§4 · Webhooks

Signed. Retried. Replayable.

Every delivery carries an HMAC-SHA256 signature in Aggregate-Signature with the standard t=<ts>,v1=<hmac> shape. Verify with the signing secret returned at endpoint creation.

POST <your-endpoint-url>
Content-Type: application/json
Aggregate-Event: post.created
Aggregate-Delivery: del_2f4a8c…
Aggregate-Signature: t=1717327200,v1=abc123…
Aggregate-Idempotency-Key: evt_xyz

{
  "id": "evt_xyz",
  "type": "post.created",
  "created_at": "2026-05-02T18:00:00Z",
  "data": { "id": "post_…", "slug": "…", "title": "…" }
}

Retry schedule. 0s, 30s, 5m, 30m, 2h, 12h, 24h (7 attempts). After 7 fails → DEAD_LETTER. Endpoints auto-disable after 50 consecutive dead-letters.

Replay. Manual replay button per delivery in /developers/webhooks.

Idempotency on receipt. Use Aggregate-Idempotency-Key as your dedupe key — replays carry the same key.

§5 · Model Context Protocol

The agent-mediated commerce rails.

/api/mcp is a Streamable HTTP MCP server speaking JSON-RPC 2.0. Any Model-Context-Protocol-aware AI client (Claude in Cursor, ChatGPT connectors, agent frameworks) can connect, list tools, and call them.

Read tools (live): find_creators, get_creator, get_marketplace_offerings, submit_intent_brief. Anonymous. Public data only.

Write tools (preview): create_order opens a Stripe Checkout session for a buyer agent to hire a creator. Only available when the buyer-side feature flag MCP_WRITE_TIER_ENABLED is on. Creator-side opt-in: flip mcpDiscoverable on your profile.

POST /api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_order",
    "arguments": {
      "handle": "alice",
      "productId": "prod_…",
      "tierId": "professional",
      "addonIds": ["rush-3-day"]
    }
  }
}

→ { "content": [{ "type": "text",
     "text": "Checkout ready — @alice…\nhttps://checkout.stripe.com/…" }] }

Auth model. Read tools are anonymous, IP-rate-limited. The write tool initiates intent only — the actual payment happens in the buyer's authenticated browser session via the returned Stripe Checkout URL. The agent never handles card data.

Per-tool rate limits. find_creators 60/min, get_creator 120/min, get_marketplace_offerings 60/min, submit_intent_brief 5/min, create_order 10/min.

Build something

Get an API key. Ship today.

The Free tier is real. 30k requests a month, real webhooks, real OAuth (Sprint 1). Build, integrate, ship — with the rails of the Social Business Network.

Get an API key Back to developers home

Capabilities

Pillars + pricing

Manage keys

Issue + rotate

GraphQL

Spike — Sprint 1