--- title: "Platform reference" url: /reference/platform --- # Platform reference > How your file becomes a live API: the calls and commands that check, plan and deploy it, and every key it can hold. ## Platform API Every command is a call to the platform API at `https://apis.dev/v1`, signed with `APIS_DEV_TOKEN`; a refusal is a Problem like any API's. One deploy publishes the file as a Version, and every Interface moves to it at once. ### Check a file `POST /v1/products/{name}/checks` · `npx apis.dev check` Checks a file against the schema and the publish rules. It changes nothing, and needs no account. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `file` string, in body, required: Your whole `definition.ts`, as text. For example `@definition.ts` in curl. Returns `ok`, and every Problem with its code, its JSON Pointer `at` and what to fix; `definition` holds the compiled file when `ok` is true. Errors: none of its own. A file that does not check answers 200 with its Problems, each a code from [When a publish is refused](#publish-errors). **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/checks \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ --data-binary @definition.ts ``` **CLI** ```sh title="CLI" $ npx apis.dev check ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_f5a14fbf78907e246b5c { "ok": false, "problems": [ { "code": "unknown_source", "at": "/Company/employees/from", "message": "Company.employees reads firm, which sources does not hold" } ] } ``` ### Plan a deploy `POST /v1/products/{name}/plans` · `npx apis.dev plan` Answers what deploying a file would change against the Version now live: each Verb, its price and its names, and every change, marked when it breaks a caller. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `file` string, in body, required: Your whole `definition.ts`, as text. For example `@definition.ts` in curl. Returns `verbs`, each with its price, MCP tool and CLI command, and `changes`, each with `breaking`. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 404 [`not_found`](/reference.md#not_found) when you own no product by that name. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/plans \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ --data-binary @definition.ts ``` **CLI** ```sh title="CLI" $ npx apis.dev plan ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_3379506a7f8f750bbcf4 { "ok": true, "verbs": [ { "verb": "Company.get", "price": 0.003, "mcp": "getCompany" }, { "verb": "Company.search", "price": 0.005, "mcp": "searchCompanies" } ], "changes": [ { "change": "price", "at": "Company.get", "from": 0.002, "to": 0.003, "breaking": true } ] } ``` ### Deploy a Version `POST /v1/products/{name}/deploys` · `npx apis.dev deploy` Publishes a file as a new Version. Every Interface moves to it at once, and a run in flight finishes on the Version it started on. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `file` string, in body, required: Your whole `definition.ts`, as text. For example `@definition.ts` in curl. - `Idempotency-Key` string, header, optional: Sent again on a retry, so one file publishes once. Returns the Version, its digest, the address it answers on and the changes it made. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 400 with every Problem from [When a publish is refused](#publish-errors), and nothing that serves changes. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/deploys \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ --data-binary @definition.ts ``` **CLI** ```sh title="CLI" $ npx apis.dev deploy ``` ```http title="Response" HTTP/1.1 201 Created Content-Type: application/json X-Request-Id: req_bd196c92ccf8d1dfb3bc { "version": "v2", "digest": "f1b536fb8c49", "url": "https://companyfacts.apis.dev", "previous": "v1", "changes": [ { "change": "price", "at": "Company.get", "from": 0.002, "to": 0.003, "breaking": true } ] } ``` ### Roll back `POST /v1/products/{name}/rollbacks` · `npx apis.dev rollback` Moves every Interface back to the Version before, as one. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. Returns the Version now live and the one it replaced. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 404 [`not_found`](/reference.md#not_found) when there is no Version before. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/rollbacks \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ -X POST ``` **CLI** ```sh title="CLI" $ npx apis.dev rollback ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_bc1acd9f19a060624e73 { "version": "v1", "digest": "be8c6389ef6c", "url": "https://companyfacts.apis.dev", "replaced": "v2" } ``` ### Set a secret `PUT /v1/products/{name}/secrets/{key}` · `npx apis.dev secrets set FIRMS_KEY` Stores a Source's credential for `secret()`. No reply, page or log shows it again. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `key` string, in path, required: The name `secret()` reads. For example `FIRMS_KEY`. - `value` string, in body, required: The credential itself. Returns the secret by its name and when it was set, never its value. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 400 [`missing_param`](/reference.md#missing_param) without a value. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/secrets/FIRMS_KEY \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ -X PUT \ --json '{ "value": "" }' ``` **CLI** ```sh title="CLI" $ npx apis.dev secrets set FIRMS_KEY ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_8d1c4047d8d1e1de3b25 { "key": "FIRMS_KEY", "updatedAt": "2026-10-24T09:00:00Z" } ``` ### Read one call `GET /v1/products/{name}/calls/{id}` · `npx apis.dev calls` One call by the request id its reply carried: what was asked, what it answered, what it cost and what it ran. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `id` string, in path, required: The `X-Request-Id` of the call. Returns the call: its Verb, input, status, reply, price, Key and time. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 404 [`not_found`](/reference.md#not_found) for an id your product never answered. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/calls/req_3cd59a9a1ede10c5bf21 \ -H "Authorization: Bearer $APIS_DEV_TOKEN" ``` **CLI** ```sh title="CLI" $ npx apis.dev calls req_3cd59a9a1ede10c5bf21 ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_320fae8b65bca1866c66 { "id": "req_3cd59a9a1ede10c5bf21", "verb": "Company.get", "input": { "domain": "acme.com" }, "status": 200, "output": { "domain": "acme.com", "employees": 240, "sector": "Software" }, "cost": { "price": 0.002, "currency": "USD" }, "key": "companyfacts_test_NNTT…", "at": "2026-10-24T09:00:00Z", "ms": 39 } ``` ### Follow the calls `GET /v1/products/{name}/logs` · `npx apis.dev logs --follow` Every call as it is answered, as a stream of Server-Sent Events, one `call` event each. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `verb` string, in query, optional: Only this Verb's calls. For example `Company.get`. Returns a `text/event-stream`; each event holds a call as [Read one call](#platform-calls) answers it, without its reply. Errors: 401 [`invalid_key`](/reference.md#invalid_key). **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/logs \ -H "Authorization: Bearer $APIS_DEV_TOKEN" \ -N ``` **CLI** ```sh title="CLI" $ npx apis.dev logs --follow ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: text/event-stream event: call id: req_3cd59a9a1ede10c5bf21 data: {"verb":"Company.get","status":200,"price":0.002} ``` ### List keys `GET /v1/products/{name}/keys` Your Test keys, and the Live keys your Customers hold, without their secrets. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `env` string, in query, optional: `test` or `live`. Returns a list: each Key by its id, its environment, the start of its secret and who holds it. Errors: 401 [`invalid_key`](/reference.md#invalid_key). **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/keys \ -H "Authorization: Bearer $APIS_DEV_TOKEN" ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_62678a7a0339e43505a7 { "items": [ { "id": "key_1", "env": "test", "starts": "companyfacts_test_NNTT", "customer": null, "createdAt": "2026-10-24T09:00:00Z" } ], "total": 1, "next": null } ``` ### Read usage `GET /v1/products/{name}/usage` Calls and revenue by Verb for a period, and by Customer with `?by=customer`. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `period` string, in query, optional: A month, `YYYY-MM`; the current one when absent. - `by` string, in query, optional: `verb` or `customer`. Returns the period's calls and revenue, line by line, in the Offer's currency. Errors: 401 [`invalid_key`](/reference.md#invalid_key); 400 [`invalid_param`](/reference.md#invalid_param) for a period that is not a month. **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/usage?period=2026-10 \ -H "Authorization: Bearer $APIS_DEV_TOKEN" ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_d37442816c70008023a6 { "period": "2026-10", "currency": "USD", "lines": [ { "verb": "Company.get", "calls": 12400, "price": 0.002, "revenue": 24.8 }, { "verb": "Company.search", "calls": 1300, "price": 0.005, "revenue": 6.5 } ] } ``` ### List payments `GET /v1/products/{name}/payouts` The payments your connected Stripe account received, each beside the calls it paid for. - `name` string, in path, required: The product's name, as the file's `name` gives it. For example `companyfacts`. - `period` string, in query, optional: A month, `YYYY-MM`. Returns a list: each payment by its Stripe id, its Customer, its amount and the calls behind it. Errors: 401 [`invalid_key`](/reference.md#invalid_key). **curl** ```sh title="Request" curl https://apis.dev/v1/products/companyfacts/payouts \ -H "Authorization: Bearer $APIS_DEV_TOKEN" ``` ```http title="Response" HTTP/1.1 200 OK Content-Type: application/json X-Request-Id: req_965da285f7dc14481f8d { "items": [ { "payment": "py_1QxAcme", "customer": "cus_Acme", "amount": 31.3, "currency": "USD", "period": "2026-10", "calls": 13700 } ], "next": null } ``` ## Publish One command publishes the file; a refused publish changes nothing that serves, and a change reaches each caller by the rules below. ### The apis.dev command - `npx apis.dev init dataset-api`: Starts a folder with a `definition.ts` for the pattern you name: `dataset-api`, `headless-saas`, `function-api`, `agent-api` or `service-api`. - `npx apis.dev dev`: Serves every Interface on localhost against your Test twin, and reloads on every save. - `npx apis.dev check`: Checks the file against the schema and the publish rules, and prints every Problem with its code and `at`. - `npx apis.dev plan`: Prints what the next deploy changes: each Verb, each price, your margin, and any breaking change. - `npx apis.dev deploy`: Publishes the file as a new Version, every Interface at once; `--json` prints the result as data. - `npx apis.dev secrets set FIRMS_KEY`: Stores a Source's credential for `secret()`: never in the file, and never shown to a Customer. - `npx apis.dev logs --follow`: Streams every call as it is answered: its Verb, status, price and request id. - `npx apis.dev calls req_3cd59a9a1ede10c5bf21`: Prints one call by its request id: its input, its reply, its price and what it ran. - `npx apis.dev rollback`: Moves every Interface back to the Version before, as one. - `npx apis.dev events listen --forward localhost:3000/hooks`: Sends each Event to a local URL, signed, so a receiver is tested before a Watch points at it. - `APIS_DEV_TOKEN`: Signs every command in without a browser, for CI and for agents. ### When a publish is refused A refused publish answers coded Problems, each with a JSON Pointer `at` into the file and its fix, and nothing that serves changes. `npx apis.dev check --json` prints the same list. - `invalid_definition` at `/Company/employees`: The file does not parse as data inside `define()`, or a key does not fit the schema. Fix the key at `at`; `/definition.schema.json` holds every key. - `unpriced_verb` at `/Deal/stage/win`: A served Verb has no price, no plan covers it, and no outcome charges for its Thing. Price it in `offer`, such as `'Deal.win': 0`, or name a plan whose `includes` covers it. - `reserved_path` at `/Company/docs`: A Verb would take a path the API serves itself. Rename the Verb; the reserved paths are listed with the rules of the file. - `unknown_source` at `/Company/domain/from`: `from` names a Source that `sources` does not hold. Add the Source under `sources`, or name one that is there. - `unknown_verb` at `/on/'Deal.won'`: A Trigger or a price names a Verb no Noun has. Name the Verb in full, `Noun.verb`, as the Noun declares it. - `one_sided_relationship` at `/Deal/company`: A Relationship names an other side that does not point back. Give the other Noun its side: `deals: '<-Deal.company'` for `company: '->Company.deals'`. - `duplicate_verb` at `/Deal/stage/open`: Two Verbs on one Noun share a name, or two serve one route. Rename one of them; every Verb is used once. - `bad_state` at `/Deal/stage/win`: A move names a state no move enters. Name a state a move enters: a move's past form, such as `qualified`. - `bad_type` at `/Company/employees`: A field's type is not one of the types, or its marks are out of order. Write a type, then `?`, `!` or `#`: `'number?'`, `'url!#'`. - `below_cost` at `/offer/'Lead.get'`: A Verb's price is below what its Sources cost you for one call. Raise the price above the cost the Problem names, or read a Source that costs less. ### Changes - `Every deploy`: A Version with a digest; `Api-Version` on a request pins one. - `A new Noun, Verb, field or plan`: Reaches every caller at once. - `A removal, a rename, a narrowed type, a higher price per call`: Deploy names it as breaking, and each Key keeps the Version it first called until it sends `Api-Version`. - `A lower price per call`: Reaches every caller at once. - `A plan's new price`: Reaches each subscriber at renewal, with a Stripe notice; `keep: true` keeps current subscribers on the old price. - `A run in flight`: Stays on the Version it started on, to its end. - `npx apis.dev rollback`: Moves every Interface back to the Version before, as one. ```sh title="Terminal" $ npx apis.dev deploy ! breaking: Company.domain is renamed to Company.website each Key keeps v3 until it sends Api-Version: v4 ✓ Team 49 → 59: 3 Customers move at their next renewal ✓ published v4 to https://pipeline.apis.dev ``` ## The file The file is `definition.ts`: `import { define } from 'apis.dev'`, then `export default define({ … })`. Sources go under `sources`, each Noun at a capitalised key with its Verbs inside it, Triggers under `on`, and prices under `offer`. [`/definition.schema.json`](/definition.schema.json) is the same file as JSON Schema, a `$defs` entry per block. ### The file itself - `import { define } from 'apis.dev'`: The file is typed: `define()` checks every key as you write it, and each call you use is imported beside it. - `name: 'companyfacts'`: The CLI command, the npm and PyPI package, the SDK class and the MCP server name; deploy asks for it when it is missing. - `domain: 'companyfacts.apis.dev'`: The Host every Interface answers on: `.apis.dev` from the first deploy, or a Domain of your own, which deploy checks once by a TXT record. - `/** Any company by its domain. */`: A comment above the file, a Noun, a field or a Verb is its description on every Interface; the file's own is the pitch. ### Source - `sources: { firms: { origin: 'https://firms.example.com' } }`: The Sources you draw on, each by the name `from` uses, at its origin. - `key: secret('FIRMS_KEY')`: A Source's credential, set with `npx apis.dev secrets set FIRMS_KEY`: never in the file, never shown to a Customer. - `{ api: 'companyfacts.apis.dev' }`: A Source that is another API product, read through its own Verbs. - `cost: { 'Company.get': 0.002 }`: What each of the Source's calls costs you: deploy prints your margin per Verb, and a price below it is refused. - `{ system: 'crm', scope: 'customer' }`: An Integration: each Customer's own system. - `{ type, from, map }`: A field a Source writes: its type, the Source, and the Source's own field. - `from: [a, b]`: A ranked `from`: each writer in turn, until one answers. - `schedule: 'every Mon 06:00'`: When a kept copy is read again, in the time grammar every schedule uses. ### Noun - `Company`: A capitalised key is a Noun: the shape you promise, with its fields and its Verbs. - `'string'`, `'number'`, `'boolean'`, `'date'`, `'url'`, `'decimal(12,2)'`: A field's type, as a lower-case word. - `?`, `!`, `#`: After a type: optional; required and unique; indexed. `'url!#'` is a key the record also answers at. - `'->Company.deals'`, `'<-Deal.company'`: A Relationship: `->` points at another Noun and `<-` reads one back; after the dot is its other side. - `{ type: 'url!#', example: 'acme.com' }`: A field as an object: its type, and `example:`, the field's example in the docs, OpenAPI, the SDK and Try it. - `{ type: 'string?', from: 'Company.research' }`: A field whose `from` names a Verb keeps that Verb's latest output, stamped Inferred. ### Verb - `stage: { open: [], qualify: 'opened' }`: Lifecycle moves: each key is a Verb, and its value the state it moves from; `[]` is no state, so `open` creates the Thing. - `lose: ['opened', 'qualified']`: A move allowed from any of these states. - `win: { in: 'qualified', role: 'manager' }`: A move with the state it moves from and the Role that may call it; `run` gives it a Function or a Workflow. - `agentic('Find the head of sales at {domain}')`: A Function: `code`, `generative`, `agentic` or `human`. A key whose value is one is a Verb; a Verb with no comment gets one written from its Noun and kind. - `{ returns: { summary: 'string' }, input, tools, role }`: A Function's options: `returns` types its output everywhere, `input` its input on a Noun with no records, `tools` the Sources an agent may use, `role` who does a human one. - `'{domain}'`, `'{company.name}'`: In a prompt, a field of the Thing, or a field across a Relationship. - `workflow(fn)`: A Workflow as durable code: a key whose value is one is a Verb, the work's body; `$` gives each step. - `machine({ initial, states })`: A Workflow as a state machine: each state's `entry`, its `on` events and its `after` timers. - `on: { approve: { target: 'approved', role: 'manager' } }`: A machine's event: a Verb on the Noun, with its target state, the Role that may send it, and a `guard`. ### Trigger - `on: { 'Deal.won': 'Deal.kickoff' }`: A Trigger: when the Event happens, the Verb it names starts. Nothing else in the file starts work. - `on: { 'every Mon, Wed, Fri 09:00': 'Meeting.book' }`: A Trigger on a schedule, run once per Customer, in that Customer's timezone; a duration is `'2d'` or `'30m'`. ### Offer - `offer: { 'Company.get': 0.002 }`: A `Noun.verb` key is a price per call; free is an explicit 0. A price applies on every plan unless the plan's `includes` covers it. - `Team: { month: 49, seats: 5, seat: 9 }`: A capitalised key is a plan: a price a month for its seats, and `seat` for each seat past them; `year`, `trial` and `keep` are its other keys. - `includes: { 'Deal.open': 1000 }`: The calls a plan covers each month, at price 0; a plan at month 0 stops at them, and a paid plan draws the price past them. - `Enterprise: { contact: true }`: A plan you sell by conversation: /pricing shows it, and Get started opens a contact form. - `free: { 'Company.get': 100 }`: Calls each month that cost nothing, on any plan or none. - `credits: [10, 50, { pay: 200, get: 220 }]`: The credit packs Checkout sells; `{ pay, get }` is a pack with a bonus. - `keyPrefix: 'cf'`: The prefix of every Key: `cf_test_…` and `cf_live_…`, then 30 characters and a checksum; with none, the file's name. - `'Company.watch': { month: 0.1 }`: A price by the month on one Verb, such as a Watch on one record. - `{ per1000Tokens, perMinute }`: A price by consumption: per 1,000 tokens and per minute. - `{ price, when, accept, acceptWithin, remedy }`: A price by outcome: charged once, when the Thing enters `when`; a rejected one gets its remedy: `redo`, `refund` or `credit`. ### Rules 1. A Noun whose fields name a Source in `from` gets `get` by its `#` key and `search` by a field; a Noun your Customers write, or an Integration holds, gets create, get, list, update and delete. 2. A move enters its past-form state and writes that Event: `open` enters `opened` and writes `Deal.opened`; `win` enters `won`; `lose` enters `lost`. 3. Every Verb you write, a move, a Function or a machine event, has a price, a plan or an outcome, or the publish is refused; a generated Verb serves when one covers it. A plan covers the Verbs it leaves unpriced, and an outcome every Verb of its Thing. 4. `Noun.verb` becomes `verbNoun` over MCP and in the SDK, plural for a list: `Deal.open` is `openDeal`, `Company.search` is `searchCompanies`. 5. A Trigger names its Verb in full: `'Deal.won': 'Deal.kickoff'`. 6. A Verb that an `on` line starts and that names no `role` is internal: it serves no path, tool or command, and a direct call answers 404 `no_route`; while it runs, the Thing is in its activity state, `drafting`. A Verb may not take a path the API serves itself. Those are `/`, `/mcp`, `/docs` or a path under it, `/openapi.json`, `/llms.txt`, `/pricing`, `/.well-known/agents.json`, `/sdk`, `/batch`, `/dashboard`, `/actions`, `/events`, `/watches` and `/checkout`. Every `{name}` in a path is a declared parameter, and every Verb's name is lowerCamelCase and used once. ### Names A Verb `Noun.verb` is `verbNoun` over MCP, in the TypeScript SDK and on its docs page, the Noun plural when it answers a list, and `verb_noun` in Python. In the CLI it is the API's name, the Noun in the plural, then the Verb. The SDK takes the `#` key first and everything else as one object. The Event it writes is its past form. - `Company.get`: REST `GET /companies/{domain}` · MCP `getCompany` · TypeScript `api.getCompany()` · Python `api.get_company()` · CLI `companyfacts companies get` - `Company.search`: REST `GET /companies?sector=` · MCP `searchCompanies` · TypeScript `api.searchCompanies()` · Python `api.search_companies()` · CLI `companyfacts companies search` - `Deal.open`: REST `POST /deals` · MCP `openDeal` · TypeScript `api.openDeal()` · Python `api.open_deal()` · CLI `pipeline deals open` · Event `Deal.opened` - `Deal.win`: REST `POST /deals/{id}/win` · MCP `winDeal` · TypeScript `api.winDeal()` · Python `api.win_deal()` · CLI `pipeline deals win` · Event `Deal.won` - `Deal.approve`: REST `POST /deals/{id}/approve` · MCP `approveDeal` · TypeScript `api.approveDeal()` · Python `api.approve_deal()` · CLI `pipeline deals approve` · Event `Deal.approved` - `Company.summarize`: REST `POST /companies/{domain}/summarize` · MCP `summarizeCompany` · TypeScript `api.summarizeCompany()` · Python `api.summarize_company()` · CLI `summaries companies summarize` · Event `Company.summarized` - `Text.translate`: REST `POST /texts/translate` · MCP `translateText` · TypeScript `api.translateText()` · Python `api.translate_text()` · CLI `summaries texts translate` · Event `Text.translated` ## Build with an agent The docs MCP at [`/mcp`](/mcp.md) lets an agent build: fetch [`/llms.txt`](/llms.txt), write `definition.ts`, call `check` until it answers no Problems, then `deploy`. `check` and `plan` need no account; `deploy` signs in with GitHub through OAuth. - `search`: Finds a page or a section of these docs by words. - `fetch`: Reads a page, or one of its sections, as Markdown. - `check`: Takes a `definition.ts` and answers the compiled Definition, or every Problem with its code and `at`. - `plan`: Answers what deploying the file would change: its Verbs, prices, margins and breaking changes. - `deploy`: Publishes the file to your own domain once `check` answers no Problems, signed in with GitHub through OAuth. ## Concepts Every word the docs use for a part of the platform, in one sentence each. - Action: What a Verb call answers: done, a 200 or 201 with its record; Refused, a 409; or Pending, a 202 with where to poll. [Workflow](/workflow.md#the-lifecycle) - API product: Everything around an API's few lines of code, on your own domain, with each part reading your one file. [What every product gets](/every-product.md) - Customer: The party that buys from you, and the tenant its own data belongs to. [Headless SaaS](/patterns/headless-saas.md) - Event: A Verb's past form, written when it happens: `Deal.opened`, `Company.updated`. [What every product gets](/every-product.md#build) - Function: How a Verb runs: code, generative, agentic or human; the caller gets the same [Action](/workflow.md#the-lifecycle) back whichever it is. [Patterns](/patterns.md#function-api) - Host: Your own Domain: every [Interface](/every-product.md) of the API answers there, and every link stays there. - Integration: A Source bound to credentials, yours or each Customer's own, that reads from and writes back to their system. [Headless SaaS](/patterns/headless-saas.md#integrations) - Interface: One way a person or an agent reaches a product on its own domain: the API, CLI, MCP, SDK and docs among them. [What every product gets](/every-product.md) - Key: The credential a Customer presents on a call; every call checks it, and no record ever holds it. - Mapping: How a [Source](/patterns/dataset-api.md#how-a-field-is-filled)'s fields become your Noun's fields, ranked when more than one Source can answer. [Dataset API](/patterns/dataset-api.md#how-a-field-is-filled) - Meter: Counts each priced call, token and minute once, so a retried request counts once. - Noun: A type of Thing, with its fields, its Verbs, and its lifecycle. [Patterns](/patterns.md#the-blocks) - Offer: What you sell, at a price (zero allowed: free is a price), on terms, made by you. [Patterns](/patterns.md#the-blocks) - Outcome contract: The terms on an Offer that make you warrant a Service's result: what done is, who accepts it, and the remedy. [Patterns](/patterns.md#service-api) - Price: The posted price of one call that returns a result: the same number in `X-Cost`, on `/pricing` and on the bill. - Problem: The error document a failed call answers: the RFC 9457 fields plus a stable machine code. [Reference](/reference.md#errors) - Provenance: Who wrote a value and on what basis: Stated, Inferred or Observed; Observed wins for facts. [Dataset API](/patterns/dataset-api.md#how-a-field-is-filled) - Relationship: A link from one Noun to another, written with an arrow, `->` or `<-`, and read from either side. [Headless SaaS](/patterns/headless-saas.md) - Role: A seat that owns a set of work, and holds the Permissions for it. [Headless SaaS](/patterns/headless-saas.md) - Source: What a product draws on and did not build: data, a service or people; a [Mapping](/patterns/dataset-api.md#how-a-field-is-filled) reads its records into your Noun. [Dataset API](/patterns/dataset-api.md#how-a-field-is-filled) - Test key: A Key whose calls stay in the Test twin and never bill; the first deploy prints one, and a Live key answers the same. [Start a Dataset API](/quickstart/dataset-api.md#call-it) - Test twin: The separate space a Test Key calls into; its books never post and it never touches Live records. - Thing: An instance of one or more Nouns, with an identity and a current state. [Patterns](/patterns.md#service-api) - Trigger: What starts work: an Event, a schedule, or a Thing entering a state. [Patterns](/patterns.md#the-blocks) - Verb: What can be done to a Noun: a read, a create, a lifecycle move, or a Function. [Patterns](/patterns.md#the-blocks) - Version: One published digest of the file; a Customer pinned to it keeps its behaviour until it moves. - Watch: A standing pick of Events, delivered somewhere: `POST /watches` makes one, and a webhook is a Watch to a URL. [Reference](/reference.md#events) - Webhook: What sends each change your Customer picks to a URL as a signed request, retried until it lands. [What every product gets](/every-product.md#build) - Workflow: Durable code, a state machine, or both: the private body of one Action. [Workflow](/workflow.md)