# topin for developers · Public API and MCP server

# For developers

topin's score tools and exam guides are open to other apps and assistants: free, read-only, no key and no sign-in. Use them to answer students' questions about the GRE, GMAT, TOEFL and IELTS, and link back to the full guides.

## Tools

* `gre_score_percentiles`: Percentile ranks for GRE Verbal (130–170), Quant (130–170) and Analytical Writing (0–6) scores, from ETS's published table for all test takers, July 2022 – June 2025.
* `toefl_overall_band`: Overall TOEFL iBT band (1–6 scale, used since January 2026) and CEFR level from the four section bands: the mean rounded to the nearest half band, halves up.
* `ielts_band_scores`: IELTS Academic bands: Listening and Reading from correct answers out of 40, Writing from the Task 1 and Task 2 bands (Task 2 counts double), and the overall band when all four sections are given.
* `exam_section_guide`: topin's guide to one section of the GRE, GMAT, TOEFL or IELTS: format facts, every question type with a tip, how it's scored, a study plan and common mistakes.
* `list_exam_resources`: topin's pages for an exam (or all four): the exam overview, section guides, free tools, sample questions and the free full-length mock test.

## REST API

Send the arguments as JSON to `POST /v1/tools/{name}`. Errors come back as `{"error": {"code", "message"}}` with a 4xx status. The full schema is in [openapi.json](/openapi.json).

curl -X POST https://topin.app/v1/tools/gre_score_percentiles \
  -H "content-type: application/json" \
  -d '{"verbal": 158, "quant": 162}'

## MCP server

Connect any MCP client to `https://topin.app/mcp` (Streamable HTTP). The server card is at </.well-known/mcp/server-card.json>. In a browser, the same tools are offered through WebMCP.

## Content

* [llms.txt](/llms.txt) lists every public page.
* Any page is available as markdown: add `.md` to its URL (</gre.md>) or send `Accept: text/markdown`.

## Versioning

The version is in the path (`/v1`). New tools and new optional fields are added in place. A breaking change gets a new path, and the old one keeps working for at least 6 months, announced here and with `Deprecation` and `Sunset` headers on its responses.

## Fair use

Scores come from official tables and are estimates; the official score report is final. Please link to the topin page a result came from, and keep request rates reasonable. Questions or ideas: [support@topin.app](mailto:support@topin.app).