{"openapi":"3.0.3","info":{"title":"TowOps Public API","version":"1.0.0","description":"RESTful API for external integrations with TowOps tow dispatch SaaS. Authenticate with `Authorization: Bearer <api_key>` on all requests.","contact":{"name":"TowOps Support","email":"api@towops.example.com"},"x-llms-txt":"https://towops.xyz/llms.txt","x-mcp-endpoint":"https://towops.xyz/api/mcp","x-mcp-manifest":"https://towops.xyz/api/mcp/manifest","x-agent-docs":"https://towops.xyz/docs/agents"},"x-speakeasy-name-override":"towops","servers":[{"url":"/api/v1","description":"Production"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"API key obtained from Settings → API Keys in the TowOps dashboard."},"agentBearer":{"type":"http","scheme":"bearer","description":"Agent-scoped API key (prefix: tk_agent_) from Settings → Agent Keys. Required for MCP-compatible AI agent access with fine-grained scopes."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional UUID for idempotent writes. Same key + tenant within 24h returns the cached response. X-Idempotency-Replay: true header is set on replays."},"DryRun":{"name":"X-TowOps-Dry-Run","in":"header","required":false,"schema":{"type":"string","enum":["true"]},"description":"Set to \"true\" to validate and preview what a write operation would do without persisting."}},"headers":{"XRequestId":{"description":"Unique request identifier for support and tracing.","schema":{"type":"string"}},"XIdempotencyReplay":{"description":"Present and set to \"true\" when the response was served from idempotency cache.","schema":{"type":"string","enum":["true"]}},"XRateLimitRemaining":{"description":"Approximate remaining calls in the current rate limit window.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object"}},"requestId":{"type":"string"}}}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"status":{"type":"string","enum":["draft","needs_review","approved","sending","sent_to_roadsync","viewed","partially_paid","paid","overdue","disputed","failed","void","cancelled"]},"customer_id":{"type":"string","format":"uuid","nullable":true},"billing_email":{"type":"string","format":"email","nullable":true},"po_number":{"type":"string","nullable":true},"due_date":{"type":"string","format":"date-time","nullable":true},"service_date":{"type":"string","format":"date-time","nullable":true},"subtotal_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"paid_cents":{"type":"integer"},"balance_due_cents":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WorkOrder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"job_number":{"type":"string"},"status":{"type":"string","enum":["pending","dispatched","in_progress","completed","cancelled"]},"billing_status":{"type":"string"},"service_type":{"type":"string"},"customer_id":{"type":"string","format":"uuid","nullable":true},"pickup_location":{"type":"string","nullable":true},"dropoff_location":{"type":"string","nullable":true},"dispatch_time":{"type":"string","format":"date-time","nullable":true},"completion_time":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_name":{"type":"string"},"company_type":{"type":"string"},"billing_email":{"type":"string","format":"email","nullable":true},"primary_phone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PaginatedResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array"},"cursor":{"type":"string","nullable":true,"description":"Pass as ?cursor= to get the next page"},"count":{"type":"integer"}}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/invoices":{"get":{"summary":"List invoices","operationId":"listInvoices","x-tags":["agent-friendly"],"x-mcp-tool-name":"list_invoices","tags":["Invoices"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by invoice status"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from previous response"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Paginated invoice list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create invoice","operationId":"createInvoice","x-tags":["agent-friendly"],"x-mcp-tool-name":"create_invoice_draft","tags":["Invoices"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/DryRun"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoice_number"],"properties":{"invoice_number":{"type":"string"},"customer_id":{"type":"string","format":"uuid"},"billing_email":{"type":"string","format":"email"},"po_number":{"type":"string"},"service_date":{"type":"string","format":"date-time"},"due_date":{"type":"string","format":"date-time"},"vehicle_description":{"type":"string"},"notes":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","required":["name","category","quantity","unit_type","unit_price_cents","total_cents"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"quantity":{"type":"number"},"unit_type":{"type":"string"},"unit_price_cents":{"type":"integer"},"total_cents":{"type":"integer"},"taxable":{"type":"boolean"}}}}}}}}},"responses":{"201":{"description":"Invoice created"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}":{"get":{"summary":"Get invoice","operationId":"getInvoice","x-tags":["agent-friendly"],"x-mcp-tool-name":"get_invoice","tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update invoice","operationId":"updateInvoice","x-tags":["agent-friendly"],"tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/DryRun"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"billing_email":{"type":"string","format":"email"},"po_number":{"type":"string"},"due_date":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated"},"404":{"description":"Not found"}}}},"/work-orders":{"get":{"summary":"List work orders","operationId":"listWorkOrders","x-tags":["agent-friendly"],"x-mcp-tool-name":"list_work_orders","tags":["Work Orders"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated work order list"}}},"post":{"summary":"Create work order","operationId":"createWorkOrder","x-tags":["agent-friendly"],"x-mcp-tool-name":"create_work_order","tags":["Work Orders"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/DryRun"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_type"],"properties":{"service_type":{"type":"string"},"pickup_location":{"type":"string"},"dropoff_location":{"type":"string"},"vin":{"type":"string"},"contact_name":{"type":"string"},"contact_phone":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/customers":{"get":{"summary":"List customers","operationId":"listCustomers","x-tags":["agent-friendly"],"x-mcp-tool-name":"list_customers","tags":["Customers"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated customer list"}}},"post":{"summary":"Create customer","operationId":"createCustomer","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_name"],"properties":{"company_name":{"type":"string"},"company_type":{"type":"string"},"billing_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}}}}