Study · Muse connector

Intoola Study connector for Muse

API documentation · Version 1.0 · Last Updated: September 19, 2026

Overview

Intoola Study turns a student's own course materials into personalized study resources. The Muse connector lets a Muse user ask Muse to create a practice exam, flashcards, or a study guide from study material they provide, for example “Create a practice exam from these lecture notes using Intoola.”

Requirements. The user needs an Intoola account (sign in with Google) and an active paid Intoola Study subscription. The subscription is verified on Intoola's servers on every request. Without one, the API returns HTTP 402 with subscription_required and a link to subscribe. Subscribing is done on intoola.com, not inside Muse.

The connector only works with text sent in the request. It cannot read a user's saved materials, Google Classroom, Google Drive, or Canvas/Brightspace data. See the Privacy Policy (Section 3.15) for how data is handled.

Endpoints

Purpose	URL
API base URL	`https://socrian.socrianstudyassistant.workers.dev`
OpenAPI 3.1 description	`/muse/v1/openapi.json`
OAuth server metadata (RFC 8414)	`/.well-known/oauth-authorization-server`
Authorization	`GET /oauth/authorize`
Token	`POST /oauth/token`
Revocation (RFC 7009)	`POST /oauth/revoke`
Subscription status	`GET /muse/v1/status`
Actions	`POST /muse/v1/actions/create_practice_exam`, `create_flashcards`, `create_study_guide`

Authentication

OAuth 2.0 authorization code flow with PKCE (S256, required). Intoola never handles a password: the user signs in with Google on an Intoola-hosted page and then approves the connection.

Authorization request: response_type=code, client_id, redirect_uri (must exactly match a registered https URI), state, code_challenge, code_challenge_method=S256, optional scope.
Token request: grant_type=authorization_code with code, code_verifier, and redirect_uri; client authentication by HTTP Basic or client_secret in the body.
Tokens: opaque bearer access token (1 hour) and refresh token (30 days). Refresh tokens rotate on each use; replaying a rotated token revokes the grant. Send Authorization: Bearer <access_token> on API calls.
Scopes: study:generate (create practice exams, flashcards, and study guides) and account:status (see whether the subscription is active).

Actions

All actions take a JSON body and return JSON. Unknown fields are rejected. An optional Idempotency-Key header (8–128 characters) makes retries safe: a repeated request replays the first result instead of generating again.

Action	Parameters	Returns
`create_practice_exam`	`material_text` (required, 40–50,000 chars); `num_questions` 5–25 (default 20); `difficulty` easy \| medium \| hard \| mixed; `additional_instructions` (max 500 chars)	`exam.questions[]` with `type`, `question`, optional `choices[]`, and `answer_and_explanation`
`create_flashcards`	`material_text`; `num_flashcards` 5–40 (default 25); `additional_instructions`	`flashcards.cards[]` with `question` and `answer`
`create_study_guide`	`material_text`; `additional_instructions`	`study_guide.content` (Markdown)

Example request:

POST /muse/v1/actions/create_flashcards
Authorization: Bearer <access_token>
Content-Type: application/json

{ "material_text": "Photosynthesis converts light energy into chemical energy ...", "num_flashcards": 10 }

Example response:

{
  "action": "create_flashcards",
  "flashcards": { "card_count": 10, "cards": [ { "number": 1, "question": "...", "answer": "..." } ] },
  "truncated": false,
  "generated_by": "Intoola Study",
  "request_id": "..."
}

Errors

Errors use the shape { "error": { "code", "message" }, "request_id" }.

HTTP	Code	Meaning
400	`invalid_parameters`	A parameter is missing, out of range, or unknown; `error.details` lists each field.
401	`missing_authorization`, `invalid_token`	No token, or the token is invalid, expired, or revoked. Refresh or re-link.
402	`subscription_required`	No active Intoola Study subscription. `error.upgrade_url` points to the subscribe page.
403	`insufficient_scope`	The authorization does not include the required scope.
409 / 422	`request_in_progress`, `idempotency_key_reuse`	Duplicate request in flight, or an Idempotency-Key reused with different parameters.
413	`payload_too_large`	The request body exceeds 400 KB.
429	`rate_limited`, `daily_limit_reached`, `daily_usage_limit_reached`	Usage limits; see `Retry-After`.
502 / 503 / 504	`generation_failed`, `service_unavailable`, `upstream_timeout`	Temporary problem; retry later.

Limits

Per user: 6 requests per minute and 60 requests per day.
A daily AI-usage limit per user, shared with the Intoola website and Chrome extension (using Muse does not add extra allowance).
Up to 50,000 characters of study material per request.

Support and legal

Questions or issues: info@intoola.com. Privacy Policy · Terms of Service · About Intoola Study.