GET /api/appointment-requests — the staff queue (optionally narrowed by status), newest first.

Parameters

Responses

Security: bearer

POST /api/appointment-requests/{id}/approve — book the requested slot on the staff member's calendar. Re-validates availability + conflicts at decision time (the client's listing may be stale); a slot that stopped being free is a typed 409, never a wedged booking. Emits BOTH `appointment.created` (the booking enters the world through the normal creation event) and `appointment_request.approved`.

Parameters

Request body

DecideAppointmentRequest

Responses

Security: bearer

POST /api/appointment-requests/{id}/decline — refuse a pending request. No calendar effect; the note reaches the client.

Parameters

Request body

DecideAppointmentRequest

Responses

Security: bearer

POST /api/appointments — create a booking (409 on overlap).

Request body

CreateAppointmentRequest

Responses

Security: bearer

GET /api/appointments/{id} — fetch one booking in the caller's org.

Parameters

Responses

Security: bearer

PATCH /api/appointments/{id} — edit fields/status (times unchanged; moves use the dedicated endpoint so clients get rescheduled events).

Parameters

Request body

PatchAppointmentRequest

Responses

Security: bearer

POST /api/appointments/{id}/cancel — frees the slot (status flip, never deletion, so history survives).

Parameters

Responses

Security: bearer

POST /api/appointments/{id}/move — reschedule with re-validation (dry-run semantics inline: a conflicting move is rejected atomically and emits a `rescheduled` event only when it lands).

Parameters

Request body

MoveAppointmentRequest

Responses

Security: bearer

GET /api/availability — list one user's weekly templates.

Parameters

Responses

Security: bearer

POST /api/availability — add a weekly template for a user.

Request body

CreateAvailabilityRequest

Responses

Security: bearer

DELETE /api/availability/{id}?user_id= — remove one template.

Parameters

Responses

Security: bearer

GET /api/calendar-exclusions?user_id=&from=&to=

Parameters

Responses

Security: bearer

POST /api/calendar-exclusions — record time-off.

Request body

CreateExclusionRequest

Responses

Security: bearer

DELETE /api/calendar-exclusions/{id}?user_id=

Parameters

Responses

Security: bearer

GET /api/calendar-sync — the caller's (or target user's) connections.

Parameters

Responses

Security: bearer

POST /api/calendar-sync — create a connection. Outbound-capable directions get a feed token generated immediately (returned once).

Request body

CreateConnectionRequest

Responses

Security: bearer

GET /api/calendar-sync/feed/{token} — the OUTBOUND direction: the user's live appointments as a subscribable iCalendar document. Unauthenticated but token-scoped and rate-limited (the scheduling-links pattern); the token resolves org + user, then the read is org-scoped. The token-to-org resolution runs through the `app_resolve_calendar_feed_target` SECURITY DEFINER bridge (migration 0132) — the token is in the URL with no session, so the row is default-deny off the bare pool under RLS.

Parameters

Responses

PATCH /api/calendar-sync/{id} — edit name/direction/feed_url/status.

Parameters

Request body

UpdateConnectionRequest

Responses

Security: bearer

DELETE /api/calendar-sync/{id} — the connection, its mirror rows, and the exclusion rows the sync owns all go away (external busy time frees the calendar).

Parameters

Responses

Security: bearer

GET /api/calendar-sync/{id}/events — the inbound mirror (the conflict/duplicate surface Wave 14 lane 7 renders).

Parameters

Responses

Security: bearer

POST /api/calendar-sync/{id}/rotate-token — invalidates the old outbound feed URL and returns the new raw token once.

Parameters

Responses

Security: bearer

POST /api/calendar-sync/{id}/sync — poll now (manual trigger; the worker lane calls the same seam on its schedule). Network fetch happens OUTSIDE the transaction; the apply + poll-state record + event emission run inside ONE org transaction.

Parameters

Responses

Security: bearer

GET /api/calendar/day — one local day for one user.

Parameters

Responses

Security: bearer

GET /api/calendar/deadlines — the ORG-WIDE ticket-deadline read model (Wave 17 lane 13): /calendar team mode overlays THIS instead of the bounded page-1 tickets fetch. Alive tickets only (category not closed) whose due date falls in the window; hydrated in the row itself.

Parameters

Responses

Security: bearer

GET /api/calendar/team — every org member over an absolute UTC range.

Parameters

Responses

Security: bearer

GET /api/calendar/week — Monday-start local week for one user.

Parameters

Responses

Security: bearer

day_pack_read

Parameters

Responses

Security: bearer

day_pack_picks_list

Parameters

Responses

Security: bearer

day_pack_pick_create

Request body

CreatePickRequest

Responses

Security: bearer

day_pack_pick_delete

Parameters

Responses

Security: bearer

day_pack_rules_list

Responses

Security: bearer

day_pack_rule_create

Request body

CreateRuleRequest

Responses

Security: bearer

