Integration API reference

The versioned machine API for facilities, appointments, completed runs, and expected work.

Endpoints#

Paths below are relative to your customer’s https://rome.example/api base URL. Authenticate with a service-account Bearer key.

↓ Download OpenAPI JSON v1 · source snapshot

GET/v1/expected-work/orders

List expected orders

Parameter	Location	Required
`location_id`	query	Yes
`date`	query	No
`reference`	query	No

orders:read

POST/v1/expected-work/orders

Create or replay expected orders

orders:write

POST/v1/expected-work/orders/preview

Validate an import without writing

orders:write

PATCH/v1/expected-work/orders/{id}

Enrich references or update an unallocated quantity

Parameter	Location	Required
`id`	path	Yes

orders:write

GET/v1/expected-work/shipments

List assembled shipments

Parameter	Location	Required
`location_id`	query	Yes
`reference`	query	No

orders:read

POST/v1/expected-work/shipments

Allocate orders to a shipment and issue its private invitation

orders:write, appointments:write

PATCH/v1/expected-work/shipments/{id}/references

Add shipment reference aliases

Parameter	Location	Required
`id`	path	Yes

orders:write

POST/v1/expected-work/shipments/{id}/release

Release an unbooked shipment's order allocations

Parameter	Location	Required
`id`	path	Yes

orders:write

GET/v1/facilities

List the docks this key can see

See the quickstart and OpenAPI contract for access requirements.

GET/v1/appointments

Scheduled arrivals at a dock

Parameter	Location	Required
`locationId`	query	Yes
`from`	query	No
`to`	query	No

appointments:read

POST/v1/appointments

Book a slot

Required JSON fields: facilityId, startAt, carrier, carrierKind, direction, serviceMethod, reference.

appointments:write

GET/v1/runs

Completed visits, with the minutes

Parameter	Location	Required
`facilityId`	query	Yes
`from`	query	No
`to`	query	No

history:read

GET/v1/slots

When a dock can take a truck

Parameter	Location	Required
`facilityId`	query	Yes
`date`	query	No

appointments:read

DELETE/v1/appointments/{id}

Cancel a booked slot

Parameter	Location	Required
`id`	path	Yes
`reason`	query	Yes

appointments:write

Create an appointment#

Send POST /api/v1/appointments with appointments:write and Content-Type: application/json. Replace the sample timestamp with an actual startAt returned by slots.

JSON

{
  "facilityId": "dock-id",
  "startAt": 1790000000000,
  "carrier": "Example Carrier",
  "carrierKind": "asset",
  "direction": "pickup",
  "serviceMethod": "live",
  "reference": "PILOT-001"
}

carrierKind: asset, broker, or unknown. direction: pickup or delivery. serviceMethod: live, drop, or hook. Service method describes how equipment is handled at the facility, not whether a TMS record is a real shipment or a quote.

Success returns 201 with the appointment ID, facility ID, start time, status, and reference. Cancellation requires a reason of at least 10 characters and retains the load and its orders.

Read windows and reporting#

Read operation	Current behavior
Appointments	Requires locationId (not facilityId). Inclusive from/to timestamps. Up to the first 1,000 records, without a continuation token.
Completed runs	Requires facilityId. Includes from, excludes to, based on dock-cleared time. More than 20,000 rows returns an error.
Read window	Appointments and runs default to the last 90 days; maximum span is 366 days.

Narrow time ranges and deduplicate appointment IDs. A 1,000-row response may be incomplete; splitting windows cannot guarantee completeness when one timestamp exceeds the cap.

Errors and retries#

Status	Handling
400	Correct missing or invalid inputs, dates, or read ranges.
401	Check the key and Authorization header.
403	Check required scopes.
404	The resource may be absent or outside the key’s visibility.
409	Refresh and reconcile a state or booking conflict.
429	Back off and honor Retry-After when present.
5xx	Retry reads with bounded backoff. Reconcile writes before replaying.

Errors normally include error; machine-readable code is not present on every endpoint. Appointment creation has no advertised idempotency-key contract. A timeout can happen after a successful commit, so do not blindly repeat a booking.