Institution APIv2026-09-14
API Reference
All endpoints live under https://serverless.grout.app/v1 and are scoped to the institution that issued the key. Responses are JSON envelopes: { "success": true, "data": … } or { "success": false, "error": "<code>", "message": "…" }. List endpoints paginate with ?page&limit (limit ≤ 200) and return { items, page, limit, total, totalPages }. Every response carries X-Request-Id and rate-limit headers.
Interactive explorer: Swagger UI · machine-readable: openapi.json.
Authentication
curl https://serverless.grout.app/v1/me \
-H "Authorization: Bearer grt_live_YOUR_KEY"Create keys in the portal under Institution → Developers → API keys, or on the developer dashboard. See API Keys & Scopes.
Resources
Meta2 endpoints
- get
/me - get
/scopes
View reference
Institution3 endpoints
- get
/institution - get
/institution/config - put
/institution/config
View reference
Students9 endpoints
- get
/students - post
/students - post
/students/bulk
View reference
Faculty5 endpoints
- get
/faculty - post
/faculty - get
/faculty/{id}
View reference
Groups7 endpoints
- get
/groups - post
/groups - get
/groups/{id}
View reference
Licenses7 endpoints
- get
/licenses - get
/licenses/summary - get
/licenses/{id}
View reference
SSO1 endpoint
- post
/sso/tokens
View reference
Exams14 endpoints
- get
/exams - post
/exams - get
/exams/{id}
View reference
Exams (GroutCode)4 endpoints
- post
/exams/{id}/files - put
/exams/{id}/code-secret - get
/exams/{id}/code-secret/status
View reference
Submissions5 endpoints
- get
/submissions - get
/submissions/{id} - get
/submissions/{id}/events
View reference
Coupons4 endpoints
- get
/coupons/batches - post
/coupons/batches - get
/coupons/batches/{id}
View reference
Merits4 endpoints
- get
/merits/allowance - get
/merits/wallets/{email} - post
/merits/credits
View reference
Guardians5 endpoints
- get
/guardians - post
/guardians - post
/guardians/{id}/resend
View reference
Alpha Learning9 endpoints
- get
/alpha/curricula - get
/alpha/enrollments - post
/alpha/enrollments
View reference
Webhooks10 endpoints
- get
/webhooks/endpoints - post
/webhooks/endpoints - get
/webhooks/endpoints/{id}
View reference
Events2 endpoints
- get
/events - get
/events/types
View reference
Scopes
| Scope | Grants |
|---|---|
| students:read | List and read student accounts |
| students:write | Create, update, suspend student accounts |
| faculty:read | List and read faculty accounts |
| faculty:write | Create and update faculty accounts |
| groups:read | List groups and their members |
| groups:write | Create groups and manage membership |
| licenses:read | Read licenses, expiry and registered devices |
| licenses:write | Revoke or extend licenses, revoke devices |
| exams:read | List and read exams, assignments and analytics |
| exams:write | Create, update, publish, assign exams; manage GroutCode exam files |
| submissions:read | Read submissions, scores and proctoring event feeds |
| submissions:write | Grade, request resubmission, void submissions |
| coupons:read | Read coupon batches and redemptions |
| coupons:write | Request coupon batches |
| merits:read | Read merit wallet balances and ledgers |
| merits:write | Credit merits to institution accounts |
| guardians:read | Read guardian links and reports |
| guardians:write | Invite and remove guardians |
| alpha:read | Read Alpha Learning enrollments, mastery and points |
| alpha:write | Enroll students and award Alpha points |
| institution:read | Read institution profile and integration config |
| institution:write | Update integration config |
| webhooks:read | List webhook endpoints, deliveries and events |
| webhooks:write | Create and manage webhook endpoints, replay deliveries |
| sso:write | Mint single sign-on launch tokens for students and faculty |