# Tillpad: full agent guide

Bounded storage and search for agent jobs

## Product

Token-protected helpers for agents:

1. Namespaced KVP (Cloudflare KV + metadata)
2. File upload (text / PDF / Excel) → R2 → extract → async embed (Workers AI) → Vectorize RAG search
3. Budget-native metering (remaining quotas on every spend; get_usage / estimate_usage)
4. Run keys with wipe receipts; capability-scoped subkeys
5. Inspect namespaces / usage quotas
6. Receive-only email inboxes (temporary or permanent) with webhooks, blocklist, and raw MIME read

## Authentication

```
Authorization: Bearer tp_<your_key>
```

Or session JWT from `POST /api/auth/verify-otp`.

## Zero-human bootstrap

```
curl -s -X POST "https://tillpad.dev/api/agents/bootstrap" \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com"}'
```

The first response is always HTTP 202 with `"code":"verification_required"` and a 6-digit code goes to that inbox (10 minutes, single use). Repeat the request with `{"email":"agent@example.com","code":"123456"}` to get `bootstrapToken`. Limits: 5 requests per IP per hour, 5 codes and 5 code attempts per email per hour.

Then `POST https://tillpad.dev/api/billing/machine-pay` with `Authorization: Bearer <bootstrapToken>` and optional `{"sku":"pro_prepaid_30d"}`. On MPP settle you receive `secret` (`tp_…`) and prepaid `planPeriodEnd`. Legal: https://tillpad.dev/terms · https://tillpad.dev/privacy · https://tillpad.dev/refunds.

## Agent SKUs (machine-pay `sku` param)

| SKU | Price | Notes |
|-----|-------|-------|
| pro_prepaid_30d | $9 | 30 days prepaid Pro (default) |
| pro_prepaid_90d | $24 | 90 days prepaid Pro |
| topup_kvp_10k | $1 | +10k KVP ops this month (requires Pro) |
| topup_storage_1gb | $0.05 | +1 GB storage ceiling this month (requires Pro) |

List with amounts: `GET https://tillpad.dev/api/config` → `plans.agentSkus`. Top-ups are available only for KVP (topup_kvp_10k) and storage (topup_storage_1gb). Top-up credits require active Pro, expire at calendar month end, and reactivate if Pro renews same month.

## Quotas (hybrid)

Meters: kvp_ops, storage_bytes, rag_index, rag_query, inbound_email, outbound_http.
Tillpad Pro is $9/month for humans (auto-renew + metered overage) or $9/30 days prepaid for agents via Stripe MPP. Unpaid accounts have no usable remaining quota; human Pro includes monthly usage, then Stripe overage up to the spend ceiling. Agent prepaid Pro renews manually and has the same included monthly quota plus optional top-ups, with no overage.
Included monthly amounts come from plan vars; human Pro overage → Stripe (agent prepaid Pro has no overage; use top-ups); hard cap → HTTP 429.
Active subscription required to create API keys and to meter KVP/RAG/upload (local may use BILLING_DEV_BYPASS).
402/429 responses include `code`, `actions`, and `budget`.
- `actions` with `type: checkout`: hand hosted Checkout URL to a human (recurring Stripe sub).
- `actions` with `type: machine_pay` (when MPP enabled): agent POSTs `/api/billing/machine-pay` with an MPP Payment credential for prepaid Pro (30 days).
Do not invent a billing flow. ChatGPT Instant Checkout / Agentic Commerce Suite is out of scope.

## Scratchpad loop (preferred first run)

