API for developers

Read the Boarding Schools data as JSON. The API is free, needs no key and reads only. Base URL: https://boardingschools.fyi/api/v1.

The OpenAPI 3.1 description is at /api/v1/openapi.json. Any website may call the API from a browser.

Endpoints

Each endpoint in this table takes GET. Any other method gives 405. A parameter that is not listed gives 400.

Endpoints of the Boarding Schools API, with their parameters
Endpoint	Returns	Parameters
`GET /api/v1/listings`	Search and list listings	`q` (query, optional, string) Search text, with at least one letter or digit. Matches name, categories, attributes, description and place. Typos fall back to close matches. `country` (query, optional, string) ISO 3166-1 alpha-2 country code, any case. A country the directory does not cover, as listed in /places, gives 400. `region` (query, optional, string) Region slug, from /places. `city` (query, optional, string) City slug, from /places. `category` (query, optional, string) Category slug, from /categories. A parent slug also matches its children. `sort` (query, optional, one of: `relevance`, `name`, `recent`) `relevance` needs `q` and is the default with it. `name` is the default without `q`. `recent` is newest first. `limit` (query, optional, integer, 1 to 50, default 20) Items per page. `cursor` (query, optional, string) `page.nextCursor` from the previous response. Opaque. Send the same filters and `limit`.
`GET /api/v1/listings/{slug}`	Read one listing	`slug` (path, required, string) The listing slug.
`GET /api/v1/places`	List countries, regions and cities with counts	None
`GET /api/v1/categories`	List the category tree with counts	None
`GET /api/v1/sources`	List the data sources with license and refresh	None
`GET /api/v1/stats`	Counts and the last update	None
`GET /api/v1/products`	List the live products, all or one category's	`category` (query, optional, string) A product category slug.
`GET /api/v1/products/{slug}`	Read one product	`slug` (path, required, string) The product slug.
`GET /api/v1/product-categories`	List the product categories with their product counts	None
`GET /api/v1/academy/courses`	List the published academy courses	`level` (query, optional, one of: `foundations`, `practitioner`, `specialist`) Only courses of this level. `limit` (query, optional, integer, 1 to 50, default 50) Most courses to return.
`GET /api/v1/academy/courses/{slug}`	Read one published course with its objectives, lessons and FAQ. No exam questions or answers	`slug` (path, required, string) The course slug.
`GET /api/v1/certificates/{code}`	Verify one certificate of completion by its code	`code` (path, required, string) A certificate code. Dashes, spaces and case do not matter.

Examples

Find boarding schools

curl "https://boardingschools.fyi/api/v1/listings?category=co-educational-boarding-schools&country=GB&limit=5"

Read the next page

curl "https://boardingschools.fyi/api/v1/listings?limit=5&cursor=<page.nextCursor from the last response>"

Read one boarding school

slug=$(curl -s "https://boardingschools.fyi/api/v1/listings?limit=1" | jq -r '.data[0].slug')
curl "https://boardingschools.fyi/api/v1/listings/$slug"

List the places and categories you can filter by

curl "https://boardingschools.fyi/api/v1/places"
curl "https://boardingschools.fyi/api/v1/categories"

MCP server

An AI agent can use the same data through MCP at https://boardingschools.fyi/mcp. It takes POST only: a GET in a browser gives 405. The server uses Streamable HTTP, keeps no session and needs no key. It reads only. It has the same rate limit, the same public fields and the same credit line as the API. The server card describes it.

search_listings: : Search published boarding schools by text, place and category.
get_listing: : Get one published boarding school by its slug.
list_places: : List countries, regions and cities that have boarding schools.
list_categories: : List categories with their boarding school counts.
get_stats: : Get the number of published boarding schools, places and categories, and when the data last changed.
list_sources: : List where the boarding school data comes from, with the license and refresh of each source.
list_products: : List the products, with the price each had on the day it was checked. Filter by product category.
get_product: : Get one product by its slug, with its page and outbound link.
list_product_categories: : List the product categories with their product counts.

Add it to Claude Code

claude mcp add --transport http boardingschools https://boardingschools.fyi/mcp

Add it to a client that reads an mcpServers file, such as Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "boardingschools": {
      "url": "https://boardingschools.fyi/mcp"
    }
  }
}

List the tools with curl

curl -X POST "https://boardingschools.fyi/mcp" -H "content-type: application/json" -H "accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Responses

A successful response has data and meta. A list response also has page, with these fields:

limit: : items on each page.
total: : items that match.
nextCursor: : send it back as cursor, with the same filters and limit. It is null on the last page.
capped: : true when more items match than the cursor can reach.
fuzzy: : true when the items are close matches for q.

An error has error (a sentence), code and sometimes details. Branch on code: invalid_parameter, invalid_cursor, not_found, method_not_allowed, rate_limited, internal_error, unavailable.

Rate limits and caching

Each client may send 300 requests in 60 seconds. Every GET response has RateLimit-Limit and RateLimit-Policy. Over the limit you get 429 with Retry-After: wait that many seconds. The limit is counted at each Cloudflare location.

A successful response sends Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600 and an ETag. Send the ETag back as If-None-Match to get 304 with no body.

Credit and licenses

Show this credit line next to the data you display:

Data from Boarding Schools (https://boardingschools.fyi). Each record keeps the license of its source, listed in meta.sources. A listing is a record, not an endorsement.

Every response lists its sources in meta.sources. Keep a source's license when you reuse its records.

Australian Boarding Schools Association (ABSA): license Association copyright; no reuse licence stated, refreshed manual
Boarding Schools’ Association (BSA): license BSA Group copyright and terms; no reuse licence stated, refreshed manual
Canadian Accredited Independent Schools (CAIS): license Association copyright; no reuse licence stated, refreshed manual
Listing enrichment: license source, refreshed manual
Get Information about Schools (DfE): license Open Government Licence v3.0, refreshed manual
Listing provenance and discovery sources: license DfE GIAS: Open Government Licence v3.0; association public directories: no reuse licence stated; copyright notices apply., refreshed manual
Business websites: license Business website facts; text and images retain their original rights., refreshed manual

Published by Boarding Schools. How we check each boarding school.