# TowOps
> Operational software for tow & recovery businesses. Dispatch, invoicing, DOT compliance, fleet management, and AI-powered automation.

TowOps provides a public REST API and MCP (Model Context Protocol) server for AI agents to:
- List, create, and update invoices and work orders
- List customers and search by type/name
- Read the live dispatch board
- Read audit logs (read-only)
- Queue human approval requests (AI proposes, humans approve)
- Run 8 specialist AI agents: triage, pricing, collections, compliance, dispatcher, insurance liaison, auction manager, orchestrator

## Quickstart
- Public API: https://towops.xyz/api/v1
- OpenAPI spec: https://towops.xyz/api/v1/openapi.json
- MCP endpoint: https://towops.xyz/api/mcp
- MCP manifest: https://towops.xyz/api/mcp/manifest
- Documentation: https://towops.xyz/docs
- LLMs.txt (this file): https://towops.xyz/llms.txt
- Full LLM reference: https://towops.xyz/llms-full.txt
- Agent docs: https://towops.xyz/docs/agents
- Skills docs: https://towops.xyz/docs/skills
- MCP setup: https://towops.xyz/docs/mcp

## Authentication
- Bearer token (API keys) on Authorization header: `Authorization: Bearer tk_agent_...`
- Agent-scoped keys are recommended for AI use (prefix: `tk_agent_`)
- Generate agent keys at: https://towops.xyz/settings/agents
- Regular integration keys (prefix: `tk_`) also work for REST API

## Permissions (Scopes)
Agent keys are issued with fine-grained scopes:
- `read_invoices` — list and read invoices
- `write_invoices_draft` — create invoice drafts (never auto-sends)
- `read_work_orders` — list and read work orders
- `write_work_orders` — create new work orders
- `read_customers` — list and search customers
- `read_dispatch` — read the live dispatch board
- `read_audit` — search the audit log
- `propose_approvals` — queue human approval requests for invoices

## Human Approval Model
TowOps enforces "AI proposes, humans approve":
- AI can create DRAFT invoices — they are never sent without human review
- AI can PROPOSE approval of an invoice via the `propose_invoice_approval` MCP tool
- A human operator must review and approve before the invoice is sent
- No MCP tool directly approves, sends, or voids an invoice

## Idempotency
All write requests support an Idempotency-Key header. Use a UUID per logical operation.
Replays within 24h return the cached response with X-Idempotency-Replay: true.
Example: `Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000`

## Dry Run
Send `X-TowOps-Dry-Run: true` on any write request to preview what would happen
without persisting any data. Useful for testing and agent validation.

## Rate Limits
- Starter tier: 60 calls/min, 1,000 calls/hr
- Standard tier: 300 calls/min, 5,000 calls/hr
- Premium tier: 1,000 calls/min, 20,000 calls/hr
Rate limit exceeded returns HTTP 429 with Retry-After.

## AI Agents
TowOps runs 8 specialist AI agents. All follow human-in-the-loop — agents propose, humans approve.
- triage — classifies new work orders, assigns priority, routes jobs
- pricing — proposes invoice line items from completed work orders (uses rate-card-lookup, scene-photos-summary skills)
- collections — drafts dunning emails, handles motor club rebills (uses draft-dunning-email, motor-club-rebill skills)
- compliance — daily DOT 49 CFR scan for CDLs, medical cards, HOS, inspections (uses compliance-snapshot skill)
- dispatcher — validates truck/driver eligibility before dispatch (uses truck-eligibility-check skill)
- insurance_liaison — supplement requests, adjuster escalation
- auction_manager — state-specific lien notice timelines, impound auction management (uses lien-notice-timer skill)
- orchestrator — multi-agent workflow coordination

## Skills System
Skills are composable capabilities agents invoke. Each has a SKILL.md, Zod schema, and implementation.
Skills: draft-dunning-email, rate-card-lookup, lien-notice-timer, motor-club-rebill, scene-photos-summary, customer-payment-history, truck-eligibility-check, compliance-snapshot
Full reference: https://towops.xyz/docs/skills

## MCP Quick Reference (Claude Desktop / compatible agents)
See https://towops.xyz/docs/mcp for the full Claude Desktop config snippet.
MCP endpoint: https://towops.xyz/api/mcp (POST, JSON-RPC 2.0, protocol 2024-11-05)

Available MCP tools:
- list_invoices — paginated invoice list with status filter
- get_invoice — single invoice with line items
- create_invoice_draft — create a draft invoice (requires human approval to send)
- list_work_orders — paginated work order list
- get_work_order — single work order details
- create_work_order — create a new job/work order
- list_customers — search and list customers
- get_dispatch_board — live dispatch board snapshot
- search_audit_log — filter audit log by entity, actor, date range
- propose_invoice_approval — queue a human approval request (does NOT approve)