What you'll 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

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

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

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)
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

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.

# 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

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.