API docs by Redocly

MirrorMingo Developer API (1.1.0)

Download OpenAPI specification:

MirrorMingo Developer Support: developers@mirrormingo.com URL: https://developers.mirrormingo.com License: Proprietary

Exam preparation and private Arena competitions.

The MirrorMingo Exam API is the public, developer-facing surface for MirrorMingo's verified exam-prep platform. It exposes:

  • A registry of supported exams (JAMB, WAEC, NECO, IELTS, SAT, and more), each with official section specs, scoring rubrics and verified source links.
  • A library of real, never-fabricated past-question papers, grouped by year.
  • A timed mock-exam engine: open a paper, page through questions, submit answers, and receive scored feedback.

All content is curriculum-grounded and verified against official exam-board sources. The Exam API does not generate past questions. Arena accepts partner-supplied questions, which are not automatically verified by MirrorMingo.

MirrorMingo School Intelligence is a separate school-subscription product. It is not exposed through this third-party developer API.

Authentication

Every request must include a MirrorMingo API key as a bearer token:

Authorization: Bearer mirrormingo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and manage keys from the Developer dashboard. Keys are shown only once at creation time — store them securely and never embed them in client-side code.

Versioning

The API is versioned in the path (/v1). Breaking changes ship under a new major version; additive changes (new fields, new endpoints) may appear within v1 without notice, so clients should ignore unknown fields.

Rate limits

Requests are rate limited per API key. The current allowance is returned on every response via the RateLimit-* headers. On exhaustion the API responds with 429 Too Many Requests and a Retry-After header.

Exams

Discover supported exams and their official specifications.

List supported exams

Returns the catalog of exams MirrorMingo supports, optionally filtered by country. Each entry carries enough metadata to render a picker.

Authorizations:
apiKey
query Parameters
country
string

Full country name to prioritise locally relevant exams (e.g. Nigeria).

country_code
string = 2 characters

ISO 3166-1 alpha-2 country code (e.g. NG).

Responses

Response samples

Content type
application/json
{
  • "exams": [
    ]
}

Get exam overview

Full specification for one exam — sections, timing, question types and scoring.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Responses

Response samples

Content type
application/json
{
  • "exam_key": "string",
  • "name": "string",
  • "category": "string",
  • "country": "string",
  • "duration_min": 0,
  • "sections": [
    ],
  • "scoring": { }
}

Get verified exam resources

Official exam-board sites and verified past-question sources for the exam.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Responses

Response samples

Content type
application/json
{}

Get a recommended study path

A suggested week-by-week study path for the exam.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Responses

Response samples

Content type
application/json
{
  • "exam_key": "string",
  • "study_weeks": 0,
  • "study_hours_total": 0,
  • "study_path": [
    ]
}

Mock Exams

Open verified past-question papers and run timed attempts.

List available past-question papers

Lists the verified past-question papers available for an exam, grouped by year. Use a paper_id from this response to open a mock attempt.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Responses

Response samples

Content type
application/json
{
  • "exam_key": "string",
  • "total_papers": 0,
  • "years": [
    ]
}

Open a paper into a timed attempt

Opens a verified paper into a new timed mock-exam attempt and returns the first page of questions. The returned attempt_id is used to page through questions and to submit answers.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Request Body schema: application/json
required
paper_id
required
string [ 6 .. 160 ] characters

A paper_id from the mock-exam catalog.

question_offset
integer >= 0
Default: 0
question_limit
integer [ 1 .. 20 ]
Default: 9
learner_id
string <= 160 characters

Stable learner reference from your app. Use the same value when paging, submitting and listing history.

Responses

Request samples

Content type
application/json
{
  • "paper_id": "string",
  • "question_offset": 0,
  • "question_limit": 9,
  • "learner_id": "string"
}

Response samples

Content type
application/json
{
  • "attempt_id": "string",
  • "paper_id": "string",
  • "question_count": 0,
  • "questions": [
    ]
}

Load a page of questions

Loads one page of questions for a paper, for paging through long papers.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Request Body schema: application/json
required
paper_id
required
string [ 6 .. 160 ] characters
question_offset
integer >= 0
Default: 0
question_limit
integer [ 1 .. 20 ]
Default: 9
learner_id
string <= 160 characters

Same learner reference used when opening the attempt, if any.

Responses

Request samples

