Conventions and errors

Base URL and format

https://app.atlahq.com/api/v1

Requests and responses are JSON. Send Content-Type: application/json on POST and PUT. Field names are camelCase.

Identifiers, dates and times

Kind	Format	Example
Id	UUID	0b7c3a1e-5d2f-4a8b-9c6d-1e2f3a4b5c6d
Date	YYYY-MM-DD	2026-11-03
Time of day	HH:MM or HH:MM:SS, facility wall-clock	07:00, 19:00:00
Timestamp	ISO 8601, UTC	2026-11-03T14:00:00.000Z
Local timestamp	YYYY-MM-DDTHH:MM[:SS], facility wall-clock, no offset	2026-11-03T07:00:00

Shift dates and times are always in the facility's time zone (each facility carries an IANA timezone). An overnight shift has an endTime earlier than its startTime. Shift events carry both a UTC timestamp and a localTimestamp rendered in the facility's zone; when you record one, prefer localTimestamp.

Lists and pagination

List routes return a flat array by default. Pass page to get a paginated envelope:

GET /orders?page=1&pageSize=100

{ "data": [ ... ], "total": 1342 }

pageSize defaults to 25 and is capped at 500. Needs and orders also accept from and to (shift date range), search, sort and sortDirection. Filters are listed per route in the reference.

Partial updates

PUT routes write only the keys you send. An omitted key leaves the field alone; an explicit null clears it. For example, to clear a provider's hourly rate:

{ "hourlyRate": null }

Errors

Every error is a JSON object:

{ "statusCode": 422, "statusMessage": "Provider is not cleared to work at this facility" }

Code	Meaning	What to do
400	Missing or malformed field, bad id, bad date or time	Fix the request. The message names the field
401	No key, malformed key, revoked key or expired key	Check the header; create a new key if it was revoked or expired
403	The key lacks the scope for this route, or the route is not available to keys	Create a key with the right scope
404	The record is not in your organization	Check the id
409	Conflict, for example deleting a facility that still has orders	Resolve the dependency first
422	A scheduling rule refused the change: provider disabled, not compliant, not cleared at the facility, marked unavailable	Fix the underlying condition in Atla, or pick another provider
429	Rate limit (600 per minute per key)	Wait Retry-After seconds
5xx	Atla had a problem	Retry with backoff. Persisting errors: contact Atla

Successful writes

Create routes answer { "success": true, "id": "<uuid>" }. Update and delete routes answer { "success": true }. Deletes of needs and orders are soft: the record stays, with status canceled.

Side effects

Writes through the API behave exactly like the same action in the Atla web app. Booking a provider on an order sends them the usual notification. Cancelling an order notifies the provider. Assigning a provider to a need creates the linked order. Expect the same rules too: a provider who is disabled, missing a required document, not cleared at the facility or marked unavailable that day is refused with 422.

Versioning

The path carries the major version (/api/v1). Within it, changes are additive only: new fields and new routes may appear; existing ones keep their names and meaning. Ignore fields you do not recognise. The API changelog lists every change.