Scheduling API contracts
Facilities, services, resource-assignment and scheduling-conflict API surfaces, assignment creation locking and refusals, list filters, connector columns and the scheduling plugin hook catalogue.
Overview
This page is the integration reference for scheduling. For the Labour page, Resource Timeline and how assignments attach to rentals and projects, see Scheduling.
API surfaces
| Surface | Path / name | Permission / ability |
|---|
| Facilities API | /api/v1/facilities | facilities:* — creating a facility in, or moving one to, a warehouse you cannot access returns 404 |
| Services API | /api/v1/services | services:* |
| Resource assignments API | /api/v1/resource-assignments | resource-assignments:* |
| Unscheduled demand | GET /api/v1/resource-assignments/unscheduled | resource-assignments:read — counts crew (account) assignments only, so booking a vehicle never satisfies a service line's staffing demand; a warehouse_id you cannot access returns 404 |
| Conflicts API | /api/v1/scheduling-conflicts | scheduling-conflicts:* |
| Assignment charge lines | POST /api/v1/resource-assignments/{id}/charge-line, …/charge-line/sync-assignment-window, …/charge-line/sync-line-window | resource-assignments:write + resource-assignments.edit and rentals.edit; MCP add-assignment-charge-line, sync-assignment-window-to-charge-line, sync-charge-line-window-to-assignment |
Resource assignment completion
POST /api/v1/resource-assignments/{id}/complete completes an in-progress assignment and finalises its linked service or charge line (rental_line_id) in the same transaction. This applies to every resource type, including delivery, collection, crew, dispatch groups and facilities. Assignments without a linked line complete normally; completion does not create a charge line or select unrelated service lines by date_source.
The final line window uses the actual started_at and the completed_at recorded by completion. If the actual start is absent, it uses the assignment's planned starts_at, then the rental start. The resulting window must be complete and end after its start. Completion sets is_final and ready_to_invoice on the line, recalculates its price and rental totals through the existing rental calculator, and records these facts in the rental event stream for replay.
Final lines refuse both charge-line window sync directions and direct window edits. Later rental hire, delivery and collection window changes (including removing a transport leg) leave final windows fixed. If another assignment shares the line, its completion records its own actual window; ordinary window syncs remain locked. Invoiced or price-frozen lines cannot be finalised, and any finalisation failure rolls back the assignment completion.
The endpoint keeps resource-assignments.edit and resource-assignments:write authorization; it does not additionally require rentals.edit. Externally sourced assignments still require their matching source, including on retries. Repeating an already completed assignment returns its existing result without changing timestamps, appending events or delivering duplicate webhooks. Completed assignments remain terminal; there is no reopen operation.
Completion records the internal rental.line_dates_changed audit event and emits the public rental.updated webhook with its existing rental DTO envelope, alongside resource_assignment.completed. The rental webhook is captured after totals have been recalculated, before the transaction commits. Replay restores final flags, windows and totals without redelivering webhooks. The response remains the resource-assignment data envelope; read the rental line for is_final and ready_to_invoice.
Completion example
After the assignment has started, complete it with:
POST /api/v1/resource-assignments/18/complete
Content-Type: application/json
{}
For an external assignment, include its matching source instead of an empty object. The response is the assignment in data; the following excerpt shows the fields to correlate:
{"data":{"id":18,"status":"completed","rental_line_id":12}}
Read GET /api/v1/rentals/42/lines to inspect the linked line. An abbreviated list entry after completion:
{"data":[{"id":12,"is_final":true,"ready_to_invoice":true}]}
Line finalisation also advances the rental's updated_at, so it appears in the rental incremental-sync feed.
Assignment creation concurrency
Rental assignment creation rechecks the current rental window, selected rental line and resource eligibility under the rental owner lock before persistence. If the window no longer fits or the resource is inactive after a wait, creation keeps its existing 422 validation response. A removed selected line returns the existing 422 validation response with errors.code = ["assignment_rental_line_missing"], before any assignment, cache invalidation or queued job is written. These refusals leave stored rows unchanged. Read the current rental and resource before submitting a fresh assignment.
Facility-backed assignment creation locks the selected facility before rechecking eligibility. It waits for concurrent facility edits; a committed deactivation retains the existing 422 validation response, with no assignment, stored-row, cache or queued-job changes. An active renamed facility remains assignable and its source row is unchanged by creation.
Vehicle-backed assignment creation also locks its selected vehicle before rechecking eligibility. A committed deactivation retains the existing 422 validation response with no assignment, stored-row, cache or queued-job changes. Active renamed vehicles remain assignable; assignment creation leaves their source rows unchanged.
Account-backed assignment creation locks the selected source account as well as any rental customer account before rechecking eligibility. A committed deactivation retains the existing 422 validation response with no assignment, stored-row, cache or queued-job changes. Active renamed source accounts remain assignable; assignment creation leaves their source rows unchanged.
If the selected facility or vehicle is deleted while creation waits, the existing 422 response remains under resource_id: The selected resource does not exist. No assignment, stored-row, cache or queued-job changes are made by the refused creation. Read the current resource before trying another assignment.
An assigned source account archived during creation's wait keeps the same missing-resource 422 under resource_id. If only the rental customer account is archived and the assigned source account still exists, creation retains its existing account refusal. Both refusals leave assignment, stored rows, cache and queued jobs unchanged.
Project assignment creation locks the selected project before rechecking attachment access and calculating its existing cost quote. A rate committed while creation waits supplies the new quote; an expired company-base rate keeps the existing 422 validation response with errors.code = ["assignment_project_base_rate_missing"], before assignment or cost persistence. This refusal leaves stored rows, cache and queued jobs unchanged. Read the current project and resource before submitting a fresh assignment.
Listing assignments over the API
GET /api/v1/resource-assignments and the MCP tool list-resource-assignments read assignments the way the timeline does:
- Effective window. A vehicle booking with no own start or end inherits the rental's booking window, so
starts_at/ends_atin the list are the effective window, andfilter[starts_at][operator],filter[ends_at][operator]andsort=starts_atuse it too. The stored row keeps its null dates;GET /api/v1/resource-assignments/{id}still returns the stored values. warehouse_ids[]keeps rows whose rental, a linked rentals of their project, their facility, or their vehicle belongs to any listed warehouse — the timeline's warehouse union. The list is limited to the warehouses you can access; asking only for warehouses you cannot access returns no rows. Without it, the normal warehouse scoping applies.from/to(ISO 8601) return rows whose effective window overlaps the range. The comparison uses UTC instants, including inherited rental dates, as on the timeline.
Connector columns
Assignments carry source (core or a plugin/connector id) and optional
external_reference (unique per source) for idempotent sync writes.
Plugin hooks (mandatory catalogue)
| Hook | Type | When |
|---|---|---|
assignment.creating |
Validator | Under the selected owner lock, before persist — veto creation |
assignment.created |
Event | After create |
assignment.status_changed |
Event | confirm / start / complete / cancel |
conflict.detected |
Event | Conflict stored on write |
demand.unmet |
Event | Cancel leaves service shortfall |
assignment.query |
Filter | List / timeline read queries |
Creation validators run once under the selected rental or project owner lock, after any wait and before assignment persistence. Denials retain 422 with errors.code = ["plugin_validator_denied"]; exceptions retain errors.code = ["plugin_validator_exception"]. These refusals leave stored rows, assignment invalidation cache and queued jobs unchanged. A thrown validator still advances its existing operational failure counter; a later successful hook call clears that counter.
Webhook event names use the resource_assignment.* and scheduling_conflict.*
prefixes — see Webhooks. Hook registration details:
Plugin hooks.
MCP confirmation
Generic MCP execute-endpoint refuses assignment confirmation, start, completion and deletion with mcp_confirmation_required. Use a dedicated tool with explicit confirmation when available, or the authenticated API.
Service custom fields
Service create and update accept custom_fields keyed by field name. Service reads include custom-field values by default. Invalid values return 422. Deleting a service extension that is still required by its catalogue item also returns 422 without deleting it.