Content type
application/json
{
  • "paper_id": "string",
  • "question_offset": 0,
  • "question_limit": 9,
  • "learner_id": "string"
}

Response samples

Content type
application/json
{
  • "questions": [
    ],
  • "total": 0
}

Submit a mock attempt

Submits learner answers for an attempt and returns scored feedback.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

Request Body schema: application/json
required
attempt_id
required
string [ 6 .. 160 ] characters
required
object

Map of answer_id to chosen option letter. Plain question-number keys are accepted for compatibility when unambiguous.

status
string
Default: "submitted"
Enum: "submitted" "expired" "abandoned"
learner_id
string <= 160 characters

Same learner reference used when opening the attempt, if any.

Responses

Request samples

Content type
application/json
{
  • "attempt_id": "string",
  • "answers": {
    },
  • "status": "submitted",
  • "learner_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "feedback": { }
}

List past attempts

Lists prior mock-exam attempts for the authenticated key, newest first.

Authorizations:
apiKey
path Parameters
exam_key
required
string non-empty

The exam identifier (e.g. jamb, waec, ielts).

query Parameters
limit
integer [ 1 .. 50 ]
Default: 10
offset
integer >= 0
Default: 0
learner_id
string <= 160 characters

Stable learner reference from your app. MirrorMingo stores only a hash-derived internal namespace.

Responses

Response samples

Content type
application/json
{
  • "attempts": [
    ],
  • "total": 0
}

Arena

Private competitions, scoped learner sessions and durable completion events.

Create Competition

Create Competition. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
Request Body schema: application/json
required
request_id
required
string (Request Id) [ 1 .. 100 ] characters
title
required
string (Title) [ 1 .. 200 ] characters
required
Array of objects (Questions) [ 1 .. 120 ] items
max_players
integer (Max Players) [ 1 .. 6 ]
Default: 6
seconds_per_question
integer (Seconds Per Question) [ 10 .. 300 ]
Default: 30
Opens At (string) or Opens At (null) (Opens At)
Closes At (string) or Closes At (null) (Closes At)

Responses

Request samples

Content type
application/json
{
  • "request_id": "string",
  • "title": "string",
  • "questions": [
    ],
  • "max_players": 6,
  • "seconds_per_question": 30,
  • "opens_at": "2019-08-24T14:15:22Z",
  • "closes_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Get Competition

Get Competition. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Create Session

Create Session. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)
Request Body schema: application/json
required
role
string (Role)
Default: "participant"
Enum: "participant" "spectator"
learner_id
string (Learner Id) <= 160 characters
Default: ""
display_name
string (Display Name) <= 100 characters
Default: ""
ttl_seconds
integer (Ttl Seconds) [ 60 .. 86400 ]
Default: 3600

Responses

Request samples

Content type
application/json
{
  • "role": "participant",
  • "learner_id": "",
  • "display_name": "",
  • "ttl_seconds": 3600
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "match_id": "string",
  • "participant_id": "string",
  • "role": "participant",
  • "expires_at": "string",
  • "websocket_path": "string"
}

Start Competition

Start Competition. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Cancel Competition

Cancel Competition. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Revoke Sessions

Revoke Sessions. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)

Responses

Response samples

Content type
application/json
{
  • "revoked": true
}

Play State

Play State. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Answer

Answer. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
path Parameters
match_id
required
string (Match Id)
Request Body schema: application/json
required
request_id
required
string (Request Id) [ 1 .. 100 ] characters
question_id
required
string (Question Id) [ 1 .. 100 ] characters
picked_index
required
integer (Picked Index) [ 0 .. 5 ]

Responses

Request samples

Content type
application/json
{
  • "request_id": "string",
  • "question_id": "string",
  • "picked_index": 5
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "version": 0,
  • "ruleset": "turns-v1",
  • "phase": "waiting",
  • "server_time": 0,
  • "deadline": 0,
  • "current_index": 0,
  • "question_count": 0,
  • "max_players": 0,
  • "seconds_per_question": 0,
  • "players": [
    ],
  • "turn_player_id": "string",
  • "question": {
    },
  • "result": {
    }
}

Events

Events. See the Arena integration guide for lifecycle and retry semantics.

Authorizations:
ArenaBearer
query Parameters
after
integer (After) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "cursor": 0,
  • "has_more": true
}