For developers and agents

Coral API Documentation

Coral's public API is read-only, unauthenticated, and safe to cache. Everything on this page is generated from the same source as /openapi.json.

Base URL and authentication

Every documented endpoint is served from a single origin:

https://coral.ax

These endpoints need no authentication

No API key, no session cookie, no rate-limit registration, no Authorization header. Send a bare GET and you get JSON. Everything documented here is read-only, so no request can change anything in Coral. Endpoints that are not documented here — the authenticated dashboard API, webhook receivers and internal proxies — are not part of any contract and may change without notice.

Public endpoints

MethodPathSummaryNotes
GET /api/health Service health (System) Liveness, deployed version and uptime. Does no database work. Never cached.
GET /api/version Deployed version (System) The version string of the running build.
GET /api/blog/posts List published blog posts (Blog) Newest first, with pagination metadata. Optional ?page, ?limit and ?category.
GET /api/blog/posts/{slug} Get one blog post (Blog) One published post by slug, including the full HTML body.
GET /api/blog/categories List blog categories (Blog) Distinct categories in use, as a flat array of strings.
GET /public/api/products Look up products by id (Catalog) At least one ?id is required; repeat it for several. A lookup, not a browsable catalogue.
GET /public/api/plans List public pricing plans (Plans) Per-brand plans in plans, multi-brand bundles in bundles.
GET /public/api/brands/{id} Get a brand's public profile (Brands) Name, logo, website and product category only — no contact, billing or Amazon account data.
GET /api/affiliate-programs/public Get an affiliate program by id (Affiliate Programs) Single-resource lookup: ?id is required and exactly one program comes back.
GET /api/affiliate-programs/page/{pageId} Get an affiliate program by page id (Affiliate Programs) Resolves an /a/{pageId} invite link. An archived program returns 410 with archived: true.
GET /api/landing-pages/public/{slug} Get a published landing page (Landing Pages) Page plus visible sections in render order. Carries a weak ETag, so If-None-Match gets a 304.
GET /api/referrals/info/{referralCode} Resolve a referral code (Referrals) Creator name, brand name and commission rate behind an active /r/{code} link.
GET /openapi.json This OpenAPI document (JSON) (Machine-readable) OpenAPI 3.1. Also served at /api/openapi.json. Cached for one hour.
GET /api/openapi.yaml This OpenAPI document (YAML) (Machine-readable) The same document as YAML.
GET /llms.txt Site index for AI agents (Machine-readable) Plain-text navigation index following the llms.txt convention.
GET /sitemap.xml XML sitemap (Machine-readable) Public pages, published blog posts and visible affiliate program pages.

Path parameters are shown in {braces}, matching the OpenAPI document. Request and response schemas for every row live in /openapi.json.

Examples

List the public pricing plans

curl -s https://coral.ax/public/api/plans

Page through published blog posts

curl -s "https://coral.ax/api/blog/posts?limit=5&page=1"

Fetch the OpenAPI document

curl -s https://coral.ax/openapi.json

Errors

Errors carry a top-level message for humans plus a structured error object with a stable machine-readable code, a hint describing what to change, a docs URL, and the HTTP status repeated in the body:

{
  "message": "Human-readable summary",
  "error": {
    "code": "invalid_request",
    "message": "Human-readable summary",
    "hint": "What to change about the request",
    "docs": "https://coral.ax/docs#errors",
    "status": 400
  }
}

One exception: the /api/blog/* endpoints predate this envelope and return the legacy shape { "error": "some string" } instead. That is documented per-operation in the OpenAPI document.

Markdown for agents

Coral's main HTML pages have a clean Markdown twin, served with the text/markdown media type at the page's .md URL — no React shell, no navigation chrome, just the document. That is what an agent should fetch instead of scraping the rendered page, and it is what every link in /llms.txt points at:

# Markdown twin of https://coral.ax/how-it-works
curl -s https://coral.ax/how-it-works.md

Requesting the HTML URL with an Accept: text/markdown header does not yet return the Markdown twin — that negotiation is not wired up. Use the .md suffix for now.

Machine-readable index

  • /openapi.json — OpenAPI 3.1 description of every endpoint below, as JSON.
  • /api/openapi.yaml — The same document as YAML.
  • /llms.txt — Site index for AI agents, linking Markdown twins of the main pages.
  • /sitemap.xml — XML sitemap of public pages, blog posts and affiliate programs.

Questions, or an endpoint you wish existed? Email support@coral.ax or use the contact form. Coral is operated by Svario, Inc. — see About Coral.