day_pack_rule_patch

Parameters

Request body

PatchRuleRequest

Responses

Security: bearer

day_pack_rule_delete

Parameters

Responses

Security: bearer

day_pack_tick_create

Request body

CreateTickRequest

Responses

Security: bearer

day_pack_tick_delete

Parameters

Responses

Security: bearer

POST /api/dispatch/assign — place an unassigned ticket on a technician's board: creates the booking AND flips the ticket assignee in one transaction.

Request body

AssignRequest

Responses

Security: bearer

POST /api/dispatch/bulk-move — atomic batch reschedule.

Every move is re-validated against the TARGET user's live bookings in the union window (each moved booking vacates its old slot, so swaps are legal); the first violating move rejects the WHOLE batch with a typed 409 naming the move index and blocking booking.

Request body

BulkMoveRequest

Responses

Security: bearer

GET /api/dispatch/capacity — multi-day capacity horizon: the day view's capacity math repeated per UTC day over the window, one org-wide availability read + one exclusion read + one appointment read.

Parameters

Responses

Security: bearer

GET /api/dispatch/day — the whole board for one day.

Parameters

Responses

Security: bearer

GET /api/dispatch/journey-start — the resolved start point plus the explicit override, if any.

Parameters

Responses

Security: bearer

PUT /api/dispatch/journey-start — set (or replace) the technician's start point for one day.

Request body

SetJourneyStartRequest

Responses

Security: bearer

GET /api/dispatch/match — for every unassigned open ticket carrying required skills, the active technicians sorted best-first by how many required skills they are missing (0 = fully qualified). Expired certifications never count as held.

Parameters

Responses

Security: bearer

GET /api/dispatch/planning/allocations — who is committed to which phase.

Parameters

Responses

Security: bearer

PUT /api/dispatch/planning/allocations — state (or restate) a technician's commitment to a phase.

Upsert on `(phase_id, user_id)`, so restating a share updates the row. Appending instead would leave two contradictory shares that SUM in the forecast and report a technician as over-committed by construction.

Request body

PhaseAllocationMutation

Responses

Security: bearer

DELETE /api/dispatch/planning/allocations/{id} — release a commitment.

Parameters

Responses

Security: bearer

GET /api/dispatch/planning/forecast — committed project load per technician over a window.

Parameters

Responses

Security: bearer

GET /api/dispatch/queue — the full unassigned queue with dispatcher overrides applied: overridden tickets sort by explicit rank first (ties fall back to the computed order), then everything else in the computed order (priority rank, then effective SLA/due deadline).

Parameters

Responses

Security: bearer

PUT /api/dispatch/queue/{ticket_id} — pin a ticket's queue position. The ticket must exist and still be open+unassigned (an override for a placed ticket is meaningless); idempotent via the instant envelope.

Parameters

Request body

SetQueueRankRequest

Responses

Security: bearer

