# Grout Developer Docs

> Institution API for GroutApp, GroutCode and the Guardians portal. Base URL https://serverless.grout.app/v1. Auth: `Authorization: Bearer grt_live_…`.

## Documentation

- [Documentation](https://grout.app/developer/documentation/index.md): Learn how to connect an LMS or campus system to Grout — provisioning, SSO, exams, webhooks and more.
- [Why Grout?](https://grout.app/developer/documentation/why-grout.md): What you get by integrating with the Institution API instead of managing Grout by hand.
- [Quick Start](https://grout.app/developer/documentation/quickstart.md): Get an API key and make your first call in five minutes.
- [Institution Account](https://grout.app/developer/documentation/setting-up/institution-account.md): Register your institution on the portal, get approved, and find the Developers area.
- [Invite Developers](https://grout.app/developer/documentation/setting-up/developers.md): Give an engineer their own developer dashboard without sharing the admin account.
- [API Keys & Scopes](https://grout.app/developer/documentation/setting-up/api-keys.md): Create least-privilege keys, understand scopes, and rotate safely.
- [Authentication](https://grout.app/developer/documentation/setting-up/authentication.md): How requests are authenticated, what the errors mean, and how request ids help support.
- [Rate Limits & Errors](https://grout.app/developer/documentation/setting-up/rate-limits.md): Per-key limits, the headers that expose them, and how to back off.
- [Agent-Readable Surfaces](https://grout.app/developer/documentation/setting-up/agent-surfaces.md): Plain-text endpoints an AI agent can fetch to learn what Grout offers and how to call it.
- [Students](https://grout.app/developer/documentation/people/students.md): Provision students with a login email and license, map personal emails, suspend and reactivate.
- [Faculty](https://grout.app/developer/documentation/people/faculty.md): Provision teachers who author exams, own groups and grade submissions.
- [Groups](https://grout.app/developer/documentation/people/groups.md): Classes and sections. Exams are assigned to groups, not to individual students.
- [Licenses & Devices](https://grout.app/developer/documentation/people/licenses.md): Read expiry, extend or revoke licenses, and manage device seats per app.
- [SSO Launch (LMS)](https://grout.app/developer/documentation/people/sso.md): Put a student inside GroutApp or GroutCode from a button in your LMS, no one-time code.
- [Guardians](https://grout.app/developer/documentation/people/guardians.md): Invite parents to the Guardians portal and read their weekly reports.
- [Exams Overview](https://grout.app/developer/documentation/exams/overview.md): Create, publish and assign exams; read attempts, scores and analytics.
- [GroutCode Coding Exams](https://grout.app/developer/documentation/exams/groutcode.md): The code_spec format, starter and test files, and encrypted hidden tests with key custody.
- [Submissions & Grading](https://grout.app/developer/documentation/exams/submissions.md): Read submissions and attachments, grade or request resubmission, export results.
- [Proctoring & AI Policy](https://grout.app/developer/documentation/exams/proctoring.md): What the apps record during an exam, the event feed you can read, and how AI assistance is governed.
- [Alpha Learning](https://grout.app/developer/documentation/learning/alpha.md): Enroll students in mastery curricula, read progress, award points, publish leaderboards.
- [Merits & Coupons](https://grout.app/developer/documentation/learning/merits.md): Fund students' AI usage from an institution allowance, and request coupon batches.
- [Webhooks Overview](https://grout.app/developer/documentation/webhooks/overview.md): Register an HTTPS endpoint, choose events, and receive signed deliveries instead of polling.
- [Verify Signatures](https://grout.app/developer/documentation/webhooks/verify.md): Check X-Grout-Signature before trusting a delivery.
- [Event Catalogue](https://grout.app/developer/documentation/webhooks/events.md): Every webhook event type, when it fires, and what data it carries.
- [Retries & Replay](https://grout.app/developer/documentation/webhooks/retries.md): Delivery schedule, automatic disabling, the delivery log, and replaying from the portal or API.
- [LMS Integration](https://grout.app/developer/documentation/guides/lms-integration.md): Connect Moodle, Canvas or any LMS to GroutApp and GroutCode: roster sync, one-click SSO launch and gradebook write-back on one institution API.
- [Integration Best Practices](https://grout.app/developer/documentation/guides/integration-best-practices.md): Keys, idempotency, backoff, webhooks, secrets and monitoring: how to build an integration against the Grout Institution API that keeps working.
- [Moodle](https://grout.app/developer/documentation/guides/moodle.md): Roster sync, an "Open in GroutCode" button and gradebook write-back from Moodle.
- [Canvas](https://grout.app/developer/documentation/guides/canvas.md): Sync sections, launch GroutCode from a module item, and post scores to Canvas assignments.
- [Roster Sync](https://grout.app/developer/documentation/guides/roster-sync.md): A generic, LMS-agnostic recipe for keeping Grout people and groups in step with your SIS.
- [Gradebook Sync](https://grout.app/developer/documentation/guides/gradebook.md): Push exam results into your gradebook the moment they are graded.
- [FAQ](https://grout.app/developer/documentation/guides/faq.md): Short answers to the questions integrators ask first.

## API Reference

- [OpenAPI document](https://serverless.grout.app/v1/openapi.json): machine-readable spec for every endpoint
- [Swagger UI](https://serverless.grout.app/v1/docs): interactive explorer
- [Meta](https://grout.app/developer/api-reference/meta/): GET /me, GET /scopes
- [Institution](https://grout.app/developer/api-reference/institution/): GET /institution, GET /institution/config, PUT /institution/config
- [Students](https://grout.app/developer/api-reference/students/): GET /students, POST /students, POST /students/bulk, GET /students/{id}, PATCH /students/{id}, POST /students/{id}/suspend, POST /students/{id}/reactivate, GET /students/{id}/guardians, GET /students/{id}/exams
- [Faculty](https://grout.app/developer/api-reference/faculty/): GET /faculty, POST /faculty, GET /faculty/{id}, PATCH /faculty/{id}, GET /faculty/{id}/exams
- [Groups](https://grout.app/developer/api-reference/groups/): GET /groups, POST /groups, GET /groups/{id}, PATCH /groups/{id}, DELETE /groups/{id}, POST /groups/{id}/members, DELETE /groups/{id}/members/{studentId}
- [Licenses](https://grout.app/developer/api-reference/licenses/): GET /licenses, GET /licenses/summary, GET /licenses/{id}, POST /licenses/{id}/revoke, POST /licenses/{id}/extend, GET /licenses/{id}/devices, POST /licenses/{id}/devices/{seatId}/revoke
- [SSO](https://grout.app/developer/api-reference/sso/): POST /sso/tokens
- [Exams](https://grout.app/developer/api-reference/exams/): GET /exams, POST /exams, GET /exams/{id}, PATCH /exams/{id}, DELETE /exams/{id}, POST /exams/{id}/publish, POST /exams/{id}/close, GET /exams/{id}/assignments, POST /exams/{id}/assignments, DELETE /exams/{id}/assignments/{groupId}, GET /exams/{id}/attempts, GET /exams/{id}/analytics, GET /exams/{id}/scores, GET /exams/{id}/export.csv
- [Exams (GroutCode)](https://grout.app/developer/api-reference/exams-groutcode/): POST /exams/{id}/files, PUT /exams/{id}/code-secret, GET /exams/{id}/code-secret/status, POST /exams/{id}/code-secret/release
- [Submissions](https://grout.app/developer/api-reference/submissions/): GET /submissions, GET /submissions/{id}, GET /submissions/{id}/events, POST /submissions/{id}/grade, POST /submissions/{id}/void
- [Coupons](https://grout.app/developer/api-reference/coupons/): GET /coupons/batches, POST /coupons/batches, GET /coupons/batches/{id}, GET /coupons/redemptions
- [Merits](https://grout.app/developer/api-reference/merits/): GET /merits/allowance, GET /merits/wallets/{email}, POST /merits/credits, GET /merits/ledger
- [Guardians](https://grout.app/developer/api-reference/guardians/): GET /guardians, POST /guardians, POST /guardians/{id}/resend, DELETE /guardians/{id}, GET /guardians/reports
- [Alpha Learning](https://grout.app/developer/api-reference/alpha-learning/): GET /alpha/curricula, GET /alpha/enrollments, POST /alpha/enrollments, PATCH /alpha/enrollments/{id}, GET /alpha/students/{id}, GET /alpha/students/{id}/mastery, GET /alpha/students/{id}/points, POST /alpha/students/{id}/points, GET /alpha/leaderboard
- [Webhooks](https://grout.app/developer/api-reference/webhooks/): GET /webhooks/endpoints, POST /webhooks/endpoints, GET /webhooks/endpoints/{id}, PATCH /webhooks/endpoints/{id}, DELETE /webhooks/endpoints/{id}, POST /webhooks/endpoints/{id}/rotate-secret, POST /webhooks/endpoints/{id}/test, GET /webhooks/deliveries, GET /webhooks/deliveries/{id}, POST /webhooks/deliveries/{id}/replay
- [Events](https://grout.app/developer/api-reference/events/): GET /events, GET /events/types

## Agent surfaces

- [llms-full.txt](https://grout.app/developer/llms-full.txt): every page in one file
- [AGENTS.md](https://grout.app/developer/AGENTS.md): how an AI agent should work with the Grout API and these docs
- [SKILLS.md](https://grout.app/developer/SKILLS.md): task recipes (roster sync, gradebook, SSO button, webhooks) with request templates
- [Changelog](https://grout.app/developer/CHANGELOG.md)