Platform reference

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.

Parameters

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.

POST apis.dev/v1/products/companyfacts/checks

Request

curl https://apis.dev/v1/products/companyfacts/checks \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  --data-binary @definition.ts

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"
    }
  ]
}

CLI

$ npx apis.dev check

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.

Parameters

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; 404 not_found when you own no product by that name.

POST apis.dev/v1/products/companyfacts/plans

Request

curl https://apis.dev/v1/products/companyfacts/plans \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  --data-binary @definition.ts

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
    }
  ]
}

CLI

$ npx apis.dev plan

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.

Parameters

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; 400 with every Problem from When a publish is refused, and nothing that serves changes.

POST apis.dev/v1/products/companyfacts/deploys

Request

curl https://apis.dev/v1/products/companyfacts/deploys \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  --data-binary @definition.ts

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
    }
  ]
}

CLI

$ npx apis.dev deploy

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.

Parameters

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; 404 not_found when there is no Version before.

POST apis.dev/v1/products/companyfacts/rollbacks

Request

curl https://apis.dev/v1/products/companyfacts/rollbacks \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  -X POST

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"
}

CLI

$ npx apis.dev rollback

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.

Parameters

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; 400 missing_param without a value.

PUT apis.dev/v1/products/companyfacts/secrets/FIRMS_KEY

Request

curl https://apis.dev/v1/products/companyfacts/secrets/FIRMS_KEY \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  -X PUT \
  --json '{ "value": "<credential>" }'

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_8d1c4047d8d1e1de3b25

{
  "key": "FIRMS_KEY",
  "updatedAt": "2026-10-24T09:00:00Z"
}

CLI

$ npx apis.dev secrets set FIRMS_KEY

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.

Parameters

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; 404 not_found for an id your product never answered.

GET apis.dev/v1/products/companyfacts/calls/req_3cd59a9a1ede10c5bf21

Request

curl https://apis.dev/v1/products/companyfacts/calls/req_3cd59a9a1ede10c5bf21 \
  -H "Authorization: Bearer $APIS_DEV_TOKEN"

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
}

CLI

$ npx apis.dev calls req_3cd59a9a1ede10c5bf21

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.

Parameters

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 answers it, without its reply.

Errors: 401 invalid_key.

GET apis.dev/v1/products/companyfacts/logs

Request

curl https://apis.dev/v1/products/companyfacts/logs \
  -H "Authorization: Bearer $APIS_DEV_TOKEN" \
  -N

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}

CLI

$ npx apis.dev logs --follow

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.

Parameters

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.

GET apis.dev/v1/products/companyfacts/keys

Request

curl https://apis.dev/v1/products/companyfacts/keys \
  -H "Authorization: Bearer $APIS_DEV_TOKEN"

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.

Parameters

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; 400 invalid_param for a period that is not a month.

GET apis.dev/v1/products/companyfacts/usage?period=2026-10

Request

curl https://apis.dev/v1/products/companyfacts/usage?period=2026-10 \
  -H "Authorization: Bearer $APIS_DEV_TOKEN"

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.

Parameters

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.

GET apis.dev/v1/products/companyfacts/payouts

Request

curl https://apis.dev/v1/products/companyfacts/payouts \
  -H "Authorization: Bearer $APIS_DEV_TOKEN"

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

Commands

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.

Codes

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

What a change reaches

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.

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 is the same file as JSON Schema, a $defs entry per block.

The file itself

Keys

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: <name>.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

Keys

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

Keys

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

Keys

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

Keys

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

Keys

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

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.
A move enters its past-form state and writes that Event: open enters opened and writes Deal.opened; win enters won; lose enters lost.
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.
Noun.verb becomes verbNoun over MCP and in the SDK, plural for a list: Deal.open is openDeal, Company.search is searchCompanies.
A Trigger names its Verb in full: 'Deal.won': 'Deal.kickoff'.
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.

One name per Verb

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 lets an agent build: fetch /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.

Tools

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.

Words

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
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
Customer The party that buys from you, and the tenant its own data belongs to. Headless SaaS
Event A Verb's past form, written when it happens: Deal.opened, Company.updated. What every product gets
Function How a Verb runs: code, generative, agentic or human; the caller gets the same Action back whichever it is. Patterns
Host Your own Domain: every Interface 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
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
Key The credential a Customer presents on a call; every call checks it, and no record ever holds it.
Mapping How a Source's fields become your Noun's fields, ranked when more than one Source can answer. Dataset API
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
Offer What you sell, at a price (zero allowed: free is a price), on terms, made by you. Patterns
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
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
Provenance Who wrote a value and on what basis: Stated, Inferred or Observed; Observed wins for facts. Dataset API
Relationship A link from one Noun to another, written with an arrow, -> or <-, and read from either side. Headless SaaS
Role A seat that owns a set of work, and holds the Permissions for it. Headless SaaS
Source What a product draws on and did not build: data, a service or people; a Mapping reads its records into your Noun. Dataset API
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
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
Trigger What starts work: an Event, a schedule, or a Thing entering a state. Patterns
Verb What can be done to a Noun: a read, a create, a lifecycle move, or a Function. Patterns
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
Webhook What sends each change your Customer picks to a URL as a signed request, retried until it lands. What every product gets
Workflow Durable code, a state machine, or both: the private body of one Action. Workflow

Platform APICopy Anchor Link

Check a fileCopy Anchor Link

Plan a deployCopy Anchor Link

Deploy a VersionCopy Anchor Link

Roll backCopy Anchor Link

Set a secretCopy Anchor Link

Read one callCopy Anchor Link

Follow the callsCopy Anchor Link

List keysCopy Anchor Link

Read usageCopy Anchor Link

List paymentsCopy Anchor Link

PublishCopy Anchor Link

The apis.dev commandCopy Anchor Link

When a publish is refusedCopy Anchor Link

ChangesCopy Anchor Link

The fileCopy Anchor Link

The file itselfCopy Anchor Link

SourceCopy Anchor Link

NounCopy Anchor Link

VerbCopy Anchor Link

TriggerCopy Anchor Link

OfferCopy Anchor Link

RulesCopy Anchor Link

NamesCopy Anchor Link

Build with an agentCopy Anchor Link

ConceptsCopy Anchor Link

Platform API

Check a file

Plan a deploy

Deploy a Version

Roll back

Set a secret

Read one call

Follow the calls

List keys

Read usage

List payments

Publish

The apis.dev command

When a publish is refused

Changes

The file

The file itself

Source

Noun

Verb

Trigger

Offer

Rules

Names

Build with an agent

Concepts