---
$id: https://apps.ax/docs/reference
$type: TechArticle
$context: https://schema.org
title: "Reference"
publishedWith: https://apps.ax
---


# API reference

apps.ax is one Worker with one seam: HTTP. Every route below is served for
**whichever instance the request hostname resolves to** — the routes
themselves never change per instance, only the Definition and live state
behind them do.

## GET / — the App's own page

Negotiated: a browser gets the faceted HTML directory for the resolved
instance; a non-HTML-preferring client (curl, an agent, `?format=md`) gets the
markdown-of-live-state twin. (On the `apps.ax` product host itself, `GET /` is
this landing page instead — the interpreter's own marketing face, not an
instance directory.)

## GET /directory — the faceted directory

Same negotiation as `GET /`. Query params:

- `?q=<term>` — searches every Definition field (never a seed's internal
  derivation fields), echoed back as `query` in the JSON face.
- `?<facetField>=<value>` — narrows to rows whose facet field equals value.
  A facet field is any enum or relation field in the noun.
- `?format=md|html` — explicit register override.

## GET /api/listings — the JSON API face

```json
{
  "app": "apis.directory",
  "listings": [{ "id": "...", "name": "...", "...": "..." }],
  "facets": [
    { "field": "category", "label": "Category", "kind": "enum",
      "options": [{ "value": "weather", "count": 3, "label": "Weather" }] }
  ],
  "query": "weather",
  "filters": { "category": "weather" },
  "total": 12,
  "matched": 3,
  "limit": 200,
  "offset": 0
}
```

`facets` is DERIVED from the Definition's noun — never hand-configured. Each
enum field's options are exactly its declared values (zero-count included);
each relation field's options are the distinct values present in the live
collection, sorted by count. Pagination: `?limit=` (default 200, max 500) and
`?offset=`.

## GET /listings/:id — one listing's detail

Negotiated, same as the directory: markdown twin or designed HTML page. The
detail's JSON-LD graph is field-generic — `@type` comes from the Definition's
optional `schemaType` (a generic `Thing` fallback otherwise), and every
property is iterated from the noun's fields, emitted only when non-empty.

## POST /listings — the submit verb

KV instances only (the `apis.directory` default); a static (read-only)
instance answers `405 read_only_instance`. The body is validated against the
resolved Definition's fields:

- a required field missing → `422`
- an enum value outside its declared options → `422`
- a relation value that is not a short `[A-Za-z0-9._-]` id (max 64 chars) →
  `422`
- a `url` field that is not an absolute `http(s)` URL → `422` (never reaches
  an `<a href>` — closes the stored-XSS vector at the seam)

Success returns `201 { id, listing }`.

## POST /listings/:id/placement — the paid Placement slot

KV instances only (the `apis.directory` default); a static (read-only)
instance answers `405 read_only_instance`, same as the submit verb. `404` if
`:id` does not match a listing in the resolved instance's live collection.

Otherwise, behavior depends on `STRIPE_STUB`:

- `STRIPE_STUB=1` (local/dev runs) → `200` with a deterministic stub checkout
  (page.ax's ADR-0009 pattern, reused): `{ checkoutUrl, sessionId, mode: "stub",
  placement: { listing, slot: "sponsored", priceCents }, settlement: "unwired",
  followUp }`. `priceCents` defaults to `2500`, overridable via
  `PLACEMENT_PRICE_CENTS`. `settlement: "unwired"` is an honest scope marker —
  this is a checkout-intent stub only; no webhook → durable-slot rail is wired
  yet (that's `followUp`'s note: wire it to the page.ax Stripe rail).
- Otherwise → `503 { error: "placement_unavailable", detail: "no payment rail
  configured (set STRIPE_STUB=1 for local runs)" }`.

## GET /llms.txt — the agent index

Generated from the resolved instance's Definition: its tagline, its faces
(directory markdown/HTML, the API face, detail), and its noun's field grammar
— so an agent discovers the whole surface from one file, for ANY mounted
instance.

## How a Definition maps to every face

| Definition piece | Where it shows up |
| --- | --- |
| `name` / `tagline` | the directory header, `llms.txt`, `<title>` |
| an enum field | a facet group (declared options, live counts); a colored chip on cards/detail |
| a relation field | a facet group (distinct live values, sorted by count); a chip |
| any other scalar | a plain chip; an `http(s)` URL scalar becomes a link chip |
| `verbs.Listing` including `"submit"` | `POST /listings` is enabled (KV instances) |
| `schemaType` | the detail page's JSON-LD `@type` (falls back to `Thing`) |

Every row above is iterated generically by `facets.ts` / `render.tsx` /
`generate.ts` — none of them name a field literally, so a Definition change
propagates to every face with zero edits there.

## This site

- Docs: [/docs](/docs) (index) · [/docs/llms.txt](/docs/llms.txt)
- llms.txt: [/llms.txt](/llms.txt)

Every docs page here is itself a screen-law face: markdown to agents, this
designed HTML to humans, at one URL.

---

Previous: [Concepts](https://apps.ax/docs/concepts)

Docs index: https://apps.ax/docs · all pages: https://apps.ax/docs/llms.txt

This page is also served as designed HTML at the same URL (add `?format=html`).
