# Agent-Readable Surfaces

> Plain-text endpoints an AI agent can fetch to learn what Grout offers and how to call it.

Canonical: https://grout.app/developer/documentation/setting-up/agent-surfaces/

These docs are written for people and for coding agents. Every page has a markdown twin, and there is an index an agent can fetch first.

| URL | What it is |
|---|---|
| [/developer/llms.txt](/developer/llms.txt) | Index of every page with a one-line summary, plus API reference and agent files |
| [/developer/llms-full.txt](/developer/llms-full.txt) | Every documentation page concatenated into one file |
| `/developer/documentation/<slug>.md` | The raw markdown of any page — add `.md` to the path |
| [/developer/AGENTS.md](/developer/AGENTS.md) | How an agent should work with the Grout API and this docs site |
| [/developer/SKILLS.md](/developer/SKILLS.md) | Task recipes with request templates: roster sync, gradebook, webhooks, exams, exams |
| [/developer/openapi-v1.json](/developer/openapi-v1.json) | Vendored OpenAPI 3.1 document (live copy at `serverless.grout.app/v1/openapi.json`) |
| [/developer/CHANGELOG.md](/developer/CHANGELOG.md) | Dated changes |

## Suggested agent workflow

1. Fetch `/developer/llms.txt` and pick the pages relevant to the task.
2. Read `/developer/SKILLS.md` for a matching recipe; each recipe lists scopes, endpoints and a request template.
3. Fetch `/developer/openapi-v1.json` when you need exact parameter names.
4. Call `GET /v1/me` first to confirm the key's scopes before doing any writes.
5. Emit `X-Request-Id` values in your logs and error messages.

## Using the API from an agent

```bash
# Discover
curl -s https://grout.app/developer/llms.txt
# Confirm access
curl -s https://serverless.grout.app/v1/me -H "Authorization: Bearer $GROUT_API_KEY"
# Do the task (example: provision one student)
curl -s -X POST https://serverless.grout.app/v1/students \
  -H "Authorization: Bearer $GROUT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"full_name":"Asha Rao","student_id":"S-0142","personal_email":"asha@example.com"}'
```

:::note
Keys are institution-wide. An agent operating with a broad key should confirm destructive actions (suspend, revoke, void, delete) with a human first. `SKILLS.md` marks those recipes accordingly.
:::