~/nouns

nouns

a REST API that builds REST APIs. and the UI for them.

you make API calls. nouns builds the backend, the JWT-protected end-user accounts, the OpenAPI spec, and a hosted, themable customer-facing site — all from JSON definitions you POST.

no migrations, no models, no deploys, no frontend build. define a noun, define a page, ship.

try it now see an example self-host

---

how it works

1. sign up. get a key.

# one customer = one developer account.
POST /customers/signup
{ "email": "you@example.com", "password": "..." }

# → token + your customer uuid (lives in your app's URLs).

2. make an app.

POST /apps
{ "slug": "todo" }

3. define a noun.

POST /apps/todo/nouns
{
  "name": "task",
  "fields": { "title": "string", "done": "bool", "priority": "int" },
  "enabled_actions": ["list", "create", "partial_update", "destroy"],
  "filterable_fields": ["done"]
}

4. you have a backend.

# end-users sign up here:
POST /<your_uuid>/todo/auth/signup

# they CRUD their tasks at:
POST   /<your_uuid>/todo/task         # create
GET    /<your_uuid>/todo/task         # list (?done=false works)
PATCH  /<your_uuid>/todo/task/<id>    # update
DELETE /<your_uuid>/todo/task/<id>    # delete

# live OpenAPI 3 spec + Scalar docs at:
GET /<your_uuid>/todo/openapi.json
GET /<your_uuid>/todo/docs

5. ship a UI for it.

# declare a few pages — table, cards, form, or detail layouts:
POST /apps/todo/pages
{
  "slug": "tasks",
  "title": "All Tasks",
  "layout": "table",
  "noun": "task",
  "columns": ["title", "done", "priority"],
  "actions": ["create", "edit", "delete"]
}

# wire them into a navigation block:
PUT /apps/todo/navigation
{ "items": [{"label": "Tasks", "page": "tasks"}] }

# (optional) brand it with three CSS knobs:
PUT /apps/todo/theme
{ "bg": "#1a0033", "fg": "#ff66cc", "accent": "#ffcc00" }

# your end-users land here, no frontend code required:
GET https://nouns-app.pages.dev/site/<your_uuid>/todo/tasks

that's the whole loop. tables are inline-editable, references auto-expand, m2m fields render as multi-selects, and your end-users sign in with the auth you got for free in step 4.

a runnable, fully-commented worked example — workout tracker — shows the entire flow in ~150 lines of bash.

---

what's in the box

• schema-validated CRUD on every noun you define
• per-app end-user accounts (email + password, JWT)
• record-level ownership (users see their own stuff by default)
• public_read toggle when you want everyone to see it
• per-action enable/disable (don't want DELETE? don't enable it)
• filterable fields you opt in to (no SQL injection-by-query-param)
• relations between nouns — reference:<noun> for 1:N, reference:<noun>[] for many-to-many. inline expansion via ?expand=field; protected deletes (no dangling references); contains-style filters for m2m.
• pages-API + hosted site renderer — POST page definitions (table, cards, form, detail) and a navigation block; get a live customer-facing site at nouns-app.pages.dev/site/<uuid>/<app>/<page>. tables are inline-editable; forms support on_submit: redirect:<page>.
• per-app theme — three CSS knobs (bg, fg, accent) via PUT /apps/<slug>/theme.
• mermaid ER importer — paste a diagram in /admin/import; nouns parses it, previews the API calls, and instantiates the whole app on confirm.
• live OpenAPI 3 spec + Scalar docs per app — schemas, paths, filterable params, expand options, and 409 semantics, all auto-generated from your noun definitions.
• multiple apps per account, fully isolated user pools
• a generic CRUD client UI, for poking at any app without writing code
• an admin UI for managing apps, nouns, pages, navigation, and theme

---

what's not in the box (yet)

• file uploads
• full-text search, aggregations, computed fields
• hooks / webhooks / scheduled jobs
• BYO auth providers (verify external JWTs against a JWKS)
• roles & groups inside an app
• payments — Stripe Connect on a payment noun is on the roadmap
• date-range filters and query operators (__gt, __contains) — exact-match only today
• multi-level expand (?expand=post.author)

they show up when someone actually needs them.

---

get started

the easiest way: just sign up at the hosted admin, paste a mermaid ER diagram into /admin/import, and you have a live app in seconds. or follow the workout-tracker walkthrough end-to-end.

prefer to self-host?

git clone <repo> nouns
cd nouns/api
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python manage.py migrate
.venv/bin/python manage.py runserver 127.0.0.1:8766

then visit the CRUD client at localhost. full deploy walkthrough in DEPLOY.md.