# BillTurn

> Household bill tracker: recurring bills and due dates, statement PDFs with AI-extracted data (amounts, usage), trends, payments and loan amortization.

## Access for agents
- Create an API token in the web app: Settings → API & agents. Send it as `Authorization: Bearer <token>`.
- MCP (Streamable HTTP): https://billturn.com/mcp
- REST + OpenAPI 3.1: https://billturn.com/api/openapi.json

## MCP tools
- list_bills: List the user's bills with schedule description and next due date.
- get_bill: Get one bill by id, including its extraction fields and loan terms.
- create_bill: Create a recurring bill (or a loan with amortization terms).
- update_bill: Update fields of an existing bill. Only provided properties change.
- delete_bill: Permanently delete a bill and its payment history. Statements are kept but unlinked.
- upcoming_bills: Due dates in a window (default: next 30 days, unpaid only) with expected or actual amounts.
- mark_bill_paid: Record a payment for a bill occurrence. dueDate must be the scheduled date from upcoming_bills ("date").
- unmark_payment: Delete a recorded payment by id.
- list_payments: Payment history, optionally filtered by bill and due-date range.
- list_statements: Uploaded statement PDFs and their extracted data. Filter by billId or status (pending|processing|done|error|skipped).
- get_statement: One statement with extracted values and a fileUrl to download the PDF (send the same Bearer token).
- upload_statement: Upload a bill PDF (base64) and optionally link it to a bill. Processing follows the bill/account AI mode. Fails with code "duplicate" (and existingId) if the same file is already uploaded.
- update_statement: Correct a statement's bill link, amount, dates or custom data values.
- process_statement: Run server-side OpenAI extraction for a statement now (needs the user's OpenAI key in settings).
- process_queue_openai: Extract the next queued statements (pending in any AI mode; failed ones too unless retryFailed=false) with OpenAI on the server, up to `limit` (1-5, default 3) per call. Call again with the returned startedAt until processed is empty; remaining is how many are left.
- claim_pending_extractions: Claim statements waiting for AI extraction (default: those in "codex_local" mode). Returns each statement with the bill's field list. Claims expire after 15 minutes.
- submit_extraction: Save extracted values for a statement. values = {amount_due, due_date, statement_date, period_start, period_end, <field keys…>, notes}. Use null when absent.
- get_trends: Time series of processed statements: amount and extracted data per statement (optionally one field), for charts and comparisons.
- loan_amortization: Amortization for a loan bill: payment, totals, current status, and (unless summaryOnly) the full schedule.

## Key REST endpoints
- GET  /api/upcoming?days=30 — due dates with amounts
- POST /api/me/calendar — create or reset the secret ICS feed (user.calendarToken → https://billturn.com/cal/<token>.ics); DELETE turns it off
- GET  /api/bills, POST /api/bills, PATCH /api/bills/{id}
- POST /api/statements (application/pdf body, ?billId=&filename=) — upload a bill PDF (409 "duplicate" with error.existingId if the same file is already uploaded)
- POST /api/queue/process — extract everything queued with OpenAI on the server (repeat until processed is empty)
- POST /api/queue/claim — claim PDFs awaiting extraction; POST /api/statements/{id}/extraction — submit values
- POST /api/payments {billId, dueDate} — mark paid
- GET  /api/trends?billId=&field=kwh
- GET  /api/bills/{id}/amortization