> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent benchmark

> A reproducible transcript: quote → send → track in 3 calls, zero schema retries, replay-proof.

Claims about being "agent-ready" are cheap; transcripts aren't. This page is a
real, reproducible run of the core loop against sandbox mode — every payload
below is captured verbatim from the API (re-verified 2026-08-28).

**Result: quote → send → track completes in 3 REST calls (2 MCP tool calls:
`quote_letter`, `send_letter`). Zero schema retries. Replays provably cannot
double-send.**

## Call 1 — quote (free, mints the confirmation token)

```json Request theme={null}
POST /v1/quotes
{ "mail_class": "certified", "page_count": 1,
  "to": { "name": "Property LLC", "line1": "1 Main St",
          "city": "Richmond", "state": "VA", "zip": "23220" },
  "text": "Formal demand for return of my security deposit within 14 days of this notice." }
```

```json Response (200) theme={null}
{
  "status": "ok",
  "total_cents": 1299,
  "total": "$12.99",
  "breakdown": [
    { "id": "certified_mail_letter_1_page", "label": "Certified Mail letter, 1 page", "amount_cents": 1299 }
  ],
  "confirmation_token": "ppq_eyJ2IjoxLCJqdGkiOiJhNDBlZjFiMzFhZDMxYjMx…",
  "expires_in_minutes": 30,
  "next": ["POST /v1/orders with this confirmation_token and the same recipient, content, and options."]
}
```

Note the `next` array: the response tells the agent its own next step.

## Call 2 — send (sandbox), with an idempotency key

```json Request theme={null}
POST /v1/orders
Idempotency-Key: bench-2026-08-25-a
{ "mail_class": "certified", "sandbox": true,
  "confirmation_token": "ppq_eyJ2IjoxLCJqdGkiOiJhNDBlZjFiMzFhZDMxYjMx…",
  "to":   { "name": "Property LLC", "line1": "1 Main St", "city": "Richmond", "state": "VA", "zip": "23220" },
  "from": { "name": "Alex Rivera", "line1": "12 Grove Ave", "city": "Richmond", "state": "VA", "zip": "23221" },
  "text": "Formal demand for return of my security deposit within 14 days of this notice." }
```

```json Response (201) — trimmed theme={null}
{
  "status": "ok",
  "order": {
    "id": "ord_test_f5ca66ace638fdc1",
    "status": "submitted",
    "sandbox": true,
    "price_cents": 1299,
    "tracking_number": "9400MOCK00000001"
  },
  "corrected_to": { "name": "Property LLC", "line1": "1 MAIN ST", "city": "RICHMOND", "state": "VA", "zip": "23220" },
  "capability": { "cancel_token": "…", "review_token": "…" }
}
```

The address came back USPS-standardized (`corrected_to`), and the response
carries scoped capability tokens for cancel/review — no account, no API key.

## Call 3 — track

```json GET /v1/orders/ord_test_f5ca66ace638fdc1 → 200 theme={null}
{ "status": "ok", "order": { "status": "submitted", "tracking_number": "9400MOCK00000001", "…": "…" } }
```

## The safety proofs (captured in the same run)

**Replay the exact same order call** (same `Idempotency-Key`):

```json theme={null}
{ "status": "ok", "replayed": true, "order": { "id": "ord_test_f5ca66ace638fdc1", "…": "…" } }
```

Same order id. A retry storm mails one letter.

**Reuse the confirmation token** (new order, same token):

```json 409 Conflict theme={null}
{ "status": "action_required", "code": "confirmation_used",
  "reason": "This confirmation_token was already used to send a letter. Each quote authorises exactly one letter.",
  "next": ["Quote again — POST /v1/quotes (MCP: quote_letter) — to authorise another letter."] }
```

**Tamper with the token**:

```json 400 Bad Request theme={null}
{ "status": "action_required", "code": "confirmation_malformed",
  "reason": "confirmation_token is not a paperplane quote token.",
  "next": ["Quote first: POST /v1/quotes (MCP: quote_letter) with the exact parameters you intend to send, then pass the confirmation_token it returns."] }
```

Every failure is a `{ status, code, reason, next[] }` envelope — the
[error contract](/docs/guides/errors) documents all of them with retry semantics.

## Reproduce it

Run the three calls above against `https://sendpaperplane.com` with
`"sandbox": true` — no account, no key, no cost. The MCP equivalent is two
tool calls (`quote_letter` → `send_letter`); connect per
[Build with agents](/docs/agents).