# Numbors — Agent-First Accounting
# https://app.numbors.com
# CLI: npm install -g numbors

## Quick Start
numbors signup my-company --email me@co.com   # Get API key + £1 activation
numbors login --local --key nb_xxx             # Save key
numbors do "Invoice Acme for 10hrs at £150/hr" # Create draft invoice
numbors do "Log £45 lunch at Pret"             # Record expense
numbors do "Reconcile current account for May" # Auto-match bank transactions
numbors status                                 # Company τ tree overview

## MCP (Claude Code)
Add to .mcp.json:
{"mcpServers":{"numbors":{"type":"stdio","command":"numbors","args":["mcp-serve"]}}}

## Auth
X-API-Key: nb_xxx (header) or NUMBORS_API_KEY env var or .numbors/config.json

## Agent-First Command (NL)
POST /api/support/chat {message, sessionId}
→ Auto-routes action intents through autonomy tiers (INFORM/SUGGEST/ACT_SAFE/ACT_FULL)

## Context Tree
GET /api/context/tree → compact τ tree (~300 tokens)
GET /api/context/tree?branch=invoices.overdue → drill down

## API Endpoints (all require X-API-Key)

### Documents (invoices, bills)
GET  /api/documents?type=invoice&status=draft&limit=25
POST /api/documents {type,contact,items,currency,notes}
GET  /api/documents/:id
PUT  /api/documents/:id
DELETE /api/documents/:id

### Estimates
GET  /api/estimates
POST /api/estimates
GET  /api/estimates/:id
PUT  /api/estimates/:id
DELETE /api/estimates/:id

### Credit Notes
GET  /api/credit-notes
POST /api/credit-notes

### Orders
GET  /api/sales/orders
POST /api/sales/orders
GET  /api/purchases/orders
POST /api/purchases/orders

### Contacts
GET  /api/contacts?type=customer&q=search
POST /api/contacts {name,email,type,phone,address}
GET  /api/contacts/:id
PUT  /api/contacts/:id
DELETE /api/contacts/:id

### Items
GET  /api/items
POST /api/items {name,salePrice,type}

### Banking
GET  /api/accounts
POST /api/accounts {name,type,currency}
GET  /api/transactions?type=expense&limit=25
POST /api/transactions {type,amount,description,account}

### Bank Feeds
GET  /api/banking/feeds
GET  /api/banking/feeds/connections
POST /api/banking/feeds/connections

### Categories / Taxes / Currencies
GET  /api/categories?type=expense
POST /api/categories
GET  /api/taxes
POST /api/taxes
GET  /api/currencies
POST /api/currencies

### Accounting
GET  /api/accounting/chart-of-accounts
POST /api/accounting/chart-of-accounts
GET  /api/accounting/journal
POST /api/accounting/journal {entries:[{account,debit,credit}]}

### Inventory
GET  /api/inventory/warehouses
POST /api/inventory/warehouses
GET  /api/inventory/transfers
POST /api/inventory/transfers
POST /api/inventory/adjustments

### Projects & Time
GET  /api/projects
POST /api/projects {name,client,budget}
GET  /api/projects/:id
PUT  /api/projects/:id
POST /api/projects/:id/tasks
GET  /api/projects/time
POST /api/projects/time {project,hours,description}

### Payroll
GET  /api/payroll/departments
POST /api/payroll/departments
GET  /api/payroll/employees
POST /api/payroll/employees
GET  /api/payroll/pay-runs
POST /api/payroll/pay-runs

### POS
GET  /api/pos/terminals
POST /api/pos/terminals
GET  /api/pos/sessions
POST /api/pos/sessions/open
POST /api/pos/orders
GET  /api/pos/loyalty
POST /api/pos/loyalty/programs

### CRM
GET  /api/crm/pipelines
POST /api/crm/pipelines
GET  /api/crm/leads
POST /api/crm/leads
GET  /api/crm/deals
POST /api/crm/deals
GET  /api/crm/activities
POST /api/crm/activities
GET  /api/crm/campaigns
POST /api/crm/campaigns

### Contracts & Proposals
GET  /api/contracts
POST /api/contracts
GET  /api/contracts/proposals
POST /api/contracts/proposals

### Helpdesk
GET  /api/helpdesk/categories
POST /api/helpdesk/categories
GET  /api/helpdesk/tickets
POST /api/helpdesk/tickets
GET  /api/helpdesk/slas
POST /api/helpdesk/slas
GET  /api/helpdesk/articles
POST /api/helpdesk/articles

### AI Insights
POST /api/ai-insights/analyse {reportType,period}
reportTypes: profit-loss,balance-sheet,cash-flow,tax-summary,aged-receivables,ratio-analysis,cash-runway,board-package,forecast

### Agent Actions
GET  /agent-actions/api/pending
GET  /agent-actions/api/recent
POST /agent-actions/api/:id/approve
POST /agent-actions/api/:id/reject
POST /agent-actions/api/:id/rollback

### Modules
GET  /api/modules/enabled
GET  /api/modules/check/:alias

## Autonomy Tiers
INFORM: read-only (reports, lists, queries)
SUGGEST: preview + human approval (month-end, VAT)
ACT_SAFE: auto-execute, 5-min rollback (invoices, expenses, contacts)
ACT_FULL: requires admin approval (send invoice, HMRC submission)

## 60 MCP Tools
numbors mcp-serve (stdio, JSON-RPC 2.0, protocol 2024-11-05)
35 read + 25 write tools covering all modules above.