Your lesson. Ready to play.

Quickstart

Request developer access in Account → Developer. Once approved, create a key and save it in your server environment as STUDYQUEST_API_KEY. Then send your first lesson:

curl --max-time 150 "https://jepbczthrhzznwzxrzoz.supabase.co/functions/v1/developer-api/v1/study-sets" \
  -H "Authorization: Bearer $STUDYQUEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: biology-lesson-01-v1" \
  -d '{
    "name": "Biology · Photosynthesis",
    "content": "Plants use sunlight to convert carbon dioxide and water into glucose and oxygen. Chlorophyll absorbs light in the chloroplasts. Glucose stores chemical energy that the plant uses for growth.",
    "question_count": 5,
    "language": "en"
  }'

A new generation returns 201 once the set is saved. Allow up to 150 seconds. The response contains a generation ID, a study-set ID and a private play link:

{
  "data": {
    "id": "<generation-uuid>",
    "status": "succeeded",
    "study_set_id": "<study-set-uuid>",
    "error_code": null,
    "play_url": "https://studyquest.app/study-sets/<study-set-uuid>/play",
    "created_at": "2026-10-27T12:00:00Z"
  },
  "replayed": false
}

The play link requires the owning StudyQuest account. It does not publish your material or give access to another account. The set also appears automatically in Study Library.

PDF and Word lessons

V1 accepts extracted text as JSON. The downloadable Python uploader reads TXT, PDF and DOCX, checks the content limit, and sends the text. Scanned PDFs need OCR first. There is no binary upload or URL-fetch endpoint in this beta.

Connect ChatGPT or Claude

Add StudyQuest as a remote MCP connection using OAuth and the URL below. Sign in to StudyQuest and review the permissions. Directory listings are subject to platform approval; use a custom connection while review is pending.

https://www.studyquest.app/mcp

Connected-app access is included in an active StudyQuest subscription, with 50 saved study sets per UTC month shared between ChatGPT and Claude. There is no fixed question-count limit; the full MCP request must fit within 256,000 bytes. Developer access is separate. No automatic overage charges apply.

Ask ChatGPT or Claude to write questions from material you provide. The assistant sends the complete questions to StudyQuest, which validates their format, saves the private set and immediately returns a “Play in StudyQuest” link. StudyQuest makes no AI call and does not verify factual accuracy in this flow. Open the link while signed in to the same account to choose a game.

OAuth grants can read your study sets, questions and subjects; with write permission they can create sets and organize them. They cannot manage billing, passwords or developer API keys. Account connections expire after 90 days; reconnect when prompted.

Manage your usage and disconnect apps in Account → Connected apps. Disconnecting stops future access; it does not remove content already retrieved by the other app. Review the privacy policy before connecting.

Save questions with MCP v2

Call studyquest_create_study_set with complete questions, four distinct answer options and a zero-based correct-answer index. More than 20 questions are supported. Optional fields are language, subject_id and a topic per question. Raw lesson text and question_count are no longer accepted. Refresh your client’s tool list after upgrading from MCP v1.

{
  "name": "Photosynthesis",
  "questions": [{
    "question": "What does chlorophyll absorb?",
    "options": ["Light", "Sound", "Soil", "Glucose"],
    "correct": 0,
    "topic": "Biology"
  }],
  "language": "en",
  "idempotency_key": "photosynthesis-authored-v1"
}

The result contains data.study_set_id, data.question_count and data.play_url. There is no generation job. studyquest_get_usage returns sets_used and sets_limit. The REST API below still offers StudyQuest AI generation and retains its separate generation limits.

Connection details

Streamable HTTP, OAuth authorization code with S256 PKCE, public clients, dynamic client registration, rotating refresh tokens and RFC 9207 issuer identification. Request the resource https://www.studyquest.app/mcp and scopes study:read and study:write. Access tokens expire after ten minutes. Refresh tokens rotate and expire after thirty days of inactivity, subject to the grant’s ninety-day lifetime. Discovery is available at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

Developer MCP with API keys

Connect an AI assistant to your StudyQuest library using the Model Context Protocol. The server uses Streamable HTTP and the same API key, developer approval, scopes and monthly allowance as the REST API.

MCP server URL

https://jepbczthrhzznwzxrzoz.supabase.co/functions/v1/studyquest-mcp

In your MCP client, add this remote server URL and an Authorization header containing Bearer YOUR_STUDYQUEST_API_KEY. Create the key in Account → Developer. Choose read-only access to search and read your library; use a read/write key to create or organize sets.

{
  "url": "https://jepbczthrhzznwzxrzoz.supabase.co/functions/v1/studyquest-mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STUDYQUEST_API_KEY"
  }
}

This is a connection example; the surrounding configuration format varies by client. Replace the placeholder locally and keep it private. This beta supports clients that accept custom bearer headers. For ChatGPT and Claude, use the OAuth connection above. Legacy SSE-only clients are not supported.

Codex configuration

Make STUDYQUEST_API_KEY available in the environment that starts Codex, then add this to your Codex configuration. bearer_token_env_var is the variable’s name, not the key itself.

