API Overview

FreeMaint exposes two API surfaces over the same authenticated backend. REST is best for simple integrations and webhooks; GraphQL is best for clients that need to fetch deeply-nested data (work order with asset, parts, labor, comments) in a single round-trip. Both share the same data model, permissions, and tier gating.

REST API

Every CMMS resource (work orders, assets, parts, locations, users, requests, PM plans, vendors, customers, purchase orders) is available under /api/v1/{resource}. Pagination is offset-based via ?page=&pageSize=. Filters use plain query parameters: ?status=OPEN&priority=HIGH&assigneeId=42. Responses use a consistent envelope: { success, data, meta? } on success, { success: false, error } on failure.

GraphQL API

The GraphQL endpoint is POST /api/v1/graphql. It supports the full Query/Mutation surface for the same resources plus relationship traversal. Use GraphQL when you would otherwise have to call several REST endpoints to assemble one screen — for example, a dashboard tile that shows a work order with its asset details, parts used, and total labor cost.

Authentication

Both APIs accept a JWT bearer token in the Authorization header. Tokens are issued by POST /api/v1/auth/login with email/password (or loginIdentifier/password for username-based accounts). Tokens expire after 2 hours; use the refresh token from the login response to obtain a new one. For server-to-server integrations, generate a long-lived service-account token from Settings → Integrations.

Tier availability

Rate limits

Quota is enforced per user, per minute, on a sliding window. When you exceed your quota, the API responds with HTTP 429 Too Many Requests and a Retry-After header indicating how many seconds to wait. Bulk endpoints (POST /work-orders/bulk-create, GET /export/{entity}) count as a single request regardless of payload size.

Error format

Every error response carries an HTTP status, a stable machine-readable error code, and a human-readable message. 4xx codes are client errors (validation, permission, not found); 5xx are server errors and should be retried with exponential backoff. Structured codes you can pattern-match: VALIDATION_FAILED, INSUFFICIENT_PERMISSIONS, NOT_FOUND, TIER_FEATURE_LOCKED, RATE_LIMIT_EXCEEDED.

Official SDKs and tooling

There is no official client SDK today — the API surface is stable enough that any generated OpenAPI client works fine. We publish the OpenAPI 3.1 spec at /api/v1/openapi.json and the GraphQL SDL at /api/v1/graphql/schema. Both are versioned alongside the backend and updated on every deploy.