Interfaces

An Interface is how a person or an Agent reaches a Product. Every Product ships the same Verbs through eight: API, MCP, CLI, SDK, Site, App, docs, and webhooks.

One Verb, every InterfaceCopy Anchor Link

Each Verb has one name, Noun.verb, on every Interface: the API route, the SDK method, the CLI command, the MCP call, and the webhook Event. Every Interface checks the same Permissions and Limits, and every call returns the same Action. An Interface changes how a call reads, never what it does.

Here is one Verb on every Interface. Pick an Interface in the header, and every example on the site follows.

curl -X POST https://api.sb/shiftnote.app/leads/lead_1/qualify \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer":"offer_1"}'

import { $ } from 'startup-builder'

const { deal, lead } = await $.Lead.qualify({ lead: 'lead_1', offer: 'offer_1' })

npx startup-builder do Lead.qualify --json '{"lead":"lead_1","offer":"offer_1"}'

{
  "name": "do",
  "arguments": {
    "code": "return await $.Lead.qualify({ lead: 'lead_1', offer: 'offer_1' })"
  }
}

What each Interface is forCopy Anchor Link

Docs are an Interface because they compile from the same definition. A Verb's reference cannot describe behavior the API lacks.

Screens for peopleCopy Anchor Link

An App derives three screens from each Noun. A list draws as a DataTable or a Board, and a record as a ThingDetail. Each Verb the Persona may run gets a VerbSheet.

The first session opens on the onboarding checklist and ends at first value, as the Product Template defines it: a shared gallery, a closed month. An empty list renders one sentence and the one Verb that fills it, such as No galleries yet. Create gallery, never a blank table.

Every pending state has exactly one rendering, as ActionStatus defines.

Each caller sees its own VerbsCopy Anchor Link

Authorization runs once, below every Interface, and narrows everything above it. A record's actions map lists only the Verbs this caller may run on it now. An Agent's MCP tool list holds only its Role's Permissions, and an App draws only the buttons its Persona may press.

Two callers reading the same record can see different Verbs. Neither sees a Verb it would be refused.

One address, three renderingsCopy Anchor Link

Every record has one URL, its $id, and that URL answers in three forms. A browser gets HTML, code gets JSON, and an Agent sending Accept: text/markdown gets Markdown in fewer tokens. The data and the links are identical in all three.

plugatlas.com, a map of EV chargers, declares a Station Noun:

curl https://api.sb/plugatlas.com/stations/st_204 -H "Accept: text/markdown"

Every API also publishes four machine registers: an OpenAPI document, llms.txt, a Markdown copy of every page, and agents.json. An Agent reads the contract a developer reads, in the form it parses best. A new Verb appears in all four at its next deploy.

Same call, different ProductCopy Anchor Link

An HTTPS POST says little about the Product behind it. The Action it returns, and the Event the Offer earns on, say the rest.

A successful HTTP response never means the Customer got value. Clients read the Action's status, and webhooks deliver its Events.

AddressesCopy Anchor Link

Every Interface answers on api.sb under the Startup's namespace, such as https://api.sb/plugatlas.com. Web Interfaces also mount on the Startup's own Domain at a path, such as plugatlas.com/api. The SDK and CLI need no path.

A new hostname is another address for the same Product, never another Product. Its Customers, Tenants, and history stay where they are.

NextCopy Anchor Link

Composition covers building one Product from others.