Brightfold API

The Brightfold API gives agents and developers read-only access to the public content of brightfold.ai: every page, with its full text as Markdown, and the Brightfold product catalog. It’s the same content you see on the site, as structured JSON.

Use it to answer questions about Brightfold, compare Brightfold products, or recommend one for a school or district need. It doesn’t expose student, staff, or district records. Customer data stays behind each product’s sign-in.

Quick start

No API key or sign-up needed. Send a GET request:

curl https://brightfold.ai/api/v1/products

{
  "data": [
    {
      "id": "ai-governance",
      "name": "Brightfold Gateway",
      "category": "AI governance",
      "description": "See, govern, and secure every AI tool across your district…",
      "highlights": ["FERPA & COPPA aligned for student privacy", "…"],
      "url": "https://brightfold.ai/gateway"
    }
  ],
  "meta": { "count": 4 }
}

Authentication

None. The API is public and read-only, and every endpoint answers to GET without credentials. Responses allow any origin (CORS), so you can call it from a browser.

Base URL

https://brightfold.ai/api/v1

Endpoints

GET /api/v1/products

Lists Brightfold’s products: id, name, category, description, highlights, and product page URL. OpenAPI operation listProducts.

GET /api/v1/pages

Lists every page on the site with its title, description, and URLs for the HTML page, its Markdown, and its API detail. OpenAPI operation listPages.

curl https://brightfold.ai/api/v1/pages

GET /api/v1/pages/{slug}

Returns one page, including its full content as Markdown in markdown. Slugs come from the list endpoint; the home page is home. OpenAPI operation getPage.

curl https://brightfold.ai/api/v1/pages/scholar

The full contract, with typed schemas for every response, is the OpenAPI 3.1 document. It’s also listed in the API catalog (RFC 9727).

Errors

Every error is an RFC 9457 problem details object, served as application/problem+json. Branch on code, which is stable; title and detail are for people and may change.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://brightfold.ai/developers#errors",
  "title": "Resource not found",
  "status": 404,
  "code": "not_found",
  "detail": "No page with slug \"pricing\". List pages with GET /api/v1/pages.",
  "instance": "/api/v1/pages/pricing"
}

• not_found (404): no such page or endpoint.
• method_not_allowed (405): the API only accepts GET.
• rate_limited (429): too many requests; wait for Retry-After seconds.
• internal_error (500): something went wrong on our side; retry later.

Rate limits

Each client can make 60 requests per minute. Every response reports where you stand, so you can pace yourself without guessing:

• RateLimit-Policy: the quota, 60;w=60 (60 requests per 60-second window)
• RateLimit-Limit: requests allowed in the current window
• RateLimit-Remaining: requests left in the current window
• RateLimit-Reset: seconds until the window resets

Over the limit, you get a 429 with a Retry-After header. Wait that many seconds before trying again.

Versioning and deprecation

The API is versioned in the URL path, and every response carries an API-Version header (currently 1). Within a version we only make backwards-compatible changes, like adding fields or endpoints, so ignore fields you don’t recognize.

Breaking changes ship as a new version, such as /api/v2, alongside the old one. Before a version is retired, its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the retirement date, and the change is noted on this page.

Content as Markdown

Every page is also available as Markdown, without the API:

• Send Accept: text/markdown to any page URL, e.g. curl -H 'Accept: text/markdown' https://brightfold.ai/scholar
• Or add .md to the path, e.g. /scholar.md. The home page is /markdown.
• Unknown pages return a Markdown 404 that links back to the site map.

For agents

• llms.txt: what Brightfold is, when to use this site, and how to call it
• Site map as Markdown
• Agent skills index

Support

Questions or something broken? Contact our support team or email hello@brightfold.ai.