DELETE /api/dispatch/queue/{ticket_id} — clear a rank override. Idempotent: clearing an unset override still returns 200 with `cleared: false` (the dispatcher's intent is already satisfied).

Parameters

Responses

Security: bearer

GET /api/dispatch/reconciliation — planned-vs-actual rollup over the existing travel drafts and their linked expenses: mileage, time, and reimbursements per technician, in the org's base currency.

Parameters

Responses

Security: bearer

GET /api/dispatch/routing — the day's journey plans, typed warnings, and (measured providers only) suggestion-grade route improvements.

Parameters

Responses

Security: bearer

GET /api/dispatch/skills — the org's skill/certification catalog.

Responses

Security: bearer

PUT /api/dispatch/tickets/{ticket_id}/required-skills — full-replace the job's required-skill set. The ticket must exist and be open + unassigned (requirements on placed work are history, not planning).

Parameters

Request body

ReplaceTicketSkillsRequest

Responses

Security: bearer

GET /api/dispatch/travel-drafts — the caller's drafts (all users for owner/admin via `user_id`), newest first.

Parameters

Responses

Security: bearer

POST /api/dispatch/travel-drafts — a draft mileage row against a ticket. Instant-first (IF1/IF2): idempotency-keyed, version-gated, write-trailed.

Request body

CreateTravelDraftRequest

Responses

Security: bearer

PATCH /api/dispatch/travel-drafts/{id} — edit a draft. Submitted drafts are frozen (the time entry already exists).

Parameters

Request body

PatchTravelDraftRequest

Responses

Security: bearer

DELETE /api/dispatch/travel-drafts/{id} — discard a draft. Submitted drafts are immutable history (delete the TIME ENTRY through invoicing corrections, never the draft's backlink).

Parameters

Responses

Security: bearer

POST /api/dispatch/travel-drafts/{id}/expense — book the draft's mileage as a ticket expense at the org rate (the reimbursement the business owes the technician or bills the client). One expense per draft, idempotent through the standard envelope.

Parameters

Request body

CreateTravelExpenseRequest

Responses

Security: bearer

POST /api/dispatch/travel-drafts/{id}/submit — convert a draft into a real time entry through the EXISTING time-entry path (`insert_time_entry` + the `time_entry.created` event), then freeze the draft with the entry backlink. The entry's notes carry the machine-readable provenance marker (`travel_draft:<id>`); the write trail records the full before/after so "who did this" and undo stay queryable. Idempotent: the same submit replays the SAME entry.

Parameters

Request body

SubmitTravelDraftRequest

Responses

Security: bearer

PUT /api/dispatch/users/{user_id}/skills — full-replace the technician's skill set. The technician must be an active member of this org.

Parameters

Request body

ReplaceUserSkillsRequest

Responses

Security: bearer

GET /api/dispatch/work-next — the caller's curated queue, or another technician's when the caller may see theirs.

Parameters

Responses

Security: bearer

PUT /api/dispatch/work-next — add a ticket to a technician's queue at a position, or move it there if the pair already exists.

Request body

WorkNextMutation

Responses

Security: bearer

DELETE /api/dispatch/work-next?ticket_id=… — drop a ticket from one technician's queue, or from every queue when `user_id` is absent.

Parameters

Responses

Security: bearer

POST /api/dispatch/work-next/reorder — move an entry and return the densified queue.

Returns the WHOLE queue rather than just the moved row because the move shifts everything between the old and new rank. A response with only the moved entry would leave the client guessing the positions of everything it did not drag, which is exactly the state a drag-and-drop list must not be in.

Request body

WorkNextMutation

Responses

Security: bearer

GET /api/meeting-types

Responses

Security: bearer

POST /api/meeting-types

Request body

MeetingTypeBody

Responses

Security: bearer

PATCH /api/meeting-types/{id}

Parameters

Request body

MeetingTypeBody

Responses

Security: bearer

DELETE /api/meeting-types/{id} — HARD delete with audit (Wave 17 lane 13): unlike the Pause toggle (PATCH `is_active`), this removes the template outright. A scheduling link still referencing the row refuses with a typed conflict (the FK RESTRICT surfaces) — pause the links FIRST or re-target them; history rows (bookings) are untouched by the template's deletion.

Parameters

Responses

Security: bearer

GET /api/on-call-blocks?user_id=&from=&to=

Parameters

Responses

Security: bearer

POST /api/on-call-blocks — add a rotation segment (409 when stacking).

Request body

CreateOnCallRequest

Responses

Security: bearer

DELETE /api/on-call-blocks/{id}?user_id=

Parameters

Responses

Security: bearer

GET /api/public/scheduling-links/{token} — unauthenticated, token- scoped, rate-limited. First view stamps the link's lifecycle (`first_viewed_at` + count) and emits `scheduling_link.viewed`.

Parameters

Responses

POST /api/public/scheduling-links/{token}/book — unauthenticated but token-scoped and rate-limited. Race-safe exactly like portal appointment-request approval: the availability + conflict gate and the single-winner link flip run INSIDE the booking transaction, and the appointments EXCLUDE constraint is the concurrency backstop.

Parameters

Request body

BookRequest

Responses

GET /api/scheduling-groups — the org's free-form groups (availability pools; deliberately NOT the org chart).

Responses

Security: bearer

POST /api/scheduling-groups — create a pool.

Request body

CreateGroupRequest

Responses

Security: bearer

GET /api/scheduling-groups/{id}

Parameters

Responses

Security: bearer

PATCH /api/scheduling-groups/{id}

Parameters

Request body

UpdateGroupRequest

Responses

Security: bearer

DELETE /api/scheduling-groups/{id} — removes the pool (memberships go with it; meeting types pointed at it retire with their FK CASCADE, mirroring Calendly's delete semantics).

Parameters

Responses

Security: bearer

POST /api/scheduling-groups/{id}/members — add a calendar to the pool.

Parameters

Request body

AddMemberRequest

Responses

Security: bearer

DELETE /api/scheduling-groups/{id}/members/{user_id}

Parameters

Responses

Security: bearer

GET /api/scheduling-links — newest-first (optionally per ticket) so the tech sees the created / viewed / scheduled / expired lifecycle.

Parameters

Responses

Security: bearer

POST /api/scheduling-links — mint a shareable link (token returned once). A replay (same key + same body) replays the SAME token.

Request body

CreateSchedulingLinkRequest

Responses

Security: bearer

GET /api/scheduling-links/{id}/bookings — the link → booking trail.

Parameters

Responses

Security: bearer

POST /api/scheduling-links/{id}/revoke — the link can never book again; an already-used link keeps its `used` state so the booking trail never changes meaning.

Parameters

Responses

Security: bearer

POST /api/scheduling/conflict-check — dry-run overlap probe that writes nothing: returns every blocking booking for the candidate slot.

Request body

ConflictCheckRequest

Responses

Security: bearer