# Educaplay API
- MCP server (Streamable HTTP; add it to your AI assistant as a custom connector, sign-in through OAuth): https://api.educaplay.com/v1/agent/mcp/
- Interactive API reference: https://api.educaplay.com/v1/docs/
- OpenAPI document: https://api.educaplay.com/v1/openapi.json
- This reference in Markdown: https://api.educaplay.com/llms.txt
Educaplay's public API for integrating third-party applications with the platform.
**Base URL.** Every endpoint is served under the versioned path `/v1/`. The unversioned URLs are still accepted as a legacy alias, but new integrations should always use `/v1/`.
**Authentication.** Every call takes an `Authorization: Bearer <token>` header; passing the token in the query string is no longer supported. There are two ways to obtain a token. `POST /v1/token/` exchanges the user's email and password for a token that expires after 24 hours, which suits integrations able to authenticate again on their own. When the user cannot hand a password over to the client — Model Context Protocol clients among them — they generate an application token from the application tokens screen of their Educaplay profile settings: it lasts a year, is revoked from that same screen, and grants exactly the same access as any other token. API access is included in the Academic and Commercial plans: on any other plan no token is issued, and requests made with a token issued earlier are answered with `403` and the code `license_required`.
**Model Context Protocol.** `POST /v1/agent/mcp/` is an MCP server (see the MCP tag) through which AI clients such as Claude, ChatGPT or Claude Code create, edit and publish the user's activities. It accepts the same Bearer tokens as the rest of the API, so a client where the user pastes a token works with an application token. Connectors that sign the user in themselves use the OAuth 2.1 flow instead (see the OAuth tag): authorization code with PKCE `S256`, public clients registered dynamically or identified by a client ID metadata document, and discovery through `/.well-known/oauth-protected-resource/v1/agent/mcp` and `/.well-known/oauth-authorization-server`. The access tokens issued that way last a year, have no refresh token and are listed and revoked from the same application tokens screen.
**Requests and responses.** Request bodies are sent as `application/x-www-form-urlencoded`. Successful responses follow the HAL convention (`application/hal+json`), and errors use the shape `{"error": {"code": 401, "messages": ["..."]}}`.
**Rate limiting.** Requests are counted per user over a fixed 60 second window, with a limit that depends on the subscription plan. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header.
## Authentication
Endpoints used to obtain credentials for the rest of the API.
### POST https://api.educaplay.com/v1/token/
Obtain a Bearer token
Exchanges HTTP Basic credentials for a Bearer token that can be used on every other API call.
Send the user's Educaplay email and password as an `Authorization: Basic base64(email:password)` header. No request body is expected.
## Guests
Endpoints to manage guest invitations. Guests are pre-registered students that the mentor can invite to play their activities and track results.
Free accounts can create a limited number of guests; Academic and Commercial subscriptions remove that limit.
### GET https://api.educaplay.com/v1/guests/
List the authenticated user's guests
Returns the list of guest invitations created by the authenticated user, with custom-named guests first and then alphabetically by name. Results are paginated.
### POST https://api.educaplay.com/v1/guests/
Create a new guest
Creates guest invitations owned by the authenticated user. Without `names`, creates one guest: if `name` is omitted or empty, an auto-generated placeholder name is used. With `names[]`, creates one guest per name (up to 500 per request) and responds with the list. `groups[]` tags the new guests with existing groups. Each guest carries its nine-letter access code, its direct access link and the content of its QR code.
### GET https://api.educaplay.com/v1/guests/groups/
List the authenticated user's guest groups
Groups work as tags: a guest may belong to several groups or to none. Each group comes with the number of guests tagged with it.
### POST https://api.educaplay.com/v1/guests/groups/
Create a guest group
Creates a group owned by the authenticated user. Tag guests with it through `groups[]` when creating them.
### PUT https://api.educaplay.com/v1/guests/groups/{groupId}/
Rename a guest group
### DELETE https://api.educaplay.com/v1/guests/groups/{groupId}/
Delete a guest group
Removes the tag from its guests. No guest is deleted.
### GET https://api.educaplay.com/v1/guests/{guestId}/
Retrieve a single guest
Returns the guest identified by `guestId`. The authenticated user must be the mentor that created it.
### PUT https://api.educaplay.com/v1/guests/{guestId}/
Update a guest's name
Updates the display name of the guest. An empty `name` is ignored and the previous value is kept.
### DELETE https://api.educaplay.com/v1/guests/{guestId}/
Delete a guest
Permanently deletes the guest and, if it had been linked to a player account through the access code, that linked player account too.
## Reports
Read-only reports about the results of your activities: games, players, errors, trends and multiplayer matches. Every endpoint accepts the same period filters and is limited to the retention window of your plan.
### GET https://api.educaplay.com/v1/reports/games/
Games report overview
Aggregated KPIs and charts for every activity owned by the authenticated user over the selected period.
### GET https://api.educaplay.com/v1/reports/games/list/
List activities with their results
Paginated list of the user's activities with the aggregated results of the period: number of plays, average accuracy, average time and rating. Pages hold up to 50 items.
### GET https://api.educaplay.com/v1/reports/games/{gameId}/
Results of a single activity
Detailed report of one activity: KPIs, charts and the most frequent wrong answers over the selected period.
### GET https://api.educaplay.com/v1/reports/games/{gameId}/ranking/
Ranking of an activity
Paginated ranking of the players who completed one activity, best score first. Pages hold up to 50 items.
### GET https://api.educaplay.com/v1/reports/players/kpis/
Players KPIs
Headline KPIs of the players report, together with the weekly sparklines that accompany them.
### GET https://api.educaplay.com/v1/reports/players/evolution/
Players evolution over time
Time series of activity and results for the selected players over the period.
### GET https://api.educaplay.com/v1/reports/players/distribution/
Distribution of players results
Distribution of scores and accuracy across the selected players.
### GET https://api.educaplay.com/v1/reports/players/heatmap/
Players activity heatmap
Activity heatmap by day and hour for the selected players.
### GET https://api.educaplay.com/v1/reports/players/recent/
Most recent plays
Paginated list of the most recent plays, newest first, including the activity, the player and every attempt. Pages hold up to 10 items and the window is limited to the last year.
### GET https://api.educaplay.com/v1/reports/players/errors/
Ranking of most frequent errors
Paginated ranking of the questions that players get wrong most often, plus the radar data comparing errors per activity. Pages hold up to 10 items.
### GET https://api.educaplay.com/v1/reports/players/errors/player/
Errors of a single player by activity
Errors made by one player across the activities that form the axes of the errors radar. Returns 404 when the player has no results in the period.
### GET https://api.educaplay.com/v1/reports/players/errors/detail/
Detail of the errors of a player
Detailed breakdown of the wrong answers of one player over the selected period.
### GET https://api.educaplay.com/v1/reports/players/list/
List players
Paginated list of the players who have completed the user's activities, with their aggregated results. Pages hold up to 50 items.
### GET https://api.educaplay.com/v1/reports/trends/
Trends report
Long-term trends of the account: KPIs, charts, activity heatmap, conversion funnel and generated insights.
### GET https://api.educaplay.com/v1/reports/matches/
Multiplayer matches overview
Aggregated results of the multiplayer matches hosted by the authenticated user over the selected period.
### GET https://api.educaplay.com/v1/reports/matches/{matchId}/
Results of a single match
Detailed results of one multiplayer match, including its participants and their scores.
## MCP
Model Context Protocol server: the tools through which AI clients read, create, edit and publish the activities of the authenticated user.
### POST https://api.educaplay.com/v1/agent/mcp/
MCP server endpoint (JSON-RPC 2.0 over Streamable HTTP)
Model Context Protocol server: a single endpoint through which AI clients (Claude, ChatGPT, Claude Code or any MCP client) read, create, edit and publish the activities of the authenticated user by calling tools.
**Transport.** Streamable HTTP, stateless: every JSON-RPC request or notification is its own `POST`, the answer is always one JSON object (no SSE streams), no session is ever issued (`Mcp-Session-Id` is ignored) and notifications are acknowledged with `202`. `GET` is not served.
**Protocol revisions.** Two eras are served on the same endpoint.
- Handshake revisions `2024-11-05`, `2025-03-26`, `2025-06-18` and `2025-11-25`: the client sends `initialize` and the server answers with the negotiated version (the newest it supports when the requested one is unknown), `serverInfo`, `capabilities` (`tools`) and `instructions`.
- Revision `2026-07-28`: no handshake. Each request declares `params._meta["io.modelcontextprotocol/protocolVersion"]` and mirrors it in the `MCP-Protocol-Version` header, together with `Mcp-Method` (the method) and, on `tools/call`, `Mcp-Name` (the tool name, Base64 sentinel encoding accepted). Results carry `resultType: "complete"`, `_meta["io.modelcontextprotocol/serverInfo"]` and, on lists, `ttlMs` and `cacheScope`. `server/discover` returns the supported versions, capabilities, identity and instructions and can be called under either era.
**Methods.** `server/discover`, `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list` and `prompts/list` (both empty). Anything else answers `-32601` (`404` under `2026-07-28`, `200` under the handshake revisions).
**Tools.** `tools/list` returns 26 tools, each with its `title`, its JSON Schema and `annotations` (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`):
- Discover: `list_activity_types`, `get_activity_schema`, `list_my_activities`, `get_activity`, `get_activity_content`, `get_publish_blockers`.
- Create and edit: `create_activity`, `set_activity_content`, `attach_video`, `update_activity`, `set_activity_audience`, `classify_activity`, `update_activity_settings`, `add_label`, `remove_label`.
- Media and audio: `list_my_media`, `illustrate_items`, `search_image_library`, `set_item_images`, `remove_item_media`, `set_item_text_visibility`, `describe_image`, `generate_field_audio`.
- Publication and visibility: `publish_activity`, `unpublish_activity`, `set_activity_privacy`.
Every tool answers a JSON text, `{"ok": true, ...}` or `{"ok": false, "error": "<code>", ...}`, and `isError` mirrors `ok`. Tools that write or publish execute immediately: asking the user for confirmation is the client's job, which is what `destructiveHint` is for. Calls are independent of each other (there is no server-side conversation); the image catalogue returned by `list_my_media` and `search_image_library` stays valid for one hour so that `set_item_images` and `describe_image` can refer to it from later requests.
**Authentication.** Any Bearer token of this API: an application token generated from the profile settings (for clients where the user pastes a token, for example `claude mcp add --transport http educaplay <this URL> --header "Authorization: Bearer <token>"`), or an access token obtained through the OAuth 2.1 flow described under the OAuth tag (for connectors that sign the user in, such as the Claude or ChatGPT connector settings, where only this URL is needed). Both grant exactly the same access as any other token of the API.
**Quotas.** Calls count against the API rate limit of the plan like any other request. `describe_image` spends the AI budget the user shares with the site's assistant, the audio tools spend the text to speech quota of the plan, and publishing is subject to the limits of the plan, which come back as `blockers`.
## OAuth
OAuth 2.1 authorization for MCP connectors: discovery documents, dynamic client registration and token exchange. The authorization page itself is served by the main site at `/oauth/authorize/`.
### GET https://api.educaplay.com/.well-known/oauth-protected-resource/v1/agent/mcp
Protected resource metadata (RFC 9728)
Discovery document of the MCP server as an OAuth 2.1 protected resource. MCP clients fetch it from the URL announced in the `WWW-Authenticate` header of a `401` answer of the MCP endpoint, or directly at this path. It names the authorization server (this same API) and the supported scopes.
### GET https://api.educaplay.com/.well-known/oauth-authorization-server
Authorization server metadata (RFC 8414)
Describes the authorization server: the authorization page on the main site, the token and registration endpoints of this API, the `code` response type, the `authorization_code` grant, PKCE `S256`, public clients only (`token_endpoint_auth_methods_supported: ["none"]`) and support for client ID metadata documents, so a client that publishes its metadata at an HTTPS URL can use that URL as `client_id` without registering.
### POST https://api.educaplay.com/v1/oauth/register/
Dynamic client registration (RFC 7591)
Registers a public client and returns its `client_id`. The identifier is self-contained and signed, so nothing is stored on the server: it encodes the registered redirect URIs and the client name, and the authorization page checks every request against them. Clients that publish a client ID metadata document do not need this endpoint.
### POST https://api.educaplay.com/v1/oauth/token/
Token endpoint (authorization code with PKCE)
Exchanges the authorization code obtained from `/oauth/authorize/` on the main site for an access token. The code is single use, bound to the `client_id` and `redirect_uri` of the authorization request, and verified against the PKCE `code_verifier`. The access token is a regular Bearer token of this API: it lasts a year, there is no refresh token, and the user can see and revoke it from the application tokens screen of their profile.