---
title: "The site, the portal and the docs"
url: /interfaces/site-portal-docs
---

# The site, the portal and the docs

> The three products every launch includes: one that sells, one that runs each account and one that teaches, generated from one file under your brand.

Every product launches with a landing site that sells it, a developer portal that runs each account, and docs that teach it. They come from the file, under your brand, and never drift from it.

## One file, three products
Each is specified as a product of its own, with its parts, paths and quality bar. Seven rules hold for all three.

| Rule | What holds |
| --- | --- |
| Generated | Every page and screen reads the [Definition](/reference/platform.md#definition); a new Verb lands on all three at the same deploy |
| Your brand | Your name, logo, colours and Domain; no platform name on any page, email or receipt |
| Overridable | Any part can be your own page or component; the parts you leave stay generated and stay in step |
| A machine twin | Each page has a Markdown or JSON twin an agent reads instead |
| A Verb first | Every move a screen offers is a Verb a [Key](/reference/platform.md#key), a token or a mandate can call, so an agent finishes it with no UI |
| One price source | Every price and term printed on any of them comes from the Offer, never typed |
| Events | Visits, sign-ups, Try it calls and unmet searches are Events, read across the seam |

Site tests, tickets and campaigns run outside the product, on these Events.

## The landing site
The landing site sells the product to a person who has never called it. An agent that asks `/` for JSON gets the root JSON: the name, the Verbs and the other registers.

| Part | What it shows |
| --- | --- |
| The hero | The file's name and its pitch, the comment above the file, with Get started |
| Try it | Each Verb with its example, called live with a Test key the page mints |
| The catalog | Every Offer, and in a [Marketplace](/patterns/marketplace.md) every supplier's items, each with its price |
| Pricing | A card per plan, each price per call, the free calls and the credit packs, with `/pricing` as its twin |
| The offer card | [Price](/reference/platform.md#price), terms, the refund rule and the [Verifier](/reference/platform.md#verifier)'s record, the same card agents read |
| Terms | The terms, privacy and refund rule, rendered from the file and versioned with it |
| Status | Each [Interface](/every-product.md)'s state and every incident, with its start and end |
| The changelog | Each [Version](/reference/platform.md#version)'s diff, in words, with the breaking changes first |
| Pages answer engines read | A page per Noun and per task, from the file's descriptions and examples, each with a real answer |
| Get started | Sign-up, Stripe Checkout for a plan or credits, then a Live key |

**Paths.**

1. A person asks a search or answer engine, lands on a Noun page, and sees a real answer with its price.
2. They press Try it, and the page mints a Test key and runs the call.
3. They read the price page and the refund rule, sign up, pay through Checkout, and leave with a Live key in the portal.
4. A finance lead reads the offer card and terms, then adds the seller to their agents' allowed sellers.

**States.** The site serves the live Version, and each superseded Version's terms stay readable at their own URL. Status shows each Interface as `up`, `degraded` or `down`, and each incident as `open` or `resolved`.

**Quality bar.** The price is on the first screen, and every example on the page runs. Every page reads with no script, holds AA contrast, and fits a phone's width.

## The developer portal
The developer portal runs each account after sign-up, at `/dashboard`.

It serves two kinds of account. A Customer buys; a supplier, in a Marketplace or a [Service API](/patterns.md#service-api), sells through the product and is paid by it.

| Area | For a Customer | For a supplier |
| --- | --- | --- |
| Sign-in | Email, single sign-on and directory sync | Email, then verification |
| Keys | Each Live key and its [Test twin](/reference/platform.md#test-twin): made, rolled and revoked | Keys for the supplier's own systems |
| Money | Usage by Verb and day, alerts and spend ceilings, plan changes and cancellation, payment methods, tax details, invoices and receipts | Payout onboarding on Stripe, payouts and statements, tax forms |
| People | Members and Roles, connected apps | Members of the supplier's firm |
| Agents | Mandates and budgets for the Customer's own agents | Mandates for agents that fill orders for the supplier |
| Events | Watches and their deliveries with Replay; request logs; runs and why each waits | The same, for the supplier's orders |
| The catalog | — | The supplier's items and prices, inside the bounds you set |
| Disputes | Open one with a receipt, and follow it | Answer one about the supplier's fill |
| Data | Export everything, and close the account with its data erased | The same |
| Reach the seller | An intake Verb that opens a conversation | The same |

**Paths.**

1. A Customer signs in, takes a Test key, and makes a first call from the docs.
2. They buy credits through Checkout, and a Live key appears.
3. They set a spend ceiling, invite a member, and give one agent a mandate with a 200 USD budget.
4. They replay a failed webhook delivery, see why a run waits, or dispute a charge with its receipt.
5. A supplier applies, passes identity and tax checks, finishes payout onboarding on Stripe, publishes items, and sees a first payout.

**States.**

| Thing | States |
| --- | --- |
| An account | `invited`, `active`, `past_due`, `suspended`, `closed`, `erased` |
| A Key | `active`, `rolled`, `revoked`; a rolled Key answers for 24 hours |
| A mandate | `active`, `suspended`, `exhausted`, `expired`, `revoked` |
| A supplier | `applied`, `verifying`, `verified`, `paused`, `removed` |
| A payout account | `onboarding`, `enabled`, `restricted`, then `enabled` once Stripe's request is met |

**Quality bar.** An empty screen says why it is empty and what fills it, and every refusal shows its cure. An export holds every record, Event and receipt the account owns.

A supplier fills orders over the API, CLI or MCP, or in a delivery app built on the UI contracts. The portal runs the supplier's account, not the work.

## The docs
The docs, at `/docs`, teach a person and an agent to make the first paid call, then every call after it.

| Part | What it holds |
| --- | --- |
| Quickstarts | One per Interface: curl, the SDKs, the CLI and MCP |
| Guides | One per task the file's descriptions name, each ending in a call that runs |
| Reference | A page per Noun, Verb and Event, with its schema, its example and its price |
| Errors | A page per refusal, with its cause and its cure; each [Problem](/reference.md#errors)'s `type` links to it |
| Try it | Every printed call runs against the Test twin with a Test key the page mints, and after sign-in with the reader's own |
| Versions | A page set per Version, with a migration guide for each breaking change |
| Search | Across every page, over the docs and over MCP's `search` and `fetch` |
| For agents | `llms.txt`, a Markdown twin per page, OpenAPI and agents.json |

**Paths.**

1. A developer opens their language's quickstart and copies a call with their Test key in it.
2. The call answers 200, and the reply's `X-Cost` matches the price on the page.
3. A later call answers 402; its `type` link opens the error page, whose cure is one Checkout link.
4. An agent reads `llms.txt`, then a Verb's Markdown twin, and calls it with no page rendered.

**States.** Each page set follows its Version: `live`, `superseded` or `deprecated` with a link to the migration guide, then `retired` and still readable.

**Quality bar.** Every printed call runs against the Test twin. A Verb's page exists from the deploy that adds the Verb.

## Contracts and an example
| You declare | The platform does |
| --- | --- |
| The file, with a description on the file, each Noun and each Verb | Writes the hero, the reference, the guides' outlines and the answer-engine pages from them |
| `brand`: name, logo and colours | Applies them to all three, every email and every receipt |
| A part you override, by path | Serves your part, and keeps every generated part around it in step |
| `docs.guides`: guides you write | Checks every call inside them against the file at each deploy |
| Nothing for the portal | Generates every area from the Verbs, the Offer and the account kinds the file declares |

| Subsystem | What the three take from it | What they give back |
| --- | --- | --- |
| Definition and compile | Every name, schema, price and description, and the [Digest](/reference/platform.md#digest) each page is stamped with | Your overrides and guides, checked at each deploy |
| Identity, access and policy | Sign-in, single sign-on, Roles, mandates, and the one decision behind every portal move | Invites, Role changes and mandates, each made as a Verb |
| Model and records | Nouns and their examples for the reference and the answer-engine pages; export | A page per Noun; the account's data, exported whole |
| Data and Sources | Licence terms and coverage to print; each Customer's connect flow | The portal's connect and revoke screens, over the same Verbs |
| Runtime | Watches, deliveries, Replay and why a run waits | Every Try it call, through the one gate |
| Work | Supplier verification, track record and the account kind | A supplier's sign-up, through to verification |
| Commerce | The Offer, Checkout, invoices, receipts, payouts and disputes, all on Stripe | Checkout started, plans changed, disputes opened, each as a Verb |
| Trust and operations | Status, incidents, request logs, export and erasure | Every printed call, for the outside check to run |

### Example
`companyfacts` with its brand, one page of its own on the site, and one guide in the docs.

```ts title="definition.ts"
import { define, secret } from 'apis.dev'

/** Any company by its domain, with its headcount and sector. */
export default define({
  name: 'companyfacts', domain: 'companyfacts.apis.dev',
  …
  brand: { logo: './logo.svg', color: '#0b6e4f' },        // every face, email and receipt
  site: { pages: { '/coverage': './coverage.mdx' } },     // your page; the rest stays generated
  docs: { guides: ['./guides/enrich-a-crm.mdx'] },        // checked against the file at each deploy
  sources: {
    firms: { origin: 'https://firms.example.com', key: secret('FIRMS_KEY') },
  },
  Company: {
    domain:    { type: 'url!#',   from: 'firms', map: 'website' },
    employees: { type: 'number?', from: 'firms', map: 'headcount' },
    sector:    { type: 'string?', from: 'firms', map: 'industry' },
  },
  offer: { 'Company.get': 0.002, 'Company.search': 0.005 },
})
```

---

Three products from one file, so the page that sells a Verb, the screen that bills it and the page that teaches it always agree.