API · v1

Aoraforge Read API — static JSON endpoints

JSON endpoints under /api/v1/*.json. Read-only, no auth, no rate limit, CDN-cached. Aimed at AI agents (Claude Code, Cursor, ChatGPT agents, MCP clients) that want structured access to the methodology, products, case studies, samples, and per-case-study query libraries.

Why static JSON

The read half of an API doesn't need a server. Every endpoint here is a static file served by GitHub Pages, regenerated on every deploy from llms.config.ts as the single source of truth. CDN-cached, zero hosting cost, zero rate limit. The write half (POST /free-diagnostic) needs a Worker + polling backend; it's marked planned below.

Endpoints

Method	Path	Summary	Status
GET	/api/v1/index.json	API root — list of all endpoints + AI search engines polled	live
GET	/api/v1/version.json	API version + last deployed	live
GET	/api/v1/products.json	Three product tiers with pitches, prices, Stripe URLs	live
GET	/api/v1/methodology.json	Methodology essay index (5 essays)	live
GET	/api/v1/methodology/{slug}.json	Single essay — metadata + body excerpt	live
GET	/api/v1/case-studies.json	All case studies Aoraforge operates in (active + planned)	live
GET	/api/v1/samples.json	Sample reports indexed by case study + tier	live
GET	/api/v1/queries/{slug}.json	Public starter query library for an active case study	live
POST	/api/v1/free-diagnostic	Trigger a Free Diagnostic run (returns run_id)	planned
GET	/api/v1/runs/{run_id}	Poll a run for status; report JSON when complete	planned

Quick start (curl)

$ curl -s https://aoraforge.com/api/v1/products.json | jq '.products[].slug'
"free-diagnostic"
"pro-audit"
"pro-roadmap"
"citation-pack"

$ curl -s https://aoraforge.com/api/v1/queries/sydney-luxury-builds.json | jq '.categories.topical'
[
  "NCC 2025 residential 7-star NatHERS Sydney luxury custom home",
  "HBCF reform 2025 fixed-price contract requirements NSW custom builds",
  "NSW Design and Building Practitioners Act registration luxury home builder",
  "BASIX Sydney luxury custom home thermal performance 2026"
]

Versioning

Path-prefixed: /api/v1/. Breaking changes ship under a new version (/api/v2/); v1 stays online during deprecation. Removals announce at least 90 days ahead in /blog/ and the RSS feed.

CORS

GitHub Pages serves these files with permissive CORS by default. Browser-side agents can fetch() them directly; server-side and MCP-server agents can call them with any HTTP client.

For agents

The full agent integration guide is at /agents.md. The /llms.txt file at the site root is the high-signal index of canonical URLs and product facts that LLMs ingest as crawler input.

What's coming

Phase D adds an MCP server (npx @aora/mcp-server) that wraps these endpoints with typed tools. The write endpoints (POST /free-diagnostic, GET /runs/{id}) ship in Phase C2 once the polling backend is migrated into minyansh7/geo-forms-worker.