{"openapi":"3.1.0","info":{"title":"Brightfold API","version":"1.0.0","summary":"Read-only access to Brightfold’s public website content and product catalog.","description":"Public, read-only API for the content of brightfold.ai: pages (with their Markdown) and the product catalog. No authentication is required.\n\n**Versioning.** The JSON API is versioned in the URL path (`/api/v1`); every response carries an `API-Version` header. Backwards-compatible changes (new fields, new endpoints) ship within a version. Breaking changes ship as a new path version, and a retiring version announces itself with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) response headers before it is removed.\n\n**Rate limits.** 60 requests per 60 seconds per client, reported on every response with `RateLimit-Policy`, `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Over the limit you get a `429` with `Retry-After`.\n\n**Errors.** Every API error is an RFC 9457 `application/problem+json` object with a stable machine-readable `code`.\n\nGuide: https://brightfold.ai/developers","contact":{"name":"Brightfold","email":"hello@brightfold.ai","url":"https://brightfold.ai/support"}},"externalDocs":{"description":"Developer guide","url":"https://brightfold.ai/developers"},"servers":[{"url":"https://brightfold.ai","description":"Production"}],"tags":[{"name":"Content","description":"Website pages as structured JSON."},{"name":"Products","description":"Brightfold’s products."},{"name":"Documents","description":"Markdown and plain-text views of the site for LLMs."}],"paths":{"/api/v1/pages":{"get":{"operationId":"listPages","tags":["Content"],"summary":"List website pages","description":"Returns every page on brightfold.ai with its title, description, and URLs for the HTML page, its Markdown, and its API detail. Use it to discover slugs for getPage.","responses":{"200":{"description":"All pages.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageList"}}}},"429":{"description":"Rate limit exceeded. Wait for `Retry-After` seconds before retrying.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/pages/{slug}":{"get":{"operationId":"getPage","tags":["Content"],"summary":"Get a page with its Markdown","description":"Returns one page, including its full content as Markdown. Use it to read what a Brightfold page says, e.g. product details or the privacy policy.","parameters":[{"name":"slug","in":"path","required":true,"description":"Page slug from listPages, e.g. `scholar` or `privacy`. The home page is `home`.","schema":{"type":"string","pattern":"^[a-z0-9-]+$","examples":["scholar"]}}],"responses":{"200":{"description":"The page.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"}}}},"404":{"description":"No page with that slug (`code: not_found`).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded. Wait for `Retry-After` seconds before retrying.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List Brightfold products","description":"Returns Brightfold’s products with what each does and where to learn more. Use it to answer which Brightfold product fits a school or district need.","responses":{"200":{"description":"All products.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"429":{"description":"Rate limit exceeded. Wait for `Retry-After` seconds before retrying.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/markdown":{"get":{"operationId":"getHomeMarkdown","tags":["Documents"],"summary":"Home page as Markdown","description":"The home page as Markdown. `GET /` with `Accept: text/markdown` returns the same.","responses":{"200":{"description":"Home page Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/{slug}.md":{"get":{"operationId":"getPageMarkdown","tags":["Documents"],"summary":"A page as Markdown","description":"A page as Markdown. `GET /{slug}` with `Accept: text/markdown` returns the same; unknown pages return a Markdown 404 that links to the site map.","parameters":[{"name":"slug","in":"path","required":true,"description":"Page slug, e.g. `gateway`.","schema":{"type":"string","pattern":"^[a-z0-9-]+$","examples":["gateway"]}}],"responses":{"200":{"description":"Page Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Markdown explaining the page was not found.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/sitemap.md":{"get":{"operationId":"getSiteMapMarkdown","tags":["Documents"],"summary":"Site map as Markdown","description":"Every page with a one-line description, as Markdown.","responses":{"200":{"description":"Site map Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["Documents"],"summary":"Site overview for LLMs","description":"llms.txt: what Brightfold is, when to use this site, and where everything lives.","responses":{"200":{"description":"llms.txt","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details.","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string","format":"uri","description":"Link to documentation for this error."},"title":{"type":"string","description":"Short, human-readable summary of the error."},"status":{"type":"integer","description":"HTTP status code."},"code":{"type":"string","enum":["not_found","method_not_allowed","rate_limited","internal_error"],"description":"Stable, machine-readable error code."},"detail":{"type":"string","description":"Human-readable explanation of this occurrence."},"instance":{"type":"string","description":"Request path that produced the error."}}},"PageSummary":{"type":"object","required":["slug","title","description","url","markdownUrl","apiUrl"],"properties":{"slug":{"type":"string","description":"Page identifier, used by getPage."},"title":{"type":"string"},"description":{"type":["string","null"],"description":"Meta description, if set."},"url":{"type":"string","format":"uri","description":"HTML page."},"markdownUrl":{"type":"string","format":"uri","description":"The page as Markdown."},"apiUrl":{"type":"string","format":"uri","description":"getPage URL for this page."}}},"Page":{"allOf":[{"$ref":"#/components/schemas/PageSummary"},{"type":"object","required":["markdown"],"properties":{"markdown":{"type":"string","description":"Full page content as Markdown."}}}]},"Product":{"type":"object","required":["id","name","category","description","highlights","url"],"properties":{"id":{"type":"string"},"name":{"type":"string","examples":["Brightfold Scholar"]},"category":{"type":"string","examples":["AI for teachers"]},"description":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri","description":"Product page."}}},"ListMeta":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0}}},"PageList":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PageSummary"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"PageResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Page"}}},"ProductList":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}}},"headers":{"RateLimit-Policy":{"description":"Quota policy: `60;w=60` (60 requests per 60 s).","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying (on 429).","schema":{"type":"integer"}}}}}