OpenAPI specification: cws.yaml
CWS API Documentation (1.0)
This is the documentation for the CWS REST API.
Every endpoint needs a Bearer token in the Authorization header:
Authorization: Bearer <access_token>
Tokens come from an API client. An account admin creates the client on a user's page in CWS (Admin > Users, open the user, API Clients). CWS shows the Client ID and Client Secret once.
Send them to POST /oauth/token with grant_type=client_credentials to receive an access token that lasts 1 hour. There is no refresh token: when the token expires (or a request answers 401), request a new one. Reuse a token until then rather than requesting one per call.
The token endpoint is at the root of your CWS host, not under /api/v1/: https://{systemId}.cws.app/oauth/token. A token works only at its own account's host; sent to another account's host it answers 401.
A token acts as its client's user, within that user's permissions: it can call an endpoint when the user holds the endpoint's permission through their user group. Each endpoint needs the permission the CWS screen showing the same data needs (for example wo.list, customer.view, report.open_stats), named in its description; the admin-only endpoints need an admin user. There are no scopes to choose: every token carries the single scope cws. To limit an integration, give its client a user with only the permissions it needs.
The API is rate limited to 60 requests per minute and 1000 requests per hour.
Both limits are applied per API user, so your requests are not affected by other integrations. Endpoints that do not require authentication are limited per IP address instead.
Each limit uses a sliding window rather than fixed clock minutes or hours, so allowance frees up continuously as older requests age out. Requests rejected for exceeding a limit do not consume quota in either window.
Every response includes the following headers so you can track usage:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Total allowance (requests per minute) |
X-RateLimit-Remaining | Requests remaining in the current minute window |
X-RateLimit-Reset | Unix timestamp when minute allowance starts to free up |
X-RateLimit-Limit-Hour | Total allowance (requests per hour) |
X-RateLimit-Remaining-Hour | Requests remaining in the current hour window |
X-RateLimit-Reset-Hour | Unix timestamp when hour allowance starts to free up |
When either limit is exceeded the API responds with HTTP 429 Too Many Requests and a Retry-After header giving the number of seconds to wait before retrying (based on whichever window was exceeded). A steady rate just under the limits is always safe; avoid bursting and back off when a Remaining header approaches zero.