# Tillpad — agent job scratchpad

Bounded storage and search for agent jobs

One loop: mint a temporary run key → store state → index + search → finish → signed wipe receipt.
Human UI: https://tillpad.cnrcode.com/docs/scratchpad
MCP: https://tillpad.cnrcode.com/mcp (same Bearer key; tools include agent_bootstrap, keys_create, kvp_*, file_upload, rag_search, run_finish, support_contact)

## Zero-human path (no OTP)

1. `POST https://tillpad.cnrcode.com/api/agents/bootstrap` with `{"email":"agent@example.com"}` → `bootstrapToken` (no outbound mail).
2. `POST https://tillpad.cnrcode.com/api/billing/machine-pay` with `Authorization: Bearer <bootstrapToken>` and optional `{"sku":"pro_prepaid_30d"}`.
3. Settle MPP ($9.00 for 30d) → response includes `secret` (`tp_…` account key) and `planPeriodEnd`.
4. Continue below with that account key instead of session JWT.

Terms: https://tillpad.cnrcode.com/terms · Privacy: https://tillpad.cnrcode.com/privacy · Refunds: https://tillpad.cnrcode.com/refunds

## Prerequisites (human or account key)

1. Active Pro (human Checkout at https://tillpad.cnrcode.com/pricing, agent bootstrap + machine-pay above, or `POST https://tillpad.cnrcode.com/api/billing/machine-pay` with account key when MPP is enabled). Unpaid accounts have no usable remaining quota.
2. Session JWT (email OTP), bootstrap-minted account `tp_` key, or an account key that can mint run keys.
3. `jq` optional for parsing JSON below.

Set:

```
BASE=https://tillpad.cnrcode.com
AUTH="Authorization: Bearer <session-or-account-tp-key>"
```

## 1. Mint a run key

```
curl -s -X POST "$BASE/api/keys" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"scratchpad-demo","kind":"run","ttlSeconds":3600,"opBudget":50,"wipeOnExpire":true}'
```

Save `secret` as `RUN_KEY`, `key.id` as `KEY_ID`, and `key.namespaces[0]` as `NS` (auto `run_…`).

```
RUN_AUTH="Authorization: Bearer $RUN_KEY"
```

## 2. Store scratch state (KVP)

```
curl -s -X PUT "$BASE/api/kvp/$NS/state" \
  -H "$RUN_AUTH" -H "Content-Type: application/json" \
  -d '{"value":{"job":"scratchpad-demo","note":"ephemeral agent state"}}'
```

Response includes `budget` / key op budget remaining.

## 3. Upload a note, wait for index, search

```
echo "Tillpad scratchpad demo: bounded storage for agent jobs." > /tmp/scratchpad-note.txt
curl -s -X POST "$BASE/api/files/$NS" \
  -H "$RUN_AUTH" \
  -F "file=@/tmp/scratchpad-note.txt;type=text/plain"
```

Poll until `status` is `ready` (async queue → embed → Vectorize):

```
FILE_ID=<id from upload>
curl -s -H "$RUN_AUTH" "$BASE/api/files/$FILE_ID"
```

Search inside the run namespace:

```
curl -s -X POST "$BASE/api/rag/search" \
  -H "$RUN_AUTH" -H "Content-Type: application/json" \
  -d "{\"query\":\"bounded storage for agent jobs\",\"namespace\":\"$NS\",\"topK\":3}"
```

## 4. Finish the run (wipe + receipt)

Session, account key, or the run key itself may finish:

```
curl -s -X POST "$BASE/api/runs/$KEY_ID/finish" -H "$RUN_AUTH"
```

Expect `receipt` with `signature` and `deleted` counts, plus `verified: true`.

## 5. Fetch the wipe receipt later

```
RECEIPT_ID=<receipt.id>
curl -s -H "$AUTH" "$BASE/api/wipe-receipts/$RECEIPT_ID"
```

## If you hit billing walls

402/429 bodies include `code`, `actions[{type:checkout|machine_pay,…}]`, and `budget`.
Do not invent a billing flow — open Checkout for humans, or `machine_pay` for agents when offered.

## Next

- Full agent guide: https://tillpad.cnrcode.com/llms-full.txt
- OpenAPI: https://tillpad.cnrcode.com/openapi.json
- Docs: https://tillpad.cnrcode.com/docs