---
title: "Service API"
url: /patterns/service-api
---

# Service API

> Sell an outcome, charged once, when the work is accepted.

**The Filing: what the client sees, and the steps inside.**

- The client orders, and $25 is held.
- While the Filing is `drafting`, three private steps run: an agent drafts, a second agent hardens it, and a supervised paralegal checks it.
- The Filing is `drafted`; the client signs, an agent files it, and it is `filed`.
- Within 7 days the client accepts, which charges the $25, or rejects, and the Filing is redone at no charge.

A Service API sells work that is sold by headcount today. The buyer orders an outcome and watches it move.

Inside, each step runs on the cheapest worker that meets its grade, and a second worker checks it. The price is charged once the buyer accepts the result under an [Outcome contract](/reference/platform.md#outcome-contract).

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

/** Each Customer's annual report, drafted, hardened, checked, signed and filed, charged once when accepted. */
export default define({
  name: 'filings', domain: 'filings.apis.dev',
  roles: {
    paralegal: { supervisedBy: 'attorney' },
    attorney:  { credential: 'bar', supervises: { paralegal: 5 } },   // one attorney to five paralegals
  },
  Filing: {                                                           // the case your client watches
    company: 'string', year: 'number',
    status: {
      order: [],
      draft: { in: 'ordered', run: workflow(async ($, filing) => {
        const { form } = await $.generative('Draft the annual report for {company}', filing,
          { returns: { form: 'string' } })
        await $.review(form, { pattern: 'adversarial' })               // a second agent tries to break it
        await $.human('Check the draft', { form }, { role: 'paralegal' })  // attests it, supervised
        return { form }
      }) },
      sign: { in: 'drafted', floor: 'signature' },                    // the client's act, never an agent's
      file: { in: 'signed', run: agentic('File the signed report with the state') },
      accept: 'filed', reject: 'filed',
    },
  },
  on: { 'Filing.ordered': 'Filing.draft', 'Filing.signed': 'Filing.file' },
  offer: {
    'Filing.order': { price: 25, when: 'accepted', accept: 'customer',
                      acceptWithin: '7d', remedy: 'redo', grade: 'measured' },
  },
})
```

Deploy refuses the file when no one holds `paralegal`, or when the roster's attorneys cannot supervise its paralegals.

## Outcomes and acceptance
| Family | What it does |
| --- | --- |
| The case | A work [Thing](/reference/platform.md#thing) with seen states the buyer watches and private steps inside them, from intake and a conflict check to delivery |
| Steps and staffing | Each step names a [Function](/patterns/function-api.md) kind, a [Role](/reference/platform.md#role) and a fallback; tasks route by skill and credential, under leases, with handoffs |
| Review | Five patterns as step kinds, each with a checker who is not the doer |
| Assurance grades | Seven grades, each earned by a kind of check; the Offer sells one, and the compiler holds the price to it |
| Licensed supervision | Credentialed Roles, acts reserved to them, supervision ratios and the oversight record, designed into the path |
| Acceptance and remedy | An acceptor, a window, what silence means, and a remedy for a rejection: `redo`, `refund`, `credit` or `finish` |
| Held funds | The price held at order, charged on acceptance, and split to each worker or supplier the Offer names |
| Disputes | One path, opened with the receipt and answered with the delivery's evidence |
| The agent as client | An agent orders, approves, accepts or contests, and pays; an act reserved to a person goes to that person by a single-use link |

| Thing | States | What moves it |
| --- | --- | --- |
| A Filing | `ordered`, `drafting`, `drafted`, `signed`, `filing`, `filed`, then `accepted` or `rejected` | The client's Verbs, the steps, and the acceptance clock |
| A review | `requested`, `passed`; or `changes_asked`, `revised`, then `requested` again | The checker's verdict; a recursive review loops until it passes or escalates to a person |
| A sign-off | `awaiting`, then `signed` or `refused` | A holder of the credentialed Role; a refusal sends the step back |
| The outcome charge | `held`, then `charged` and `paid_out`, or `remedied` | The order holds it; acceptance charges it; a rejection takes the remedy |
| A delivery | `sent`, `in_window`, then `accepted`, `rejected` or `lapsed` | The acceptor, or the window's clock; a lapse accepts |
| A dispute | `opened`, `answered`, then `upheld` or `denied` | Either party, with the receipt and the evidence; an upheld dispute takes the remedy |

Seen is a state and unseen is a step: the steps inside `drafting` stay private, and their evidence travels with the delivery. The acceptor is the client here; it can also be an evaluator the client agreed to, or an outside oracle such as the filing office. Acceptance, or 7 days of silence, charges the $25.

```json title="Filing.accepted · to you"
{
  "id": "evt_11",
  "type": "Filing.accepted",
  "at": "2026-10-26T08:15:00Z",
  "seq": 11,
  "data": { "id": "filing_1", "status": "accepted" },
  "charged": { "price": 25, "currency": "USD" },
  "grade": "measured",
  "evidence": {
    "review": { "pattern": "adversarial", "rounds": 2, "passed": true },
    "check": { "role": "paralegal", "supervisor": "attorney", "attested": true },
    "accepted": { "by": "customer", "day": 2 }
  }
}
```

## Grades, review and supervision
An Offer sells a grade: the strength of the evidence behind each outcome. The compiler computes the grade the path earns from its checks.

| Grade | Earned by | [Prices](/reference/platform.md#price) up to |
| --- | --- | --- |
| `declared` | the doer's own statement | per call |
| `estimated` | a model's confidence on the output | per call |
| `sampled` | a checker who reviews one call in every n | per call |
| `graded` | a checker who reviews every one | per output |
| `attested` | a named person who signs every one, credentialed or under a credentialed supervisor | per output |
| `measured` | the acceptor's verdict on the outcome itself | per outcome |
| `confirmed` | an outside party's record, such as the filing office's | per outcome |

Deploy refuses an Offer that sells more than its path earns.

Review comes in five patterns: adversarial ("harden it"), affirmative ("yes, and"), recursive, sampled and four-eyes. A credential is checked when its holder joins, and every supervised act writes the oversight record. A step's `floor` names what no change may remove: none, a signature, or a licensed practice.

## The ceiling
A Service API sells the largest unit of the seven patterns: an outcome a firm bills by the hour today, priced once. Its margin moves.

A step can move from a person to an agent, or to code, behind the same Verb and price, and the client sees no change.

Deploy prints the cost per step, to you alone. Once the record shows hardened drafts pass, the paralegal's check moves from every Filing to one in ten:

```sh title="Terminal"
$ npx apis.dev deploy
✓ Filing.order  25  · grade measured · floor signature
    draft 0.30 · harden 0.40 · check 8.00 (every one) · file 0.20  · cost 8.90 · margin 64%
✓ published v6 to https://filings.apis.dev
$ npx apis.dev deploy        # check: sampled, one in ten
✓ Filing.order  25  · grade measured · floor signature
    draft 0.30 · harden 0.40 · check 0.80 (sampled 1/10) · file 0.20  · cost 1.70 · margin 93%
✓ published v7 to https://filings.apis.dev
```

The change deploys because the Offer sells `measured`, which acceptance earns; an Offer selling `attested` refuses it. No change removes the client's signature, the step's `floor`. If the rejection rate rises, the next margin print shows it.

## Contracts and the platform's part
It declares what [Work](/work.md#declare) declares: seen states, steps, review, credentialed Roles, `floor`, the grade and the Outcome contract. The cost per step, the margin print, the staffing check and each delivery's evidence need nothing declared.

A Service API draws on every subsystem:

- **Definition and compile** checks the case graph, staffing, grades and floors.
- **Identity, access and policy** gives credentialed Roles, reserved acts, single-use links and shared-case grants.
- **Model and records** keeps case files, privilege classes, retention and legal hold.
- **Data and Sources** brings outside submissions and the typed acknowledgements an oracle reads.
- **Runtime** runs steps, waits and clocks, and sends effects such as the filing itself once.
- **Work** gives cases, tasks, review, supervision, acceptance and disputes.
- **Commerce** holds the price, charges on acceptance, applies the remedy and pays each worker's share.
- **Interfaces and distribution** gives one conversation per case on every [channel](/interfaces/channels.md), and the client and delivery [contracts](/interfaces/ui-contracts.md) UIs render.
- **Trust and operations** keeps the supervision record and review evidence, runs evals, and checks each grade from outside.

## What clients and their agents meet
A client's turn is a Verb: approve the quote, sign, accept or reject, through the API, MCP, the SDK or the CLI.

An agent acting as the client does the same:

1. It reads the offer card: $25 per accepted Filing, grade `measured`, 7 days to accept, `redo` on rejection.
2. It orders under its mandate, and $25 is held from its budget.
3. When the Filing is `drafted`, the signature goes to its person by a single-use link: an agent never signs.
4. It reads the delivery's evidence, accepts or rejects within the window, and keeps the receipt.

| Pattern | Noun: the shape you promise | Verb: what can be done to it | Source: where its data comes from | Trigger: what reacts to a change | Offer: the price |
| --- | --- | --- | --- | --- | --- |
| [Service API](/patterns/service-api.md): Sell an outcome, charged once, when the work is accepted. A Workflow writes it. | a work Thing the buyer watches | order, then one Verb per move | the filing office's receipt | Filing.ordered starts the draft | 25 when accepted, under an Outcome contract |