---
title: "Trust and operations"
url: /trust
---

# Trust and operations

> The managed infrastructure under every product: Test and Live, Versions, reliability, security, privacy, brakes on abuse, and proof judged from outside.

Trust and operations is the managed infrastructure every product runs on, so you never run it yourself. It keeps the product up, safe and honest, and proves each of those to an outside [Verifier](/reference/platform.md#verifier) whose record buyers read.

## Capability families
| Family | What it does |
| --- | --- |
| Environments | Test and Live for every product: a [Test twin](/reference/platform.md#test-twin) whose books never post, a simulated market of paying agents, and test clocks. A person approves the move to Live |
| [Versions](/reference/platform.md#version) and changes | Plan, deploy, cutover, pinning and rollback; deprecation with a notice, `Deprecation` and `Sunset` headers and a migration guide; retirement once nothing is pinned |
| Reliability | Rate limits; [Limits](/reference/platform.md#limit) that fail closed; a retry counted once; runs that survive restarts; a promise per Verb, measured from outside; incidents and a status page |
| Observability | A [Call record](/reference/platform.md#call-record) for every call, logs as they happen, a trace across every step and every hop, metrics and alerts; each Customer sees its own calls |
| Security | [Keys](/reference/platform.md#key) kept only as digests; secrets outside the file; encryption in transit and at rest; rotated signing keys for webhooks and receipts; a leaked Key revoked |
| Privacy | Residency per [Namespace](/reference/platform.md#namespace), retention per Noun, consent, export and erasure as Verbs, and an audit export |
| Customer operations | Provision, suspend, restore, isolate, offboard and erase a Customer, each a Verb your console or your agent calls |
| Abuse and risk | Brakes declared in the file: trial abuse, card testing, Key leaks, scraping against a licence, runaway agent spend, chargebacks; seller and supplier verification |
| Evidence | The proof record: what each decision enforced and why, digests and attestations, and a replay of any call against its Version; evals for generative, agentic and human [Functions](/patterns.md#function-api) |
| Outside verification | The Verifier's conformance suite, run on every deploy and on a schedule, with its results on the offer card and the status page |

The platform runs the infrastructure and answers for its incidents. A failure your own Function causes reaches you as an Event, with its trace, and shows on your status page.

## Lifecycles and states
| Thing | States | What moves it |
| --- | --- | --- |
| A product's environment | `test`, then `live` | A deploy serves Test at once; the first Live sale waits on the move to Live, which a person approves |
| A [Version](/reference/platform.md#version) | `live`, `superseded`, `deprecated`, `retired` | The next deploy supersedes it; you deprecate it with a window; it retires when the window ends and nothing is pinned; a rollback makes the one before live |
| An incident | `investigating`, `identified`, `monitoring`, `resolved` | A failing check opens it; each update posts to the status page and to Watches; the resolution links its record |
| A Customer account | `invited`, `active`, `past_due`, `suspended`, `closed`, then `erased`; a restore returns `suspended` to `active` | Your console or your agent; a suspension refuses calls with a reason and keeps every record; an erase follows an export |
| A Key | `active`, `rolled`, `revoked` | Its holder; a Key found in public is revoked at once and its holder told |
| A brake | `armed`, `tripped`, `held`, then `released` or `reset` | A cap is reached before a call runs; the run waits as Pending; a person releases it, or the period resets it |
| A verification run | `scheduled`, `running`, then `passed` or `failed` | Every deploy and a schedule start one; its result replaces the proof on the offer card |

Every move is a Verb and writes its Event: `Version.deprecated`, `Incident.resolved`, `Customer.suspended`, `Brake.tripped`.

## What you declare, what the platform does
| You declare | The platform does |
| --- | --- |
| A promise per Verb: a success rate and a median time | Measures it from outside, prints it on the offer card and the status page, and pays any credit your terms name when it misses |
| A region | Keeps each Customer's records, files and backups there |
| Retention per Noun | Keeps and deletes on that schedule; a legal hold stops a delete |
| Brakes: a cap per Verb, per Customer and per period, on calls or on spend | Checks each before the call runs, holds the run as Pending, and releases it on a person's approval |
| A deprecation window | Sends the notice, adds `Deprecation` and `Sunset` to replies, and serves the old Version until the window ends and nothing is pinned |
| Nothing else | The Test twin, deploys and rollbacks, call records, logs, traces, secrets, encryption, backups, Key-leak checks, incidents, the status page, Customer operations and the Verifier |

### Example
The agent product declares what it promises, where its Customers' records live, and when a run stops for a person.

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

/** An agent that books three meetings a week with each Customer's leads, in their own inbox and CRM. */
export default define({
  name: 'meetings', domain: 'meetings.apis.dev',
  …
  sources: { … },                                         // each Customer's inbox and CRM, as before
  Meeting: {
    with: 'string', company: 'string', at: 'date',
    book: agentic('Book a meeting with the next lead in {crm}',
      { tools: ['inbox', 'crm'], returns: { meeting: 'string' } }),
  },
  on: { 'every Mon, Wed, Fri 09:00': 'Meeting.book' },
  offer: { … },                                           // by tokens and minutes, as before
  operate: {
    promise: { 'Meeting.book': { success: 0.99, median: '10m' } },  // judged from outside
    region:  'eu',                                        // records, files and backups
    brakes:  { 'Meeting.book': { day: 5, spend: { day: 2 } } },     // per Customer; past it, a person
    sunset:  '180d',                                      // how long a deprecated Version answers
  },
})
```

The proof the Verifier publishes for it, read by an agent before it hires the product.

```json title="meetings.apis.dev/.well-known/agents.json · offer"
{
  "offer": {
    "proof": {
      "by": "verifier", "window": "90d",
      "success": 0.994, "median": "6m",
      "conformance": { "passed": 212, "of": 212, "version": "v3" },
      "incidents": 1, "region": "eu"
    }
  }
}
```

## Contracts with the other subsystems
| Subsystem | What Trust and operations takes from it | What it gives back |
| --- | --- | --- |
| Definition and compile | The [Digest](/reference/platform.md#digest), the diff, the breaking-change gate; the promise, region, retention and brakes in the file | Deploy, cutover, rollback and retirement; the outside check of each Version before it serves Live |
| Identity, access and policy | Roles, consent, approvals | Residency and consent as inputs to the one decision; support access recorded read by read; the move to Live and a brake's release as approvals |
| Model and records | Each Namespace's records and files | Backups, residency, retention, legal hold, export and erasure, Namespace by Namespace |
| Data and Sources | Licence terms on each value | Scraping against a licence detected and braked; a [Source](/patterns/dataset-api.md#how-a-field-is-filled)'s failures traced and alerted |
| Runtime | The gate and the commit | Limits checked first and failing closed; a call record committed with the fact; a trace across every step and hop |
| Work | Review and supervision records; supplier onboarding | Evals for each Function kind; supplier and seller verification |
| Commerce | Money Events, Stripe's fraud and dispute signals | A Test Key that never bills; brakes on runaway spend, card testing and chargebacks; the evidence a dispute needs |
| Interfaces and distribution | Every call, from every [Interface](/every-product.md) | The status page, the changelog and the security page on your Domain; `Api-Version`, `Deprecation` and `Sunset` on replies; the proof on the offer card |

**The seam.** Your console reads incidents, Versions, Customers and the proof record through Events and Verbs. A brake trips the same way whether a person or an agent is watching.

## What Customers and their agents meet
- **An engineer integrating.** A Test key calls the Test twin and answers as Live does, with refusals on demand through `Prefer: code=`. A simulated market lets their agent pay and be refused without money moving.
- **A Customer's admin.** A status page on your Domain with incidents they can Watch, the changelog, and each deprecation notice with its migration guide. They also get request logs, an audit export, and export and erasure of their own Namespace.
- **An agent.** It reads the proof on the offer card before it calls, pins `Api-Version`, and follows `Deprecation` and `Sunset`. Each receipt names the Version, so any disagreement replays against it.
- **A security reviewer.** A security page on your Domain, rendered from the file: region, retention, encryption, how Keys are kept, and the Verifier's latest run.
- **Your operator, or your agent.** Read any call by its request id, replay it, roll back, or suspend a Customer, over the API, CLI or MCP.

---

The product never grades itself: an outside Verifier measures it, and the record it publishes is what buyers read.