Conventions

These hold across the whole surface. Reading this once saves rediscovering it per resource.

Versioning

The version is in the path: /api/public/v1/.

Additive changes — new fields, new endpoints, new optional parameters, new enum values — ship inside v1. Your client must tolerate them, which takes two habits: ignore response fields you don’t recognise, and don’t fail closed on an unfamiliar enum value.

Removals, renames, retypes, and anything that tightens validation bump the version, with an overlap window during which both are live.

List responses

Lists are cursor-paginated and always come back in the same envelope:

{
  "object": "list",
  "data": [ { "object": "shift", "id": "0194d1c0-…", "…": "…" } ],
  "has_more": true,
  "next": "https://app.shiftavo.com/api/public/v1/shifts/?cursor=…",
  "previous": null
}

• next and previous are opaque URLs. Follow them as-is; do not construct or parse cursors.

• Stop when has_more is false.

• page_size controls the page length.

The object discriminator

Every resource carries an "object" field naming its type — "shift", "location", "employee". Branch on it rather than on the shape of the payload, especially inside webhook handlers and mixed collections.

Related records

A related record comes back as a small {id, name} ref, under the same key you write its id to:

{
  "object": "budget",
  "id": "0194d1c0-…",
  "location": { "id": "0194d1b2-…", "name": "Zürich" }
}

• Write the id, read the ref. Send "location": "0194d1b2-…" on a create or update; every response carries "location": {"id": …, "name": …}. An unset optional relation reads null, and a many-to-many relation reads as a list of refs.

• name can be null where the record has none: shifts are unnamed (only general events carry a name), so a timesheet’s event reads {"id": "…", "name": null} for a shift.

• Related sets are left out unless you ask. GET …/events/<id>/?expand[]=attendees adds the event’s attendees as refs; without it the key is absent.

Errors

One envelope, everywhere:

{
  "error": {
    "type": "conflict_error",
    "code": "not_cancellable",
    "message": "…",
    "details": []
  }
}

• details is present on every 4xx — a list of field-level failures, empty when the error has no field breakdown. Don’t index into it unconditionally on a 5xx.

• param appears only when exactly one field is at fault.

There are nine types. Each maps to one status except invalid_request_error, the catch-all for the non-tabulated 4xx, where the code carries the distinction:

type	Status	Notes
invalid_request_error	400 · 405 · 406 · 415	code = invalid_request / method_not_allowed / not_acceptable / unsupported_media_type. A 405 means the resource doesn’t offer that verb at all — open_shifts and swaps are read-only — not that your token lacks a scope
idempotency_error	400	Idempotency-Key reused with a different body (idempotency_key_reused)
authentication_error	401	missing / invalid / expired token
plan_error	402	plan_required — the company’s subscription plan does not include this resource. Not a permission the token lacks; nothing to retry until the plan changes
permission_error	403	insufficient_scope, and friends
not_found	404	also returned instead of 403 for records outside your company — no existence leak
conflict_error	409	state conflicts: duplicate, in_use, not_deletable, already_approved, already_confirmed, owner_protected, an in-flight idempotent replay
rate_limit_error	429	carries Retry-After
api_error	5xx	our side: internal_error (500) / upstream_unavailable (502 — retry)

Branch on type for handling class, on code for the specific case. Both are stable; message is not — treat it as human-readable only.

Idempotency

Send an Idempotency-Key header on creates. A retried request then replays the first result instead of creating a second record.

Reusing a key with a different body is a 400 idempotency_key_reused — the key identifies one request, not one endpoint.

Request tracing

Every response, success and error alike, carries an X-Request-Id header. Log it. Send your own X-Request-Id and it is echoed back, so a trace id can travel end to end. Quote it in any support request.

Lifecycle transitions

A transition fires as a POST to an action sub-path: POST …/<id>/publish/, …/cancel/, …/revoke/.

A transition that cannot apply — cancelling a draft, publishing something already published — is a 409 with a specific code (not_cancellable, not_publishable, not_unpublishable). It is never a 200 that silently did nothing.

The same holds for timesheets: POST …/timesheets/<id>/approve/ on a row that is already approved is a 409 already_approved, and POST …/timesheets/<id>/confirm/ without a body on hours a person already confirmed is a 409 already_confirmed (on an approved row, confirm/ is a 409 locked). Both mean the row is already where you wanted it — refetch it rather than retrying.

Deleting

DELETE returns a stub, not a 204:

{ "id": "0194d1c0-…", "object": "shift", "deleted": true }

A DELETE never takes a body. Everything a delete needs is in the path or the query string, so a generated client can express all of them. (HTTP leaves a DELETE body’s semantics undefined and OpenAPI 3.0 tells consumers to ignore one, so a body field here would silently disappear from your client and come back as a 400 the schema couldn’t explain.)

Delete is not the soft verb

Where a resource offers both, they are not synonyms, and the wrong choice is not recoverable:

Resource	DELETE …/<id>/	The soft verb
shifts	removes the shift; assignees of a published shift are notified and any live marketplace offer is withdrawn first	POST …/cancel/ — the shift stays, marked cancelled
employees	terminal removal: access revoked, the person leaves every collection and a later GET is a 404. The record is retained internally so timesheets and leave keep their references. The company’s Owner can be neither removed nor deactivated: 409 owner_protected	POST …/deactivate/ (reversible) · POST …/offboard/ (dated termination + settlement)
leave_requests	only while pending or declined — a confirmed or revoked request carries a ledger booking, so it is a 409 not_deletable, as is a withdrawn one	POST …/revoke/ — undoes the effect, keeps the record

Recurring records

Deleting one occurrence of a recurring shifts or availability record needs an explicit scope:

DELETE …/<id>/?scope=this|following|all        # shifts
DELETE …/<id>/?scope=single|following|all      # availability

The two resources treat an omitted scope differently:

• shifts — omit it on a series and you get a 409 delete_scope_required rather than a guess about what you meant.

• availability — the scope defaults to all: omitting it deletes the whole block. single and following additionally require an occurrence=<ISO datetime> anchor naming the occurrence you mean; a missing anchor is a 400.

Rate limits

A 429 carries a Retry-After header. Honour it, and back off exponentially on repeats.