REST API
The REST API at /api/v1 lets your own scripts and other systems read and write your data with scoped keys.
Keys
Create keys on the REST API screen (under Website). For each key choose:
- Scopes: read and/or write, per resource.
- An optional rate limit in requests per minute.
- An optional IP allow-list.
- An optional expiry date.
The full key, which starts with cvn_sk_, is shown once when you create it. Only a hash is stored, so copy it then. Keys can be archived, restored or deleted, and the screen shows each key's last use and request count.
Sending the key
Send the key in a header on every request, in either form:
Authorization: Bearer cvn_sk_your_key
X-API-Key: cvn_sk_your_key
Keys in the query string are not accepted, because URLs end up in logs and browser history.
Resources
| Group | Resources | Access |
|---|---|---|
| Commerce | products, customers, orders, inventory | Read and write |
| Service | repairs, servicecalls, appointments, rmas, tradeins, tickets | Read and write |
| Finance | invoices, sales, payments, giftcards | Read only |
| Marketing | posts, subscribers, newsletters, social, reviews | Read only |
Finance and content resources are read-only through the API on purpose: they change through their own screens, so the books stay balanced.
Each read-write resource follows the same pattern:
| Request | Does |
|---|---|
GET /api/v1/{resource} |
List records |
GET /api/v1/{resource}/{id} |
Fetch one record |
POST /api/v1/{resource} |
Create a record |
PUT or PATCH /api/v1/{resource}/{id} |
Update a record |
DELETE /api/v1/{resource}/{id} |
Delete a record |
GET /api/v1 lists the resources and echoes your key's label and scopes.
Lists
List requests take page and pageSize, q for a free-text search, sort and order (asc or desc), and exact-match filters on a field, such as ?status=pickup. Responses include data, page, pageSize and total.
curl "https://your-domain/api/v1/repairs?status=pickup&pageSize=25" \
-H "Authorization: Bearer cvn_sk_your_key"
Responses and errors
Every response is JSON with a success flag. Errors add an error code and a message:
| Status | Error | Meaning |
|---|---|---|
| 401 | unauthorized, invalid_key |
Missing, wrong, archived or expired key |
| 403 | forbidden |
The key lacks the resource's read or write scope |
| 403 | ip_blocked |
The request's IP address is not on the key's allow-list |
| 404 | unknown_resource, not_found |
No such resource or record |
| 429 | rate_limited |
Too many requests this minute |
| 400 | https_required |
The API requires HTTPS |
| 503 | api_disabled |
The API is switched off |
API settings
The REST API screen's settings switch the API on or off and set the defaults: whether HTTPS is required, the default rate limit, allowed browser origins (no wildcard), a global IP allow-list, page sizes and how long request logs are kept. Every request is logged with its method, path, resource, status and timing, and the screen charts usage by day, resource and key.