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


# Quickstart: define an App, get every face

apps.ax is one interpreter Worker that resolves a mounted App **instance** by
request hostname and renders it through the same generator every time. You do
not hand-build a frontend, an API, and an agent surface separately — you write
**one typed Definition**, and every face falls out of it.

## The shape of a Definition

A Definition names a noun (its fields) and, optionally, its verbs:

```ts
import type { AppDefinition } from "apps.ax/definition";

export const apisDirectory: AppDefinition = {
  name: "apis.directory",
  tagline: "Every agent-legible API, one browsable face.",
  nouns: {
    Listing: {
      name: "string",
      summary: "string",
      url: "string?",
      // an enum field -> a derived facet group
      category: "weather | finance | geo | data | payments",
      // a relation field -> a derived facet group
      provider: "->Provider",
    },
    Provider: { name: "string" },
  },
  verbs: {
    Listing: ["submit"], // the create verb: POST /listings
  },
};
```

Field grammar: a bare scalar (`string` / `number` / `boolean` / `date`), an
`"a | b | c"` enum, a `"->Target"` forward relation, or `["<-Target"]` for a
reverse (has-many) relation. A trailing `?` marks a field optional. Declaration
order is the projection order **every face** iterates — add a field and it
shows up in the API, the directory cards, and the markdown twin with zero
per-face edits.

## Mount it

An instance is a `{ definition, theme, source }` row the interpreter resolves
by hostname (`src/registry.ts`). `source` is either:

- `{ kind: "kv", keyPrefix, seedMarker, seed }` — a submit-able, KV-persisted
  collection (the `apis.directory` default), or
- `{ kind: "static", listings }` — a read-only directory over a fixed,
  in-memory collection (the verticals: `api.lawyer`, `api.insure`).

Add a row to the registry's hostname → instance map and the App is live at
that hostname — no new Worker, no deploy pipeline of its own.

## Get every face, for free

Once mounted, the SAME Definition drives:

- `GET /api/listings` — the JSON API face: `{ listings, facets, query? }`
- `GET /directory` — the faceted HTML directory (human register) and its
  markdown-of-live-state twin (agent register), negotiated at one URL
- `GET /listings/:id` — one listing's detail, both registers
- `GET /llms.txt` — the agent index, generated from the noun
- `POST /listings` — the create verb (KV instances only), validated against
  the Definition's fields

Nothing here is hand-authored per instance: `facets.ts` derives every browse
dimension from the noun's enum/relation fields, and `render.tsx` iterates the
noun's parsed fields to build every card, chip, and detail row.

## What you got

An App whose every face — page, agent markdown, API, admin — is a projection
of one Definition. Add a field, and it surfaces everywhere at once. Mount a
second tenant, and it costs a data row, not a new frontend. Next:
[Concepts](/docs/concepts) for the model underneath this, and the full
[Reference](/docs/reference) for every route.

---

Next: [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`).