[mcp_servers.studyquest]
url = "https://jepbczthrhzznwzxrzoz.supabase.co/functions/v1/studyquest-mcp"
bearer_token_env_var = "STUDYQUEST_API_KEY"
tool_timeout_sec = 30

What your assistant can do

Try: “Find my biology study sets” or “Create a 10-question study set from these notes and put it under Biology.” Creating a set uses one set from your monthly allowance. Reads and subject changes do not use that allowance.

MCP v2 saves supplied questions immediately without polling. The idempotency_key argument is required: reuse it with unchanged input after a timeout. MCP saves have their own idempotency records, separate from REST AI generation. Tool results include untrusted_content: true because lesson text and names are data, not instructions for your assistant. Revoking the API key or suspending developer access blocks further MCP requests.

Authentication

Authorization: Bearer sq_dev_…

API keys are shown only once. StudyQuest stores a SHA-256 hash, not the usable key. You can have five active keys, each valid for 90 days. Revoke a key in your account to stop new requests immediately. Keys are private server credentials: never put them in browser code, a mobile app bundle, a URL or a public repository.

• study:read — read your sets, questions, subjects, generations and usage.
• study:write — create sets and subjects, rename sets and change their subject.

A regular Premium subscription alone does not enable the API. Developer access must be active and unexpired. Suspending access blocks every key.

Study sets

Base URL

https://jepbczthrhzznwzxrzoz.supabase.co/functions/v1/developer-api/v1

POST requires name (1–200 characters), content (50–40,000 characters), and an Idempotency-Key header (8–128 characters). Optional: question_count (1–20, default 10), language (default en), and subject_id (your subject UUID).

The generator may return fewer questions when the material cannot support the requested count. Questions have question, four options, and a zero-based correct index.

GET /study-sets?limit=20&offset=0&q=biology
GET /study-sets?subject_id=<subject-uuid>
GET /study-sets?subject_id=none

PATCH /study-sets/<study-set-uuid>
{ "name": "Biology lesson 2", "subject_id": null }

Lists return data, has_more and next_offset. Pass next_offset to fetch the next page. The maximum page size is 100. Name search is case-insensitive and matches literal text.

Subjects

Subjects belong to your account and work in both the API and Study Library. Create one, then use its ID when creating or updating a set. Names are unique within your account, ignoring case and surrounding spaces.

POST /subjects
{ "name": "Biology" }

GET /subjects
// { "data": [{ "id": "<subject-uuid>", "name": "Biology", ... }] }

In Study Library, search by name, filter by subject, and assign each set to a subject. Use null to remove a set’s subject. Subject renaming/deletion is not part of the v1 API.

Usage & limits

• Approved beta accounts start with 100 successful generations per UTC calendar month, unless a different limit is agreed.
• One generation creates one set with up to 20 questions. Reading sets and changing subjects do not consume generation credits.
• 60 requests per minute per account, shared across all keys. At most two generations can run at once.
• Generation reserves one credit. Handled failures return it. Interrupted work is recovered on a status check or the next generation request after five minutes.
• At most 40,000 text characters and 256,000 request bytes. Split long lessons before submitting them.
• Hard limits: no automatic overage charges.

GET /usage
// { "period": "2026-10-01", "generations_used": 12,
//   "generations_limit": 100 }

Usage includes in-progress reservations. Account → Developer shows the same allowance and your access expiry date.

Errors & retries

Every response includes X-Request-Id. Errors use a stable code and a readable message:

{ "error": {
  "code": "quota_exceeded",
  "message": "Monthly generation limit reached. It resets on the first day of the next UTC month.",
  "request_id": "<request-uuid>"
} }

• 400 / 413 / 415 — invalid input, oversized body or unsupported content type.
• 401 / 403 — invalid key, missing scope or inactive developer access.
• 404 — endpoint, set, subject or generation not found in your account.
• 409 — duplicate subject name or idempotency key used with different input.
• 422 — material could not support any questions.
• 429 — rate, concurrency or monthly limit. For rate/concurrency limits, wait at least Retry-After seconds; a monthly limit needs a reset or an agreed allowance change.
• 500 / 502 — saving or generation failed.

On a timeout or lost response, repeat the same POST with the same idempotency key and input. A replay returns the original result without another generation charge. It returns 202 while processing, or 200 with the final status. Check data.status: a replay of a failed job stays failed. After confirming failure, use a new key for a deliberate new attempt. Use GET /generations/{id} to poll an existing job.

Idempotency records are retained for the lifetime of the developer account. Use a distinct key for each lesson revision. If you delete a generated set, its old key will not recreate it.

Support

For connection, account or generation issues, email hello@studyquest.app. Include the request ID and the error message, but never include passwords, API keys or OAuth tokens.

Developer access

The first release is an approval-based beta with an explicit expiry date and allowance. Developer is planned as an add-on to a StudyQuest subscription. Beta approval does not start a paid subscription, and no add-on checkout is enabled yet.

Request access from your account and describe your integration. We will agree on access and limits before enabling it. Commercial redistribution, multi-account integrations and higher volume need a separate agreement.