---
title: "Document APIs"
description: "How to navigate our API documentation — OpenAPI specs, Markdown supplements, and the Try-It-Out console."
url: "https://education.gough.run/guides/document-apis"
image: "https://education.gough.run/_og/d/c_Ocean.takumi,title_Document+APIs,description_~SG93IHRvIG5hdmlnYXRlIG91ciBBUEkgZG9jdW1lbnRhdGlvbiDigJQgT3BlbkFQSSBzcGVjcywgTWFya2Rvd24gc3VwcGxlbWVudHMsIGFuZCB0aGUgVHJ5LUl0LU91dCBjb25zb2xlLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiM2NmFhMjMifX19,p_Ii9ndWlkZXMvZG9jdW1lbnQtYXBpcyI,s_ysE9_z9Zh7R18i05.png"
---

## Document APIs

How to navigate our API documentation — OpenAPI specs, Markdown supplements, and the Try-It-Out console.

## [What you'll find in the catalog](#what-youll-find-in-the-catalog)

Every API in this portal has three layers of documentation: an OpenAPI specification (the contract), Markdown supplements (the context), and an interactive Try-It-Out console (the playground). Together, these tell you what an API does, how to call it, and let you exercise it live without writing a single line of integration code.

The Education Data Platform exposes three APIs, each documented in this way:

-   **Stats REST API** — Traditional REST endpoints for aggregate education statistics
-   **Education GraphQL API** — Relay-style GraphQL for flexible, query-driven access
-   **Stats MCP Server** — Model Context Protocol interface for AI agents

## Explore our APIs

Connect, create, and innovate with our easy-to-use APIs.

[Start building](https://education.gough.run/apis)

### [Using the OpenAPI specification](#using-the-openapi-specification)

Each API page shows its OpenAPI spec in a fully-rendered, navigable view. You can:

-   Browse operations grouped by tag
-   Inspect request and response schemas
-   See authentication requirements
-   Drill into specific operations to see headers, parameters, examples, and response codes

The spec is the source of truth — it's the same machine-readable document the gateway uses to validate requests and that codegen tools use to generate client SDKs.

### [Using the Markdown supplements](#using-the-markdown-supplements)

OpenAPI is great for the contract but light on context. We supplement each API spec with a Markdown guide that covers:

-   Schema details that don't fit cleanly into OAS (especially for GraphQL)
-   Example queries grouped by use case
-   Notes on rate limit costs and cursor pagination
-   Error handling guidance
-   Best practices for batching, caching, and retry behaviour

Look for the Markdown section linked from each API's main page.

### [Using Try-It-Out](#using-try-it-out)

The interactive console at the top of each operation lets you fire real requests at the gateway from within the portal. To use it:

1.  Make sure you've registered an application and have a Bearer token (see [Publish APIs](https://education.gough.run/guides/publish-apis))
2.  Paste the token into the Authorization field at the top of the operation
3.  Fill in any required parameters
4.  Click **Send**

You'll see the live response below — same shape, same auth, same rate limits as a production integration would.

## [Reading the OpenAPI examples](#reading-the-openapi-examples)

Each operation's request body includes one or more **named examples** — pre-built request payloads you can use as a starting point.

Pick the example that matches your use case, hit Send, and you'll see what the response shape looks like.

```bash
# Equivalent curl call you'd make outside the portal:
curl -X POST https://api.example.com/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ schools(first: 5) { totalCount edges { node { id name } } } }"
  }'
```

Try-It-Out also generates equivalent curl commands you can copy and run from your own terminal.

### [Schema browsing](#schema-browsing)

For typed languages (TypeScript, Java, Go), you can also export the OpenAPI spec directly from the portal and feed it into your favourite codegen tool to produce a fully-typed client SDK. Look for the **Download Spec** button on each API page.