# Allumi Press — agent ordering

Allumi sells done-for-you press-release campaigns. An AI agent can order one
for its human through a gated MCP server or the matching REST API. The human
always approves payment in a browser; an agent can never charge a card itself.

## Endpoints

- MCP (Streamable HTTP JSON-RPC): POST /api/mcp — methods initialize, tools/list, tools/call
- REST mirror: /api/agent/catalog, /api/agent/quotes, /api/agent/orders,
  /api/agent/orders/{id}, /api/agent/orders/{id}/brief, /api/agent/orders/{id}/report

## Access key

POST /api/agent/keys with {"label":"<agent name>"} returns {"token":"press_sk_..."}
shown once. Send it as "Authorization: Bearer press_sk_..." on protected calls.
Optional "lifetimeDays" 1-90 (default 90). Revoke: DELETE /api/agent/keys
with {"id":"<key id>"} using the key's own bearer or the customer's session.

## Flow

1. list_packages / GET /api/agent/catalog — public, no key.
2. get_quote / POST /api/agent/quotes — public, server-owned prices in USD cents.
3. create_order / POST /api/agent/orders {items, campaign, requestKey} — returns
   order id and paymentUrl. requestKey is idempotent; reuse it to retry safely.
4. Give the human paymentUrl — a token-bound page that mounts embedded checkout.
5. order_status / GET /api/agent/orders/{id} — poll until paid.
6. submit_brief / POST /api/agent/orders/{id}/brief {announcement, outcome,
   mustInclude} — accepted only after payment.
7. get_report / GET /api/agent/orders/{id}/report — campaign status, intake,
   activity and publication links.

## Rules

- Prices, terms and order snapshots are server-owned; never trust client totals.
- Errors: {"error":"<stable code>","status":<n>}. 429 returns a Retry-After hint.
- Keys are scoped to the customer that created them; other tenants' orders 404.
- No auto-charge. Shared payment tokens and saved-card charging are not offered.