# 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; budget_get / budget_estimate)
4. Run keys with wipe receipts; capability-scoped subkeys
5. Inspect namespaces / usage quotas

## Authentication

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

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

## Zero-human bootstrap

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

Then `POST https://tillpad.cnrcode.com/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.cnrcode.com/terms · https://tillpad.cnrcode.com/privacy · https://tillpad.cnrcode.com/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.cnrcode.com/api/config` → `plans.agentSkus`. 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.
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; after subscribing you get included monthly usage, then Stripe overage up to the spend ceiling.
Included monthly amounts come from plan vars; overage → Stripe; 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.cnrcode.com/scratchpad.txt](https://tillpad.cnrcode.com/scratchpad.txt): mint run key → KVP → upload/search → `run_finish` → wipe receipt.
Human copy: [https://tillpad.cnrcode.com/docs/scratchpad](https://tillpad.cnrcode.com/docs/scratchpad).

## Example

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

```
curl -X POST "https://tillpad.cnrcode.com/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.cnrcode.com/mcp` with the same Bearer key.

- agent_bootstrap, keys_create, budget_get, budget_estimate, billing_machine_pay ({ sku? }), usage_get
- kvp_put, kvp_get, kvp_delete, kvp_list
- file_upload, files_list, files_types, rag_search, inspect_storage, run_finish
- support_contact (Pro; emails the Tillpad team; replies go to the account email)

## Endpoint groups

- Bootstrap: POST /api/agents/bootstrap (no auth; rate limited)
- 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
- Support: /api/support/contact (Pro; contact Tillpad support)
- KVP: /api/kvp/{namespace}/{key}
- Files: /api/files/* (GET /api/files/types for supported uploads)
- RAG: /api/rag/search
- Inspect: /api/inspect/* · DELETE /api/namespaces/{name}
- Spec: https://tillpad.cnrcode.com/openapi.json · UI: https://tillpad.cnrcode.com/swagger