For developers
Connect your tools to a PlowTrail shop
Every shop can issue its own API keys under Settings → API & MCP. Keys are shown once, stored as a hash, and can be revoked at any time. The same key authenticates the public REST API and the MCP server.
Authentication
Send the key as a Bearer token or an X-Api-Key header. Never put a key in a query string or a public repo.
Authorization: Bearer YOUR_API_KEY
REST API
Versioned at https://plowtrail.com/api/v1. GET https://plowtrail.com/api/v1 lists every resource and the scope it needs. List endpoints accept page and per_page (max 100, default 25) and return data plus a meta object. Money amounts are decimal strings such as "12.00". Dates are ISO 8601 in the shop’s timezone.
Example: list customers
curl https://plowtrail.com/api/v1/customers?q=Casey \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json"
Example: create a customer
curl -X POST https://plowtrail.com/api/v1/customers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Casey Customer","email":"casey@example.com","address":"12 Pine St"}'
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/shop | shop:read |
| GET | /api/v1/customers | customers:read |
| GET | /api/v1/customers/{id} | customers:read |
| POST | /api/v1/customers | customers:write |
| POST | /api/v1/customers/{id}/notes | customers:write |
| GET | /api/v1/invoices | invoices:read |
| GET | /api/v1/invoices/{id} | invoices:read |
| GET | /api/v1/quotes | quotes:read |
| GET | /api/v1/quotes/{id} | quotes:read |
| GET | /api/v1/bookings | bookings:read |
| GET | /api/v1/bookings/{id} | bookings:read |
| GET | /api/v1/visits | visits:read |
| GET | /api/v1/visits/{id} | visits:read |
Filters: q on customers, invoices, and quotes; status and customer_id on invoices, quotes, and bookings; from / to (ISO 8601) on visits. Write scopes are opt-in when you create a key; new keys default to read-only.
MCP server
The Model Context Protocol endpoint is https://plowtrail.com/mcp. It speaks JSON-RPC 2.0 over HTTP (Streamable HTTP). A GET request returns endpoint info. POST requests must include a valid API key.
Claude Desktop or Cursor
{
"mcpServers": {
"plowtrail": {
"url": "https://plowtrail.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Tools cover the same shop data as the REST API: shop info, customers (search, get, create, add a note), invoices, quotes, bookings, and visits. Write tools require the customers:write scope.
Errors and rate limits
60 requests per minute per API key. JSON errors use an error code (unauthorized, forbidden, not_found, validation) and a message. Responses include standard rate-limit headers.
