# The response envelope

URL: /code/api/guides/envelope · Id: `page:code/api/guides/envelope`

> Every api.sb response is one JSON envelope that names its record, links to related records, and lists the Verbs the caller can run next.

Every response from [api.sb](/code/platform/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 record
`briefcraft.ai` is a [Startup](/business/nouns/startup) that sells research briefs to product teams. Reading one of its [Orders](/business/nouns/order) returns this:

```json
{
  "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](/business/nouns/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 actions
`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](/business/nouns/verb) 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](/business/nouns/permission) filter the map too, so two callers can read the same Order and see different Verbs.

An [Agent](/business/nouns/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](/business/nouns/approval).

## Writes return an Action
A write returns the [Action](/business/nouns/action) it created beside the record it changed:

```json
{
  "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](/code/sdk/guides/actions) covers every field and status.

## Lists and cursors
A list returns one page under the plural key, with a cursor in `meta`:

```json
{
  "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 includes
`relationships` holds a record's outbound edges, such as the [Customer](/business/nouns/customer) who placed an Order. `references` holds inbound edges, such as every Order for one [Offer](/business/nouns/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 renderings
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](/business/nouns/app).

The [Interfaces](/business/nouns/interface) 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.

## Next
- [Actions](/code/sdk/guides/actions): the record every write returns.
- [Authentication](/code/api/guides/authentication): the credential that decides which namespace `api` names.
- [Errors and testing](/code/sdk/guides/errors-and-testing): the problem document a failed call returns.