How APIs.Dev works
Open in
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.
definition.ts
enters here
compiles to routes, state machines, prices, terms, every Interface, the site, the portal and the docs
- 2Identity, access and policywho acts, for whom, and one decision on every move
- 3Model and recordswhat each Customer keeps, and the views rebuilt from it
- 4Data and Sourceswhat the product draws on, and outside truth reconciled
- 7Commerceselling on Stripe, and buying with agents under a mandate
- 8Interfaces and distributionevery 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
hands off work, and is watched and proved
- 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, 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, 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, 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 |
| Pinning | Every caller and every running case stays on the Version it started on |
| Cutover | Every Interface 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, inside the limits you set.
Nine subsystems
Every move passes the runtime's gate. A subsystem with pages of its own links to them.
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 the seven patterns and 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.
Model and records
Each Customer's records: Nouns, Relationships, lifecycles, files and content, with full history. Search, views and metrics are rebuilt from them. Specified in Headless SaaS.
Data and Sources
Sources read live or kept on a schedule, through a Mapping, and each Customer's own systems as an Integration. Licence terms travel with the data. Specified in Dataset API.
Runtime
One gate for every move: identify, decide, price, guard, commit, then act outside. A Workflow waits for weeks without losing its place.
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.
Commerce
The sell side prices, meters and takes payment from people through Stripe Checkout and from agents inside the call. The buy side lets your Customers' agents spend.
Interfaces and distribution
Eleven Interfaces from one file, among them the landing site, the developer portal and the docs. Each product is found where people and agents look. Specified in What every product gets and Reference.
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.
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 |
| Roles and policy | Custom Roles; permissions per Verb, field and record; mandates for agents; approvals; support access a Customer consents to | Identity |
| Records | Nouns and Relationships, full history and restore, import and export, fields each Customer adds | Model |
| Content and files | Files and media, documents generated from records, drafts, review and publishing, editions and access tiers | Model |
| Search and views | Search that respects permissions, saved views, metrics and reports | Model |
| Integrations | Each Customer's own systems, read and written back, with outside truth reconciled | Data |
| Workflows and state machines | Lifecycles with guarded moves, durable runs, schedules, recurring work and timers | Runtime |
| Events | The change feed, Watches, signed webhooks in and out, live subscriptions | Runtime |
| 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 |
| Cases and outcomes | Intake with conflict checks, quotes, tasks, queues, handoffs, delivery, acceptance and remedy under an Outcome contract | Work |
| Review and supervision | Adversarial, affirmative, sampled and four-eyes review; licensed sign-off; privilege, ethical walls, retention and legal hold | Work |
| Suppliers and the people who do the work | Join, verify, match and staff; capacity, booking and track record; orders filled, shipped and returned | Work |
| Billing and money | Plans, seats, credits, committed use, invoices, outcome prices with holds, splits between payees, client funds held until acceptance | Commerce |
| Payments for your Customers | Each Customer takes payments from its own customers on its own Stripe account, with your fee on each | Commerce |
| Buying with agents | Budgets, mandates, a selection policy, a credential per seller and one receipt stream for a Customer's own agents | Commerce |
| Messages | Delivery sends, notifications, inbound intake into a case, and one thread per case, with preferences and consent | Interfaces |
| Customer operations | Provision, suspend, restore, export and erase a Customer; isolation; audit export | Trust |
A CRM you sell is a Headless SaaS built from these families.
The landing site, the portal and the docs
All three are generated from your file under your brand, and a new Verb lands in all three at the same deploy.
| Interface | What it holds |
|---|---|
| Landing site | The promise, examples that run, the catalog and price page with its machine twin, the offer card, terms, privacy and the refund rule from your file, status, the changelog, sign-up |
| Developer portal | Sign-in and single sign-on, Test and Live keys, usage with alerts and spend caps, plan changes and cancellation, payment methods and tax details, invoices and receipts, members, connected apps, webhook addresses and their delivery log, request logs, mandates and budgets for agents, disputes, export and deletion, a way to reach you |
| The portal for suppliers | A second kind of account, in a Marketplace or a Service API: verification, the supplier's catalog, payout onboarding on Stripe, payouts and tax forms |
| Docs | A quickstart per Interface, guides, a reference page per Verb and Noun, an error page per refusal with its cure, try-it with sandbox keys, docs pinned per Version with migration guides, search, llms.txt |
Every move in the portal is a Verb first.
The buy side
Your Customers' agents buy too, under the same one decision.
| Part | What it does |
|---|---|
| Budget | Funded on Stripe, then split per agent, task and seller |
| Mandate | Scoped, budgeted, time-boxed and revocable, and checked by the seller before it serves |
| Selection policy | Allowed sellers, price and proof thresholds, and an approval above a limit |
| Credentials | One per seller, held for the agent, never in its prompt |
| Receipts | One signed stream across every seller, verified, reconciled, exported to the Customer's books, and disputed with the receipt |
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 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, which is an agent's tool. Agents and people deliver a 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 | Function API | Content | Agent API |
|---|---|---|---|---|
| Definition | Sources and Mappings | Functions 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 | Marketplace | 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 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 |