# 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](https://yappy.biz/developers/) or the
[REST guide](https://yappy.biz/developers/rest-api). This page is the endpoint
list.

## Conventions

- Responses are `application/json; charset=utf-8`; errors are
  `application/problem+json` ([shape](https://yappy.biz/developers/errors)).
- 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.

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `limit` | integer | 20 | 1–100 |
| `cursor` | string | — | Opaque; from `pagination.next_cursor` |

```bash
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.

```json
{
  "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".

| Parameter | Type | Required | Example |
|---|---|---|---|
| `os_version` | string | yes | `14.5` |
| `arch` | string | yes | `arm64` or `x86_64` |

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

```json
{
  "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.

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `q` | string | — | Required, 2–200 characters |
| `limit` | integer | 10 | 1–50 |
| `cursor` | string | — | Opaque |
| `type` | string | — | `doc` or `faq` to narrow |

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](https://yappy.biz/developers/sandbox).

## Auth

Optional. `Authorization: Bearer <token>` raises your rate ceiling and unlocks
export scopes — see [authentication](https://yappy.biz/developers/authentication).

---

Canonical: https://yappy.biz/api/ · Last updated: 2026-08-25