Developers

Novari Study API documentation

Everything an engineer or an AI agent needs to read Novari Study's public facts and, with a student's consent, their study state.

Quick start

Fetch the contract: /openapi.json (OpenAPI 3.1). The API base URL is https://api.novaristudy.site.
Check the service: curl https://api.novaristudy.site/api/health (no authentication).
Call a student endpoint with their access token: curl -H "Authorization: Bearer $TOKEN" https://api.novaristudy.site/api/dashboard/up-next

Authentication

Endpoints that return student data need a Supabase Auth access token for the signed-in student, sent as Authorization: Bearer <token>. Metadata for clients is published as RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource. There is no separate API-key product yet: every call acts as one student, and a student always signs in themselves.

Scopes

Request the narrowest scope that does the job. Scope names are declared in the OpenAPI security scheme and in the protected-resource metadata; today the API authorises by the student's session and does not yet refuse a token for lacking a scope.

profile:read: Read the signed-in student's profile and plan tier.
study:read: Read study state: daily queue, up-next mission, mastery and planner sessions.
study:write: Create or change study content: documents, flashcards, quizzes and plans.

Errors

Errors are JSON. Gateway errors look like {"error":{"code":"wrong_host","message":"...","hint":"...","status":404}}; some API routes return {"error":"...","code":"MISSING_BEARER_TOKEN"}. Both carry a machine-readable code; the hint says how to fix the request. Authentication failures are HTTP 401, throttling is HTTP 429.

Rate limits

API responses carry the IETF RateLimit and RateLimit-Policy headers (the default policy is 800 requests per 900 seconds per user or IP). A throttled call returns HTTP 429 with Retry-After in seconds; wait that long before retrying.

Free tier and sandbox

Novari Starter is free with no card required, so you can create a student account and call the API against your own data at no cost. See pricing. A separate sandbox environment and self-serve API keys are not available yet; email support@novaristudy.site if you need either.

MCP server

A Model Context Protocol server (Streamable HTTP, no authentication, read-only) is at https://novaristudy.site/mcp, described by /.well-known/mcp/manifest.json. Tools: get_product_overview, get_pricing, list_exam_boards.

For agents

Read /llms.txt for a summary and when to use Novari. The agent skill is at /.well-known/agent-skills/index.json. Any page can be fetched as Markdown with Accept: text/markdown. The machine-readable resource list is the /.well-known/api-catalog linkset.

Support

Questions and bug reports: contact us. Terms are in the terms of service.