Service API

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.

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. It also refuses an Offer that sells a grade the path cannot earn.

Outcomes and acceptanceCopy Anchor Link

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.

{
  "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 supervisionCopy Anchor Link

An Offer sells a grade: the strength of the evidence behind each outcome. The compiler computes the grade the path earns from its checks.

An output price needs at least graded, and an outcome price needs measured or confirmed. Deploy refuses an Offer that sells more than its path earns.

Review is a step kind, in five patterns: adversarial ("harden it"), affirmative ("yes, and"), recursive, sampled and four-eyes. The doer is never the checker.

Licensed supervision is part of the path. A Role carries a credential, checked when its holder joins, and an act the law reserves runs only for a holder.

A supervised Role works within its ratio, 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 ceilingCopy Anchor Link

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. The cost falls, 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:

$ 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 partCopy Anchor Link

What clients and their agents meetCopy Anchor Link

• The grade before they order. The offer card prints the price, the grade, the window and the remedy.
• The case, not the work. Seen states move; the steps inside stay private, and their evidence arrives with the delivery.
• Their turn is a Verb. Approve the quote, sign, accept or reject, through the API, MCP, the SDK or the CLI.
• One charge, on acceptance. Nothing is charged before; a rejection takes its remedy at no charge.
• One dispute path, opened with the receipt and answered with the evidence.

An agent acting as the client finishes the same path:

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.