The response envelope

Every response from api.sb is one JSON envelope: the record, where it lives, and what the caller can do next. A client that reads one envelope reads them all.

One shape for every recordCopy Anchor Link

briefcraft.ai is a Startup that sells research briefs to product teams. Reading one of its Orders returns this:

{
  "api": "https://api.sb/briefcraft.ai",
  "$type": "Order",
  "$id": "https://api.sb/briefcraft.ai/orders/order_1",
  "order": {
    "$id": "https://api.sb/briefcraft.ai/orders/order_1",
    "$type": "Order",
    "$version": 4,
    "total": { "amount": 290, "currency": "USD" },
    "status": "paid"
  },
  "links": {
    "self": "https://api.sb/briefcraft.ai/orders/order_1",
    "up": "https://api.sb/briefcraft.ai/orders"
  },
  "actions": {
    "refund": "https://api.sb/briefcraft.ai/orders/order_1/refund",
    "dispute": "https://api.sb/briefcraft.ai/orders/order_1/dispute"
  }
}

api is the namespace root: the Startup that owns the record. $type names the Noun, $id is the record's canonical URL, and $version counts its writes. The record sits under its Noun's name in camelCase, so an Order arrives as order.

Fields that start with $ are metadata. Every other field is a property listed on the Noun's reference, and no field starts with an underscore.

Links and actionsCopy Anchor Link

links and actions both map a name to a URL. links points at records to read: self, the collection up, and the next page of a list. actions points at the Verbs this caller may run on this record, in its current state.

The actions map is the record's state machine, read from where the caller stands. A paid Order lists refund and dispute; a refunded Order lists neither. A caller's Permissions filter the map too, so two callers can read the same Order and see different Verbs.

An Agent that follows actions never calls a Verb the record refuses, and never needs the state rules in its prompt. A GET on any actions URL previews that Verb without running it: the result, the price, and whether it waits for an Approval.

Writes return an ActionCopy Anchor Link

A write returns the Action it created beside the record it changed:

{
  "api": "https://api.sb/briefcraft.ai",
  "action": {
    "$id": "https://api.sb/briefcraft.ai/actions/action_7",
    "operation": "Order.refund",
    "status": "done",
    "mode": "do",
    "by": "https://api.sb/briefcraft.ai/agents/support"
  },
  "order": {
    "$id": "https://api.sb/briefcraft.ai/orders/order_1",
    "$type": "Order",
    "$version": 5,
    "status": "refunded"
  },
  "links": { "self": "https://api.sb/briefcraft.ai/actions/action_7" }
}

action.operation is the operation id, Noun.verb. The same id names the SDK method, the CLI command and the MCP call. Actions covers every field and status.

Lists and cursorsCopy Anchor Link

A list returns one page under the plural key, with a cursor in meta:

{
  "api": "https://api.sb/briefcraft.ai",
  "$type": "Order",
  "orders": [{ "$id": "https://api.sb/briefcraft.ai/orders/order_1", "$type": "Order", "status": "paid" }],
  "meta": { "limit": 20, "after": "cursor_2" },
  "links": {
    "self": "https://api.sb/briefcraft.ai/orders",
    "next": "https://api.sb/briefcraft.ai/orders?after=cursor_2"
  }
}

To read the next page, follow links.next. A page with no after is the last one. Cursors are opaque: pass them back unchanged.

Relationships and includesCopy Anchor Link

relationships holds a record's outbound edges, such as the Customer who placed an Order. references holds inbound edges, such as every Order for one Offer. Inbound edges grow long, so each is a paginated link.

By default each edge is a URL. ?include=customer embeds the Customer, and ?depth=2 follows one level further. An embedded record is a full envelope record, with its own $id and actions.

One address, three renderingsCopy Anchor Link

Every $id serves three content types, chosen by Accept. application/json is the default, and text/markdown returns the same record and links in fewer tokens. text/html opens the record in the Startup's App.

The Interfaces carry the envelope unchanged. The SDK returns the typed record, and --json makes the CLI print all of it. The MCP fetch call hands it to an Agent as is.

NextCopy Anchor Link

• Actions: the record every write returns.
• Authentication: the credential that decides which namespace api names.
• Errors and testing: the problem document a failed call returns.