# Success Magis Developer Resources

Success Magis publishes a small read-only HTTP API and a set of machine-readable files so that agents, crawlers and scripts can work with the platform without scraping HTML. Everything listed here is open: there are no API keys to request, no sign-up, and no write access.

## OpenAPI specification

- Specification: https://api.successmagis.live/api/openapi.json
- Versioned base URL: https://api.successmagis.live/api/v1
- Mirror on this site: https://www.successmagis.live/openapi.json
- API catalog (RFC 9727): https://api.successmagis.live/.well-known/api-catalog
- The document is OpenAPI 3.1. Every operation carries a unique operationId, a description, typed parameters and a response schema, so it can be loaded directly into an LLM function-calling tool definition.

## Public endpoints

Base URL: https://api.successmagis.live/api

- GET /health - service status, uptime and version.
- GET /stats/public - aggregate platform counters.
- GET /stats/star-performer - the current top-performing student.
- GET /questions/categories - classes that have quiz questions available.
- GET /questions/chapters - chapters available, optionally filtered by class.
- GET /questions/stats - how many quiz questions exist.
- GET /videos/{id} - metadata for one lecture, so links can be shared.

## What is not public

Anything belonging to a student stays behind a bearer token: quiz attempts, contest submissions, AI chat history, profiles and every administrative route. Those endpoints are deliberately absent from the specification and no tokens are issued to third parties. Please do not attempt to enumerate them.

## Authentication

The endpoints listed above need no authentication at all. Send a plain GET request with no headers and you get JSON back. There is no API key to register for and no OAuth flow to complete.

Everything else on the platform uses a bearer token: sign in as a student, receive a JWT, and send it as "Authorization: Bearer <token>". Those routes serve one student their own data and are not part of this public surface. Tokens are issued only to people signing in to the product, never to third parties, and a password reset invalidates every token that user holds.

## Example requests

Check the service is up:

curl https://api.successmagis.live/api/v1/health

Fetch the current top performers:

curl https://api.successmagis.live/api/v1/stats/star-performer

Read the platform counters:

curl https://api.successmagis.live/api/v1/stats/public

List the chapters that have questions for Class 10:

curl "https://api.successmagis.live/api/v1/questions/chapters?class=10"

Load the specification into a tool:

curl https://api.successmagis.live/api/openapi.json

A successful response looks like this:

{ "success": true, "count": 2, "leaderboard": [ { "_id": "...", "name": "...", "studentClass": "12", "totalXP": 1450 } ] }

A failure looks like this:

{ "success": false, "message": "No route matches GET /api/nope", "error": { "code": "not_found", "hint": "...", "status": 404, "path": "/api/nope", "documentation": "https://api.successmagis.live/api/openapi.json" } }

## Versioning

Major versions live in the URL path. Use https://api.successmagis.live/api/v1 to pin version 1. The unversioned https://api.successmagis.live/api base always tracks the current major version, so pin the versioned path if you want stability. Every response carries an API-Version header naming the major version that served it.

A breaking change ships as a new major version at a new path, and the previous version keeps working for at least 180 days after its successor is published. A deprecated version returns the RFC 8594 Deprecation header with the date deprecation began and a Sunset header with the date it stops responding, both at least 180 days before removal. Adding an endpoint, an optional parameter or a response field is not breaking and ships without a version bump.

## Errors

Every failure returns JSON, including 404s on unknown paths. The body carries a stable machine-readable code, a human-readable message, a hint describing how to resolve the problem, the HTTP status, the request path and a link back to this specification. Codes in use: not_found, bad_request, unauthorized, forbidden, rate_limited, payload_too_large and internal_error.

## Rate limits

All routes share a limit of 200 requests per 15 minutes per IP address. Exceeding it returns HTTP 429 with the rate_limited code. Please cache responses where you can rather than polling.

## Markdown and agent files

- Agent guide: https://www.successmagis.live/llms.txt - describes when an agent should use this site.
- Sitemap: https://www.successmagis.live/sitemap.xml
- Every public page is available as Markdown. Send Accept: text/markdown to any page URL, or append .md to the path.

---

Canonical: https://www.successmagis.live/developers
Sitemap: https://www.successmagis.live/sitemap.xml
Agent guide: https://www.successmagis.live/llms.txt