API reference

Base URL **https://yappy.biz/api/v1** · OpenAPI 3.1 at [/openapi.json](https://yappy.biz/openapi.json) · no API key required.

New here? Start with the developer portal or the REST guide. This page is the endpoint list.

Conventions

• Responses are application/json; charset=utf-8; errors are application/problem+json (shape).
• Every object carries an object discriminator: release, doc, faq, plan, feature, job, list, error.
• List responses are { "object": "list", "data": [...], "pagination": {...} }.
• Every response carries ETag, X-Request-Id, API-Version, and the RateLimit-* headers.

GET /api/v1

The service index: every endpoint, the API version date, links to the spec, the MCP servers, and the auth metadata. A good first call for an agent that has just discovered the domain.

GET /api/v1/releases

Release history, newest first.

curl -s "https://yappy.biz/api/v1/releases?limit=3"

GET /api/v1/releases/latest

The current release, read from the same signed appcast the app's own updater reads — so it is never a stale hand-edited number.

{
  "object": "release",
  "version": "0.4.19",
  "published_at": "2026-08-25",
  "notes": "Fixes for a fresh install…",
  "download_url": "https://yappy.biz/download",
  "platform": { "os": "macOS", "min_version": "13.0", "arch": "arm64" }
}

GET /api/v1/releases/{version}

One release by exact version string, for example 0.4.17. 404 with a not_found code if there is no such version.

GET /api/v1/docs

The documentation index: slug, title, description, URL, and markdown URL for every page. Paginated.

GET /api/v1/docs/{slug}

One page. slug is the path after /docs/ — quickstart, dictation, agent-mode, backends, configuration, privacy-model, troubleshooting, changelog. Returns the markdown body plus metadata.

GET /api/v1/faq

Question and answer pairs, the same set rendered as FAQPage structured data on the homepage. Paginated.

GET /api/v1/pricing

What is free, and what each LLM backend costs. Includes the API's own terms — free, no key — so an agent can answer "what does it cost to integrate" without a second call.

GET /api/v1/features

Product capabilities as structured objects: id, name, description, whether it runs on-device, and which permission it needs.

GET /api/v1/requirements

System requirements: minimum macOS version, required architecture, disk, and the macOS permissions Yappy asks for and what each unlocks.

GET /api/v1/compatibility

Deterministic answer to "will this Mac run Yappy".

curl -s "https://yappy.biz/api/v1/compatibility?os_version=12.7&arch=arm64"

{
  "object": "compatibility",
  "compatible": false,
  "reasons": ["macOS 12.7 is below the minimum supported version 13.0"],
  "minimum": { "os_version": "13.0", "arch": "arm64" }
}

GET /api/v1/search

Full-text search across documentation and FAQ.

Results carry a score, the matching excerpt, and both the HTML and markdown URLs.

POST /api/v1/batch

Up to 20 GET operations in one round trip. Body: {"operations":[{"id":"a","method":"GET","path":"/faq?limit=1"}]}. Accepts Idempotency-Key. Returns 200 with per-operation status and body; one failure does not fail the rest.

POST /api/v1/exports

Start an export job. Body: {"resource":"docs"|"faq"|"releases","format":"markdown"|"json"}. Returns 202 with Location, Retry-After, and a job object. Accepts Idempotency-Key, which determines the job id.

GET /api/v1/exports/{job_id}

Poll a job. status moves queued → running → completed, and the completed body carries result.url.

Sandbox

Every path above also exists under /api/v1/sandbox with fixture data and a ?simulate= parameter for forcing each error. See sandbox.

Auth

Optional. Authorization: Bearer <token> raises your rate ceiling and unlocks export scopes — see authentication.