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.
Base URL: https://api.successmagis.live/api
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.
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.
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" } }
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.
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.
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.