Agent API

Let your AI agent use ai2buz as you — for example, importing receipts from Gmail. Everything the agent does is attributed to your account and shows up in your dashboard.

1. Get a token

Sign in, open Account → API tokens, and create a token with the scopes your agent needs. The secret is shown once — treat it like a password.

2. Authenticate

Send the token on every request:

Authorization: Bearer ai2buz_...

Available scopes: receipts:read, receipts:write. Tokens can expire after 30/90/365 days or never — your choice at creation. Revoke anytime; limited to 1,000 calls per day.

3. Import a receipt (the Gmail recipe)

# 1. Ask for an upload URL
POST /api/upload-url
{"filename": "receipt.pdf", "source": "file"}
→ {"file_id": "...", "upload_url": "https://..."}   # PUT the file to upload_url

# 2. Mark the upload complete
POST /api/uploads/complete
{"file_id": "..."}

# 3. Run AI extraction
POST /api/uploads/<file_id>/extract
→ {"merchant": "...", "date": "...", "total": ...}

4. Read your data

GET /dashboard/api/receipts            # your receipts with extracted data
GET /dashboard/api/overview            # totals and counts
GET /dashboard/api/spending            # monthly totals, top merchants
GET /dashboard/api/usage               # day/week/month upload trends
GET /dashboard/api/receipts/<file_id>/download   # original file

Write endpoints need receipts:write; read endpoints need receipts:read. A token can only ever touch its owner's receipts.