---
title: "Developers and AI agents"
description: "The goodtogrid API, MCP server and agent sign-in. Read the site as JSON or Markdown with no key, and send a project brief once a person approves it."
canonical: "https://goodtogrid.com/developers"
updated: "2026-10-02"
---

# Developers and AI agents

> The goodtogrid API, MCP server and agent sign-in. Read the site as JSON or Markdown with no key, and send a project brief once a person approves it.

URL: https://goodtogrid.com/developers · Updated: 2026-10-02

The goodtogrid site works as an API too. Agents and developers can search it, read every page and case study, and help a person send the studio a project brief. Reads need no key, no sign-up and no payment.

## Quickstart
Search the site, list the case studies, and read a page as Markdown:

```sh
curl 'https://goodtogrid.com/api/v1/search?q=clinic'
curl 'https://goodtogrid.com/api/v1/case-studies?service=mobile'
curl -H 'Accept: text/markdown' https://goodtogrid.com/about
```

Or connect an MCP client to `https://goodtogrid.com/mcp` (Streamable HTTP, no sign-in for reads). Its tools are `search_site`, `read_page`, `list_case_studies`, `get_studio_info`, `estimate_project_cost`, `prepare_project_brief` and `send_project_brief`. For the docs alone, `https://goodtogrid.com/mcp/docs` serves `search_site` and `read_page`.

## Ways in
- **REST API** at `https://goodtogrid.com/api/v1`, described by [openapi.json](https://goodtogrid.com/openapi.json).
- **MCP servers**: the product server at `https://goodtogrid.com/mcp` ([server card](https://goodtogrid.com/.well-known/mcp/server-card.json)) and the read-only docs server at `https://goodtogrid.com/mcp/docs` ([server card](https://goodtogrid.com/.well-known/mcp/docs-server-card.json)).
- **A2A agent** at `https://goodtogrid.com/a2a`, described by its [agent card](https://goodtogrid.com/.well-known/agent-card.json).
- **NLWeb** at `https://goodtogrid.com/ask?query=…`, for natural-language questions, with streaming on request.
- **Markdown**: add `.md` to any page URL, or send `Accept: text/markdown`. The index is [llms.txt](https://goodtogrid.com/llms.txt), and the developer docs alone are [developers/llms.txt](https://goodtogrid.com/developers/llms.txt).
- **Structured data**: every page's schema.org data in one [JSON Lines feed](https://goodtogrid.com/feeds/schema.jsonl), listed in the [schema map](https://goodtogrid.com/schemamap.xml).
- **Catalogs** listing all of the above: [ai-catalog.json](https://goodtogrid.com/.well-known/ai-catalog.json) and the [API catalog](https://goodtogrid.com/.well-known/api-catalog).

## Get a key
Sending a brief needs an access token with the `brief:write` scope. You can get one yourself, without emailing anyone, but a person always has to approve it:

- **Agents without a browser:** register with `POST /agent/identity` and `{"type": "anonymous"}`. That returns a token for reading straight away. To send briefs, start the claim ceremony: the person opens a goodtogrid link, types the 6-digit code you give them and passes a quick human check. The steps are in [auth.md](https://goodtogrid.com/auth.md).
- **Apps acting for a person:** use OAuth 2.0 authorization code with PKCE (S256). Register at `/oauth/register`, or use a client ID metadata document. The metadata is at [/.well-known/oauth-authorization-server](https://goodtogrid.com/.well-known/oauth-authorization-server).

Scopes are `content:read` (everything you can already read) and `brief:write` (send a brief to the studio's inbox). The site has no user accounts, and a brief only ever goes to the studio.

## Sandbox
`https://goodtogrid.com/api/v1/sandbox` is the same API with no token needed. Its reads return the real data. `POST /api/v1/sandbox/briefs` checks a brief and answers the same `202` as production, with `"status": "dry_run"`, but nothing is ever sent. Build the whole flow there first:

```sh
curl -X POST https://goodtogrid.com/api/v1/sandbox/briefs -H 'Content-Type: application/json' \
  -d '{"name":"Kai","email":"kai@example.com","services":["Web development"],"message":"A booking site for a small clinic."}'
```

With a real token, `?dry_run=true` on `POST /api/v1/briefs` does the same, and so does `dry_run` on the MCP tool `send_project_brief`.

## Pricing
The API, both MCP servers and the sandbox are free and need no key. Projects are priced by scope: [pricing.md](https://goodtogrid.com/pricing.md) lists the price bands for each kind of project, in US dollars, and the [cost guides](https://goodtogrid.com/cost) explain what moves a project between bands. The MCP tool `estimate_project_cost` returns the same bands.

## Limits, errors and versions
- Reads: 120 requests a minute per IP. Briefs: 5 a minute. Every response carries `RateLimit-Policy`, and a `429` carries `Retry-After`.
- Errors are `application/problem+json` with a machine-readable `code` and a `hint` that says what to do next.
- `POST /api/v1/batch` runs up to 20 reads in one request.
- Lists use cursor pagination: pass `next_cursor` back as `cursor`.
- `POST /api/v1/briefs` takes an `Idempotency-Key`, answers `202 Accepted` with a `Location` to poll, and never sends the same brief twice for one key.
- The major version is in the path (`/api/v1`), and every response carries `API-Version` and a `Link` to the [versioning policy](https://goodtogrid.com/agents.md#versioning). Breaking changes ship as a new path. A version being retired answers with `Deprecation` and `Sunset` headers for at least 90 days first.

## Rules for agents
Quote facts and prices from the pages; cost guides give ranges, and the studio quotes after a call. Case studies marked "Studio concept" are self-initiated work, not client work. Never send a brief the person hasn't seen and approved. Questions go to hello@goodtogrid.com.