REST API overview

The REST API operates on records in one BlueSuite workspace. Each resource page lists the supported operations, required scopes, request fields, and behavior. Some resources are read-only or have dedicated actions rather than unrestricted create/update/delete operations.

Base URL

https://my.bluesuite.app/api/v1

Use a Bearer API key and Content-Type: application/json for JSON writes. File uploads use multipart form data. See authentication for API keys and OAuth.

Record IDs in paths are positive integers. User/profile IDs are UUIDs from Users. Keep all related IDs in the same workspace.

Pagination and filters

Most lists accept these parameters; the resource page lists exceptions and additional filters.

Use pagination.total_pages to decide whether to fetch another page. Do not infer the total record count from page size. Quote/job/invoice/request status lists use comma-separated values where documented. Contact/request/quote/job/invoice tag filters match any selected tag.

Resources with a strict sort-column list reject unsupported values with a field-level error. Other resources fall back to default ordering when the shared sort whitelist does not recognize the column.

Responses and errors

Most successful reads/updates return 200; creation returns 201. A single result uses { "success": true, "data": ... }. A paginated list looks like:

{
  "success": true,
  "data": [{"id": 42, "first_name": "Jamie", "last_name": "Rivera"}],
  "pagination": {"page": 1, "per_page": 25, "total_pages": 1}
}

Entity responses may contain expanded related records. Fields vary by operation, workspace features, and permissions. Tag assignments return an unpaginated array. The user PATCH route omits success; legacy webhook and form APIs have their own envelopes.

Errors normally contain success: false, an error string, and optional details. Validation details identify the affected field path.

Treat error messages and field details as the source for correcting a request. Do not blindly retry writes: most creation endpoints do not offer an idempotency key. A failed multi-step operation can have already created a record.

Rate limits

API-key v1 requests use a limit of 1,000 requests per one-hour window per key. Responses after rate-limit evaluation include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). A 429 also includes Retry-After in seconds. Honor these headers instead of polling aggressively. Public forms use separate limits.

Dates, amounts, and updates

Use the workspace timezone for local scheduling dates and times. Timed events require both times unless explicitly all-day; timestamps such as payment dates need an offset. Check the resource guide for whether a field is a calendar date, clock time, or timestamp.

Monetary amounts use the workspace currency. Time-entry total_time is minutes, not hours. Missing fields on partial updates are generally preserved; null only clears a value where the schema allows it. Many JSON write bodies are strict and reject unknown fields.

Schema tables show structural requirements. Cross-field rules, state checks, and permissions still apply. The downloadable request reference contains the full JSON schemas, including nested fields; it is a request reference, not an OpenAPI response specification.

Line items

Quotes, jobs, invoices, quote templates, and visit line-item replacement accept up to 500 rows. A regular row has name, unitPrice, and optional quantity (default 1), description, unitCost, taxable, and optional. unitCost must be nonnegative and is used when cost tracking is enabled. _type defaults to lineItem when omitted.

[
  {"name":"Window cleaning","quantity":2,"unitPrice":75,"taxable":true},
  {"_type":"image","image_path":"workspaces/123/example.png","image_id":456,"description":"Work area"}
]

For image rows, first upload a workspace line-item image through Uploads, then use its returned storage path as image_path and upload-link id as image_id. Do not invent storage paths. Submitting a line-item array replaces that scope's list; retain every row you intend to keep. Job scope locks can reject pricing changes.

Resources