---
title: "How APIs.Dev works"
url: /how-it-works
---

# How APIs.Dev works

> How APIs.Dev turns one file into a product that people and agents find, choose, buy and verify, with its own site, portal and docs.

APIs.Dev turns one file into a product people and agents find, choose, buy and verify, with its own site, portal and docs. Nine subsystems run it.

**The system map**

`definition.ts` enters at 1.

1. [Definition and compile](#definition): one file, checked, versioned and diffed

↓ compiles to routes, state machines, prices, terms, every Interface, the site, the portal and the docs

2. [Identity, access and policy](#identity): who acts, for whom, and one decision on every move
3. [Model and records](#model): what each Customer keeps, and the views rebuilt from it
4. [Data and Sources](#data): what the product draws on, and outside truth reconciled
7. [Commerce](#commerce): selling on Stripe, and buying with agents under a mandate
8. [Interfaces and distribution](#interfaces): every way in and out: the site, the portal, the docs, being found

↓ every call and message comes in; every move asks, prices and commits through one gate

5. [Runtime](#runtime): the gate every move passes, and work that waits for weeks

↓ hands off work, and is watched and proved

6. [Work](#work): jobs done by agents and people, reviewed and supervised
9. [Trust and operations](#trust): runs it, watches every decision and proves it outside

**The seam:** Events · webhooks · entitlements · offers in replies · the UI contracts · every act a Verb. Everything outside the product reads it through these, and acts through the same Verbs.

- Composition goes sideways: any product can be a Source of another, with a price and a margin on each hop.
- Tenancy goes down: identity, the runtime, work and commerce are offered again to each Customer, and through it to its own customers.

## One file, four kinds of state
Your file compiles to one versioned [Definition](/reference/platform.md#definition), and every part of the product is generated from it. Underneath sit four kinds of state, and each has one owner.

| State | What it holds | Changed by |
| --- | --- | --- |
| The Definition | What may happen: Nouns, Verbs, lifecycles, prices, terms, Roles and staffing | a deploy, and nothing else |
| The record | What did happen: records, Events, [Actions](/workflow.md#the-lifecycle), money and evidence, kept forever | a Verb, through one commit gate |
| Views | Search, lists, metrics, and your own numbers: revenue, margin per Verb, cost to serve | rebuilt from the record, never written |
| Outside truth | Stripe, upstream [Sources](/patterns/dataset-api.md#how-a-field-is-filled), and the systems each Customer connects | reconciled; a disagreement arrives as an Event |

A fact, its Event, its meter line and its audit entry commit together, or none of them do.

| Rule | What keeps every output in step with the file |
| --- | --- |
| Lineage | Every output carries the digest of the Definition it came from |
| The diff is the change | A deploy compares two Definitions, writes the changelog, and refuses a breaking change unless it ships as a new [Version](/reference/platform.md#version) |
| Pinning | Every caller and every running case stays on the Version it started on |
| Cutover | Every [Interface](/every-product.md) moves to the new Version at once, and a rollback moves them all back |
| Migration | A migration is checked against the live record, and old Versions run until the work pinned to them closes |

Each Customer can extend your file with its own fields, rules and [Workflows](/workflow.md), inside the limits you set.

## Nine subsystems
Every move passes the runtime's gate, and each subsystem has a page of its own.

### Definition and compile
The compiler checks the business: it refuses a Verb with no price, a price below cost, or a step nobody can staff. Specified in [Definition and compile](/definition.md), [the seven patterns](/patterns.md) and [the file](/reference/platform.md#the-file).

### Identity, access and policy
A person, an agent, a key or an app acts for a Customer org under a Role or a mandate. One decision answers every move: allowed, pending, or refused with a cure. Specified in [Identity, access and policy](/identity.md).

### Model and records
Each Customer's records: Nouns, [Relationships](/patterns/headless-saas.md), lifecycles, files and content, with full history. Search, views and metrics are rebuilt from them. Specified in [Model and records](/model.md) and [Headless SaaS](/patterns/headless-saas.md).

### Data and Sources
Sources read live or kept on a schedule, through a [Mapping](/patterns/dataset-api.md#how-a-field-is-filled), and each Customer's own systems as an [Integration](/patterns/headless-saas.md#integrations). Licence terms travel with the data. Specified in [Data and Sources](/data.md) and [Dataset API](/patterns/dataset-api.md).

### Runtime
One gate for every move: identify, decide, price, guard, commit, then act outside. A Workflow waits for weeks without losing its place. Specified in [Runtime](/runtime.md) and [Workflow](/workflow.md).

### Work
Jobs done by agents and people: cases, review, licensed supervision, suppliers, booking, orders and acceptance. Each step runs on the cheapest worker that meets its grade. Specified in [Work](/work.md).

### Commerce
The sell side prices, meters and takes payment from people through Stripe Checkout and from agents inside the call. The [buy side](/commerce/buy-side.md) lets your Customers' agents spend. Specified in [Commerce](/commerce.md).

### Interfaces and distribution
Eleven Interfaces from one file, among them [the landing site, the developer portal and the docs](#faces). Each product is found where people and agents look. Specified in [Interfaces and distribution](/interfaces.md) and [Reference](/reference.md).

### Trust and operations
The managed infrastructure: Test and Live, deploy and rollback, status, security, privacy, tenant operations and brakes on abuse, proved to an outside check. Specified in [Trust and operations](/trust.md).

## What every product can do
Each family is an API, so a person, an agent and any UI reach the same state and moves.

| Family | What a product does with it | Subsystem |
| --- | --- | --- |
| Orgs and members | Customer orgs, members, invites, teams, single sign-on and directory sync, apps acting for a Customer | [Identity](/identity.md) |
| Roles and policy | Custom Roles; permissions per Verb, field and record; mandates for agents; approvals; support access a Customer consents to | [Identity](/identity.md) |
| Records | Nouns and Relationships, full history and restore, import and export, fields each Customer adds | [Model](/model.md) |
| Content and files | Files and media, documents generated from records, drafts, review and publishing, editions and access tiers | [Model](/model.md) |
| Search and views | Search that respects permissions, saved views, metrics and reports | [Model](/model.md) |
| Integrations | Each Customer's own systems, read and written back, with outside truth reconciled | [Data](/data.md) |
| Workflows and state machines | Lifecycles with guarded moves, durable runs, schedules, recurring work and timers | [Runtime](/runtime.md) |
| Events | The change feed, Watches, signed webhooks in and out, live subscriptions | [Runtime](/runtime.md) |
| Agents inside the product | An agent for each Customer, with tools drawn from the Verbs, its own memory and skills, spend brakes and a record of what it did | [Work](/work.md) |
| Cases and outcomes | Intake with conflict checks, quotes, tasks, queues, handoffs, delivery, acceptance and remedy under an Outcome contract | [Work](/work.md) |
| Review and supervision | Adversarial, affirmative, sampled and four-eyes review; licensed sign-off; privilege, ethical walls, retention and legal hold | [Work](/work.md) |
| Suppliers and the people who do the work | Join, verify, match and staff; capacity, booking and track record; orders filled, shipped and returned | [Work](/work.md) |
| Billing and money | Plans, seats, credits, committed use, invoices, outcome prices with holds, splits between payees, client funds held until acceptance | [Commerce](/commerce.md) |
| Payments for your Customers | Each Customer takes payments from its own customers on its own Stripe account, with your fee on each | [Commerce](/commerce.md) |
| Buying with agents | Budgets, mandates, a selection policy, a credential per seller and one receipt stream for a Customer's own agents | [Commerce](/commerce/buy-side.md) |
| Conversations | Delivery sends, notifications, inbound intake into a case, and one conversation per record, with preferences and consent | [Interfaces](/interfaces.md) |
| Customer operations | Provision, suspend, restore, export and erase a Customer; isolation; audit export | [Trust](/trust.md) |

A CRM you sell is a [Headless SaaS](/patterns/headless-saas.md) built from these families.

### The landing site, the portal and the docs
All three come from your file under your brand, and a new Verb lands in all three at once. [The site, the portal and the docs](/interfaces/site-portal-docs.md) specifies each.

### The buy side
Your Customers' agents buy too, under the same one decision. [The buy side](/commerce/buy-side.md) specifies how.

### Where the product stops
Anything outside the product reads it through these hooks: Events, webhooks, entitlements, offers in replies and the UI contracts. It acts through the same Verbs.

A message that delivers what a Customer bought is product; a campaign to someone who never called runs outside, on its Events.

## Seven patterns, one system
[The seven patterns](/patterns.md) share one grammar, gate, decision and receipt; only the core, in bold, and the unit metered change.

They stack: a Dataset API feeds a [Function API](/patterns.md#function-api), which is an agent's tool. Agents and people deliver a [Service API](/patterns.md#service-api), and a Headless SaaS keeps the records. Content sells records by access, and a Marketplace sells any of them from many suppliers.

| Subsystem | [Dataset API](/patterns/dataset-api.md) | [Function API](/patterns.md#function-api) | [Content](/patterns/content.md) | [Agent API](/patterns.md#agent-api) |
| --- | --- | --- | --- | --- |
| Definition | Sources and Mappings | [Functions](/patterns.md#function-api) and prices | items, editions, access tiers | the agent, its tools, its mandate |
| Identity | keys | keys and mandates | members and tiers | the mandate chain |
| Model | the records it serves | input and output | **posts, issues, files, spaces** | the Customer's records and memory |
| Data | **the core** | optional | imports | each Customer's own systems |
| Runtime | refresh | **the core** | scheduled editions | long runs, schedules |
| Work | corrections | escalation to a person | moderation | **brakes, handoffs, proof** |
| Commerce | per answer | per call | subscription, one-off, per read | tokens and minutes |
| Interfaces | all eleven | all eleven | and delivery sends | and an agent card |
| Trust | coverage, freshness, licence | evals | licence, moderation record | traces, spend brakes |
| An agent, end to end | compares offer cards, buys an answer, checks the receipt | quotes, calls, pays per call | pays per read | hires the agent and reads its proof |

| Subsystem | [Headless SaaS](/patterns/headless-saas.md) | [Marketplace](/patterns/marketplace.md) | [Service API](/patterns.md#service-api) |
| --- | --- | --- | --- |
| Definition | Nouns, lifecycles, plans | suppliers, their catalog, split rules | the case, its grades, its staffing |
| Identity | **orgs, members, Roles, approvals** | buyers and suppliers, verified | client orgs, parties without accounts, licensed Roles |
| Model | **the core** | the catalog, stock, ratings | case files, privilege classes |
| Data | each Customer's Integrations | supplier feeds | outside submissions and evidence |
| Runtime | lifecycles, Workflows, Events | order routing | clocks, signals, effects |
| Work | approvals, booking, orders | **orders filled by suppliers, on time** | **the core** |
| Commerce | plans and seats | **the split, payouts, your share** | per accepted outcome, held funds |
| Interfaces | and an app's contracts | and buyer and supplier contracts | and client and worker contracts |
| Trust | audit, residency | supplier risk, fraud | supervision record, evidence |
| An agent, end to end | a member's day and an admin's setup | buys from a supplier, the money splits, contests a bad fill | files a matter, accepts or contests, pays |

Every pattern launches with the site, the portal and the docs.

## Products built on products
Any product can be a Source of another, and each hop keeps its own price and margin. [The patterns](/patterns.md#composition) show the files.

| Chain | What it guarantees when your product is built on another |
| --- | --- |
| Version | The product you build on is pinned, and its breaking changes ship as new Versions |
| Mandate | An agent's spending authority narrows at every hop |
| Settlement | One payment splits to every seller at its printed price |
| Trace | One evidence chain runs from the first call to the last |
| Remedy | An upstream refusal or refund flows into your Outcome contract |