# BigShop API

> REST API for BigShop, a truck and fleet repair shop management platform. Read work orders, customers, vehicles, inventory, purchase orders, reports and the daily Smart Digest; create records with a full-access key. Built to be used by AI agents.

Base URL: https://api.bigshopai.com/v1
Auth: `Authorization: ApiKey bsk_live_...` (create a key in the BigShop app under Admin > API Keys).
Use a READ-ONLY key for agents: it can call GET endpoints only, never returns credentials or sharing links, and hides employee pay data unless the key was created with includePayData.

## Conventions an agent must follow
- Money is integer cents unless an operation's `x-money-units` says otherwise. Report endpoints mix decimal dollars and cents.
- Dates are shop-local YYYY-MM-DD, inclusive at both ends.
- Pagination: pass `limit`; a response with `lastEvaluatedKey` has more, send it back as a query parameter. `truncated: true` means the result was capped.
- A record in another shop looks the same as a missing one: 404.
- Send `X-Agent-Name` and `X-Agent-Run-Id`. Send `Idempotency-Key` on creates you may retry.
- Fair use: about 3,000 requests per 5 minutes per key. Prefer webhooks (`digest.ready`, `work_order.status_changed`, ...) to polling.

## Docs
- [OpenAPI 3.1 spec](https://developer.bigshopai.com/openapi.json): every operation, parameters and response shapes. GET operations carry `x-read-only-key`.
- [Reports & Digests reference](https://developer.bigshopai.com/reports.html): sales, payments, tax, parts, receivables, dashboard and Smart Digest endpoints.
- [Connect an AI agent](https://developer.bigshopai.com/guides.html#ai-agents): read-only keys, MCP server, digest recipe.
- [API reference](https://developer.bigshopai.com/index.html)
- [Quickstart](https://developer.bigshopai.com/quickstart.html)