{ "openapi": "3.1.0", "info": { "title": "PupilBot Agent API", "version": "1.0.0", "summary": "The public agent surface of PupilBot: an MCP server, its OAuth 2.1 flow, and the agent-readable files.", "description": "PupilBot turns study material a student supplies — photographed notes, a handout, or pages picked out of a PDF — into adaptive practice questions scheduled by spaced repetition. Through the MCP server at /mcp an agent can create a study from text, poll its processing status, list the user's studies, and read overall or per-topic mastery. Practice itself happens in the web app, the iPhone app, or the Telegram bot; the agent creates and reads. The /api/* routes are first-party and not described here.", "contact": { "email": "support@pupilbot.com", "url": "https://www.pupilbot.com/developers" } }, "servers": [ { "url": "https://www.pupilbot.com" } ], "externalDocs": { "url": "https://www.pupilbot.com/developers", "description": "PupilBot developer and agent documentation" }, "tags": [ { "name": "agent-files", "description": "Plain-text files written for AI agents and crawlers." }, { "name": "discovery", "description": "Pre-connection metadata documents for MCP clients." }, { "name": "oauth", "description": "OAuth 2.1 authorization server backing the MCP endpoint." }, { "name": "mcp", "description": "The Model Context Protocol server itself." }, { "name": "status", "description": "Service health." } ], "paths": { "/llms.txt": { "get": { "summary": "Agent brief", "description": "The llms.txt brief: what PupilBot is, when to use it, how an agent calls it, and what not to claim about it.", "operationId": "getLlmsTxt", "tags": [ "agent-files" ], "responses": { "200": { "description": "The brief, as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "summary": "Agent brief plus every page inlined", "description": "llms.txt concatenated with the full markdown twin of every public page, so a fetcher that reads one file reads the whole site.", "operationId": "getLlmsFullTxt", "tags": [ "agent-files" ], "responses": { "200": { "description": "The brief and every page twin, as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "summary": "This document", "description": "The OpenAPI 3.1 description of the public agent surface.", "operationId": "getOpenApi", "tags": [ "agent-files" ], "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp/server-card": { "get": { "summary": "MCP Server Card", "description": "The MCP Server Card (SEP-2127) for the PupilBot MCP server: its name, version, website, icon, and the Streamable HTTP remote with the protocol versions it supports.", "operationId": "getMcpServerCard", "tags": [ "discovery" ], "responses": { "200": { "description": "The server card.", "content": { "application/mcp-server-card+json": { "schema": { "type": "object" } } } } } } }, "/.well-known/ai-catalog.json": { "get": { "summary": "AI Catalog", "description": "The site-wide AI Catalog, the well-known URI the MCP Server Card extension reserves. It holds one entry, pointing at /mcp/server-card.", "operationId": "getAiCatalog", "tags": [ "discovery" ], "responses": { "200": { "description": "The catalog.", "content": { "application/ai-catalog+json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "Authorization server metadata (RFC 8414)", "description": "Names the authorization, token and registration endpoints, the response types, the grant types and the PKCE methods this server supports. Also served at /.well-known/oauth-authorization-server/mcp for clients that insert the resource path.", "operationId": "getAuthorizationServerMetadata", "tags": [ "oauth" ], "responses": { "200": { "description": "The authorization server metadata.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "summary": "Protected resource metadata (RFC 9728)", "description": "Names the MCP resource and the authorization server that protects it. This is the document a 401 from /mcp points at. Also served at /.well-known/oauth-protected-resource/mcp.", "operationId": "getProtectedResourceMetadata", "tags": [ "oauth" ], "responses": { "200": { "description": "The protected resource metadata.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/oauth/register": { "post": { "summary": "Dynamic client registration (RFC 7591)", "description": "Registers an OAuth client and returns its client_id. Open and unauthenticated, so it is rate limited per client IP. Redirect URIs must be HTTPS, or loopback HTTP.", "operationId": "registerOauthClient", "tags": [ "oauth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "redirect_uris" ], "properties": { "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } } }, "responses": { "201": { "description": "The registered client.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid registration request (for example a non-HTTPS remote redirect URI).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/oauth/authorize": { "get": { "summary": "Authorization endpoint", "description": "The consent page. The user signs in with their PupilBot account and approves the client; approval returns an authorization code to the registered redirect URI. PKCE with S256 is required.", "operationId": "authorize", "tags": [ "oauth" ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The consent page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/oauth/token": { "post": { "summary": "Token endpoint", "description": "Exchanges an authorization code for an access token, or rotates a refresh token. PKCE S256 is required on the code exchange: the code_verifier must hash to the code_challenge sent to /oauth/authorize. Refresh tokens rotate — the presented one is revoked.", "operationId": "token", "tags": [ "oauth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "title": "Authorization code exchange", "type": "object", "required": [ "grant_type", "client_id", "code", "code_verifier", "redirect_uri" ], "properties": { "grant_type": { "type": "string", "const": "authorization_code" }, "client_id": { "type": "string" }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" } } }, { "title": "Refresh token rotation", "type": "object", "required": [ "grant_type", "refresh_token" ], "properties": { "grant_type": { "type": "string", "const": "refresh_token" }, "client_id": { "type": "string" }, "refresh_token": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "The issued tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } } } } }, "400": { "description": "An OAuth error response (invalid_grant, invalid_request, …).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp": { "post": { "summary": "MCP endpoint (Streamable HTTP)", "description": "A stateless Streamable HTTP MCP server: one JSON-RPC 2.0 request per POST, one JSON response, no SSE stream and no session ids. It answers initialize, ping, tools/list and tools/call. The four tools are create_study (turn text into a study; questions generate in about a minute), get_study_status (poll a study until it is ready), list_studies (the user's studies, newest first) and get_mastery (overall mastery, or per-topic mastery for one study). JSON-RPC batching is not supported.", "operationId": "mcp", "tags": [ "mcp" ], "security": [ { "mcpOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "The JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "The request was a JSON-RPC notification, so there is no response body." }, "401": { "description": "Missing or invalid access token.", "headers": { "WWW-Authenticate": { "description": "Bearer challenge naming the protected resource metadata document at /.well-known/oauth-protected-resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/health": { "get": { "summary": "Health check", "description": "Answers 200 while the server is up. The only /api route in this document.", "operationId": "getHealth", "tags": [ "status" ], "responses": { "200": { "description": "The service is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } } }, "components": { "securitySchemes": { "mcpOAuth": { "type": "oauth2", "description": "OAuth 2.1 authorization code flow with PKCE (S256 required). Clients register themselves at /oauth/register.", "flows": { "authorizationCode": { "authorizationUrl": "https://www.pupilbot.com/oauth/authorize", "tokenUrl": "https://www.pupilbot.com/oauth/token", "refreshUrl": "https://www.pupilbot.com/oauth/token", "scopes": {} } } } } } }