Follow [https://tillpad.dev/scratchpad.txt](https://tillpad.dev/scratchpad.txt): mint run key → KVP → upload/search → `finish_run` → wipe receipt.
Human copy: [https://tillpad.dev/docs/scratchpad](https://tillpad.dev/docs/scratchpad).

## Example

```
curl -X PUT "https://tillpad.dev/api/kvp/demo/hello" \
  -H "Authorization: Bearer tp_…" \
  -H "Content-Type: application/json" \
  -d '{"value":"world"}'
```

```
curl -X POST "https://tillpad.dev/api/rag/search" \
  -H "Authorization: Bearer tp_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"what is stored?","topK":5}'
```

## MCP tools

Connect to `https://tillpad.dev/mcp` with the same Bearer key.

- get_usage (view: summary, periods, budget), estimate_usage, manage_billing (action: machine_pay, portal, purchases)
- bootstrap_agent, create_api_key (tools allow-list uses per-operation ACL names such as kvp_put)
- manage_kv (action: put, get, delete, list), manage_memory (action: put, get)
- index_document (kind: file, note), search_documents (source: documents, memory), list_files (view: files, supported_types), get_storage_summary, finish_run
- contact_support (Pro; emails the Tillpad team; replies go to the account email)
- manage_inbox (action: create, list, get, delete, audit), read_inbox_message (action: list, get, raw, attachment)
- manage_inbox_webhook (action: create, list, delete, deliveries), manage_inbox_blocklist (action: list, add, delete)
- manage_schedule (action: create, list, get, delete, runs)

## Receive-only email inboxes

Domain from `GET https://tillpad.dev/api/config` → `inboundEmailDomain` (default `centralmail.us`).

```
curl -s -X POST "https://tillpad.dev/api/inboxes" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"localPart":"my-agent","kind":"temporary","ttlSeconds":86400}'
```

Register webhooks for `email.received` (metadata only; HMAC-signed POST):

```
curl -s -X POST "https://tillpad.dev/api/inboxes/webhooks" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/tillpad"}'
```

List delivery failures (after 3 attempts):

```
curl -s "https://tillpad.dev/api/inboxes/webhooks/failures" -H "Authorization: Bearer tp_…"
```

Block a sender address or entire domain (applies to all account inboxes):

```
curl -s -X POST "https://tillpad.dev/api/inboxes/blocklist" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"kind":"domain","value":"spam.example"}'
```

Local dev without Email Routing: `POST https://tillpad.dev/api/_dev/inbound-email/simulate` (`ENVIRONMENT=local` only).

## Scheduled HTTPS jobs

Create an interval schedule (min 5 minutes). Each attempt meters `outbound_http` (and each `notify_webhook` action); auto-disables after consecutive exhausted failures (default 5).

```
curl -s -X POST "https://tillpad.dev/api/schedules" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"name":"ping","url":"https://example.com/health","method":"GET","intervalMinutes":15}'
```

List runs (`status=failed` for exhausted failures):

```
curl -s "https://tillpad.dev/api/schedules/runs?status=failed" -H "Authorization: Bearer tp_…"
```

## Memory conventions

Scopes: `prefs`, `facts`, `run` (run → run key namespace when using a run key).

```
curl -s -X PUT "https://tillpad.dev/api/memory/prefs/theme" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"value":"dark"}'
```

```
curl -s -X POST "https://tillpad.dev/api/memory/search" \
  -H "Authorization: Bearer tp_…" -H "Content-Type: application/json" \
  -d '{"query":"preferred theme","scope":"prefs","topK":5}'
```

## Endpoint groups

- Bootstrap: POST /api/agents/bootstrap (no auth; rate limited; emailed code required)
- Auth: /api/auth/*
- Keys: /api/keys (kind: account|run|sub; create requires active Pro)
- Runs: /api/runs/{keyId}/finish, /api/wipe-receipts/{id}
- Budget: /api/budget, /api/budget/estimate
- Billing: /api/billing/checkout, /api/billing/machine-pay, /api/billing/portal, /api/billing/invoices, /api/billing/purchases
- Support: /api/support/contact (Pro; contact Tillpad support)
- KVP: /api/kvp/{namespace}/{key}
- Memory: /api/memory/{scope}/{key}, POST /api/memory/search (scopes: prefs|facts|run)
- Files: /api/files/* (GET /api/files/types for supported uploads)
- RAG: /api/rag/notes, /api/rag/search
- Inspect: /api/inspect/* · DELETE /api/namespaces/{name}
- Inboxes: /api/inboxes, /api/inboxes/{id}/messages, /api/inboxes/webhooks, /api/inboxes/webhooks/failures, /api/inboxes/webhooks/deliveries, /api/inboxes/blocklist, /api/inboxes/audit
- Schedules: /api/schedules, /api/schedules/{id}, /api/schedules/runs
- Spec: https://tillpad.dev/openapi.json · UI: https://tillpad.dev/swagger