# Billbot
> Agent-first invoicing for solopreneurs

## API
Base URL: https://billbot.io/api
Auth: Bearer token with `bb_` prefix (get one from /settings)
OpenAPI spec: https://billbot.io/api/openapi
Interactive docs: https://billbot.io/docs

## Capabilities

### Invoices
- POST /api/invoices — Create invoice with client info and line items
- GET /api/invoices — List invoices (filter by status, date range, paginate)
- GET /api/invoices/export — Export invoices as CSV (filter by status, date range)
- GET /api/invoices/{id} — Get full invoice with line items
- PATCH /api/invoices/{id} — Update invoice fields or line items
- DELETE /api/invoices/{id} — Delete invoice and its PDF
- POST /api/invoices/{id}/pdf — Generate professional PDF
- POST /api/invoices/{id}/send — Email invoice to client with PDF attached

### Clients
- POST /api/clients — Create a reusable client contact
- GET /api/clients — List clients (optional search)
- GET /api/clients/{id} — Get client details
- PATCH /api/clients/{id} — Update client
- DELETE /api/clients/{id} — Delete client

### Settings
- PATCH /api/settings/profile — Update company info, bank details, invoice defaults
- POST /api/settings/profile/logo — Upload company logo (PNG/JPG/SVG, max 2MB)
- DELETE /api/settings/profile/logo — Remove company logo
- POST /api/settings/api-keys — Generate new API key
- DELETE /api/settings/api-keys?id={id} — Revoke API key

## MCP Server
Endpoint: POST https://billbot.io/api/mcp (Streamable HTTP transport)
Discovery: GET https://billbot.io/.well-known/mcp.json
Auth: Same Bearer token as REST API (bb_ prefix)

9 tools: create_invoice, list_invoices, get_invoice, generate_pdf,
send_invoice, create_client, list_clients, get_invoice_stats, export_invoices

## Health Check
GET https://billbot.io/api/health — Returns server and database status

## Quick Start
1. Get API key from https://billbot.io/settings
2. POST /api/invoices with client info and line items
3. POST /api/invoices/{id}/pdf to generate PDF
4. POST /api/invoices/{id}/send to email it to the client

## Authentication
Include your API key in the Authorization header:
Authorization: Bearer bb_your_api_key_here

## Create Invoice Example
POST /api/invoices
Content-Type: application/json

{
  "client_name": "Acme Corp",
  "client_email": "billing@acme.com",
  "client_address": "Straße des 17. Juni 135",
  "client_address_line2": "Sekretariat H 93",
  "client_city": "Berlin",
  "client_state": "Berlin",
  "client_zip": "10623",
  "client_country": "DE",
  "due_date": "2026-03-15",
  "currency": "EUR",
  "tax_rate": 19,
  "line_items": [
    {
      "description": "Web Development — February 2026",
      "quantity": 10,
      "unit_price": 150
    }
  ]
}

IMPORTANT: Address fields are separate. Do NOT put the full address in client_address.
- client_address: street only (e.g. "Hauptstraße 42")
- client_address_line2: apartment, suite, floor, c/o
- client_city: city name
- client_state: state or province
- client_zip: postal code
- client_country: ISO country code (DE, US, GB, etc.)

## Full Documentation
See llms-full.txt for complete API reference with all fields and responses.