CRMcy Docs

API overview

Auth, pagination, errors, and rate limits for the CRMcy REST API.

Last updated 2026-05-05

The CRMcy REST API is served at https://api.crmcy.app. Every request requires a Bearer token (Authorization: Bearer <jwt>); tokens are minted via the auth flow on the staff app or via the POST /api/auth/token endpoint with email + password + optional TOTP. Tenant scope is encoded in the JWT — there is no separate X-Tenant header. All responses are JSON, all timestamps are ISO 8601 in UTC, and IDs are ULIDs sorted by creation time.

Pagination is cursor-based: list endpoints accept limit (default 50, max 200) and cursor; responses include nextCursor (null on the last page). Filters are query parameters, validated against a Zod schema per endpoint — invalid filters get a 400 with the offending field path. Rate limits are 600 req/min per token and 60 req/min per unauthenticated IP; exceeding either returns 429 with a Retry-After header.

Errors

Errors follow a consistent envelope:

{
  "code": "VALIDATION_FAILED",
  "message": "first error message",
  "issues": [
    { "path": "customer.email", "message": "must be a valid email" }
  ],
  "requestId": "01HZ..."
}

Common codes: UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, VALIDATION_FAILED, CONFLICT, RATE_LIMITED, INTERNAL.

Related