Developers

Supergood API documentation

Supergood's site is static files on GitHub Pages. Two read endpoints live on that host. The fit-check form posts to a separate host. None of these calls need a key, a token, or an account. auth.md says the same thing in the short form agents look for.

The contract is openapi.json (OpenAPI 3.1.0, version 1.1.0). Prices are also in pricing.md.

This page is the official documentation for the Supergood API. The API has two read endpoints, pricing.json and services.json, and one endpoint that submits a fit check. The OpenAPI document is at https://supergood.solutions/openapi.json. The MCP server is at https://api.supergood.solutions/api/mcp and has three tools: get_pricing, get_services and submit_fit_check. The sandbox at https://api.supergood.solutions/api/sandbox/intake validates a fit check and sends no email. To submit a real fit check, POST to https://api.supergood.solutions/api/intake as described under Fit check below.

Reads

GET https://supergood.solutions/pricing.json

Returns the rate card as JSON. The intro call is free. The Sidekick Session is $500, credited in full to a Setup Sprint signed within 14 days. A Setup Sprint starts at $2,500. Sidekick Monthly starts at $900 per month plus 10-20% of measured gain over an agreed baseline, capped at 1.5x the retainer, with a 3-month minimum. For teams of 10 or more, the Quick Scan is $1,000, credited toward a build if you sign within 14 days, and a build starts at $4,000 per workflow. Same numbers as the pricing page.

GET https://supergood.solutions/services.json

Returns the five service pages and a one-line summary of each.

Both documents are the full list. They are not paged. A GET has no side effects.

curl -sS https://supergood.solutions/pricing.json
curl -sS https://supergood.solutions/services.json

Fit check

POST https://api.supergood.solutions/api/intake

Content-Type: application/json

This sends a real note to Ryan. One inquiry per person. Send an Idempotency-Key header (1 to 200 printable characters, no spaces, such as a UUID) and a retry of the same body within 24 hours does not send a second email. Without the header, a second POST with the same details can send a second email. The same key with a different body is 422 idempotency_conflict. Two requests with the same key at the same time give 409 idempotency_in_progress.

Required strings: name, email, handoff.

Also send paysForTools: Yes, Not sure, or No. It answers "Are you OK paying for the software and tools your workflows run on, on your own accounts?" The form and the MCP tool require it. The endpoint accepts a request without it.

Optional: companyName, role, currentState, teamSize, timeline, budget, source, elapsedMs.

Send company as "". That field is a honeypot on the form. The employer's name goes in companyName.

The page at /start/ waits 3 seconds after the first field is focused before it will submit. The function also drops a body whose elapsedMs is under 3000, and a body with a filled company field. It answers 200 {"ok":true} to both and sends no email.

Browser requests are allowed from https://supergood.solutions only. A request with another Origin gets 403. Server-side callers that send no Origin header are fine. Each IP gets 10 requests per 10 minutes. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy, and a 429 adds Retry-After.

The in-page tool submit_fit_check (WebMCP, document.modelContext.registerTool in /assets/agent-tools.js) waits 3 seconds and posts once. It is registered on the homepage, the fit-check page, and this page.

curl -sS -X POST https://api.supergood.solutions/api/intake \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","company":"","handoff":"A Monday report rebuilt from three spreadsheets.","paysForTools":"Yes","source":"docs-example","elapsedMs":3000}'

That command creates a real inquiry. Do not run it as a test. To test, use the sandbox below.

Sandbox

POST https://api.supergood.solutions/api/sandbox/intake takes the same body, runs the same validation and returns 200 {"ok":true,"sandbox":true}. It never sends an email. Each IP gets 30 requests per 10 minutes.

curl -sS -X POST https://api.supergood.solutions/api/sandbox/intake \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","handoff":"A Monday report rebuilt from three spreadsheets.","paysForTools":"Yes"}'

Errors

Every error is JSON: {"ok":false,"error":"<code>","message":"...","hint":"..."}. error is a stable code, message says what went wrong, and hint says how to fix it. The MCP tool returns the same fields.

StatusBodyWhat to do
200{"ok":true}Ryan has the note.
400error: jsonThe body was not a JSON object. Send JSON with Content-Type: application/json.
400error: requiredSend name, email, and handoff as non-empty strings.
400error: emailSend a complete email address, then one more POST.
400error: paysForToolsSend Yes, Not sure, or No.
400error: idempotency_keyThe Idempotency-Key header is not 1 to 200 printable characters. Fix it or leave it out.
403error: originBrowser request from an origin other than supergood.solutions. Call from a server, or use the form.
404error: not_foundNo such path on the intake host. GET / lists the endpoints.
405error: methodUse POST. A GET on this URL returns this error.
409error: idempotency_in_progressA request with this Idempotency-Key is still running. Wait a few seconds, then retry with the same key.
422error: idempotency_conflictThis Idempotency-Key was already used with a different body. Use a new key for a new inquiry.
429error: rate_limitedWait for Retry-After seconds and retry.
500error: serverThe endpoint is not configured. Try later.
502error: sendThe email was not delivered. Try again in a minute.

A missing path on api.supergood.solutions returns this JSON with status 404. A missing path on supergood.solutions returns the HTML 404 page. GitHub Pages does not return JSON for that.

Versioning

The API is version 1. Every intake response carries API-Version: 1. The document at /openapi.json is version 1.1.0: 1.1.0 added the Idempotency-Key header, the sandbox, the RateLimit headers and the JSON 404, and removed nothing. pricing.json and services.json are unpaged.

A breaking change ships as a new path, for example /api/v2/intake. The old path keeps working for at least 90 days after the change is announced on this page and in info.description of openapi.json. During those 90 days the old path returns Deprecation and Sunset headers. Adding a field to a response or an optional field to a request is not a breaking change. GitHub Pages cannot send those headers for the two JSON files on this host, so a change to them is announced here only.

MCP server

The intake project hosts an MCP server. Streamable HTTP, stateless, no key: https://api.supergood.solutions/api/mcp.

The server card is at /.well-known/mcp/server-card.json. The server accepts requests from any origin and rate limits by IP (60 requests a minute, with the same RateLimit headers). An unknown tool name returns a JSON-RPC -32602 error with a message that lists the tools. Bad arguments to a real tool return a tool result with isError: true.

curl -sS https://api.supergood.solutions/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What this host cannot do

This host is static, so the MCP server runs on the intake project, not here.

No OAuth server and no API keys. Publishing an authorization-server document would point at endpoints that are not there.

GitHub Pages does not let this repo set response headers. /.well-known/api-catalog is the RFC 9727 linkset, but the response will not carry Content-Type: application/linkset+json. There is also no HTTP Link header for the sitemap, the markdown twin, or the API catalog. The same URLs are linked from robots.txt, sitemap.xml, llms.txt, and the head of the homepage.

Where to look