Tours
A tour schedules work for a group of human participants. It has a server-assigned UUID id
for API URLs and relationships, and an immutable, tenant-unique positive natural_id for human
references. The application displays natural ID 2 as Tour-2. Numbers are never reused;
gaps are allowed.
The tour's optional editable text is description. When set, it contains 1–255 nonblank characters and appears
below the human reference in the application. Tour request bodies, responses, search, sorting
and webhook resource payloads use description.
Detail reads and full create, PATCH, publish, Start, use-Vehicle and finish responses include
requirement_coverage and start_blockers. Ad-hoc Start and the corresponding MCP tools use the
same response contract. Write responses describe the resulting state within that transaction;
you do not need a second GET or additional Tour-read permission after creating a Tour.
Coverage combines the skills supplied by participants and Vehicles, including Vehicle-required
skills. References you cannot read are redacted. start_blockers describes the current Vehicle
obstacles to first Start; an empty list does not waive other permissions or lifecycle checks.
These fields are advisory and omitted from list summaries. Every command rechecks current state.
vehicle_source_unconfirmed means a planned Vehicle has an app Device association whose fixed/portable
mode still needs confirmation and no configured tracker, fixed Device or plugin operational GPS source
has priority. When Start or use-Vehicle needs to nominate the current phone, it returns
409 vehicle-device-associations/mode-unconfirmed without changing the Tour, login or associations.
The conflict includes data.details_restricted; callers with both vehicles:read and devices:read
also receive data.association_ids to identify the associations to review. Confirm the mode through
association management, then refresh the review and submit again. Starting remotely without a Device
does not nominate a phone and does not require this source-configuration decision. Participant Device
consistency is still checked, including unknown modes that prevent safely moving a participant Device.
Create and edit
Create a draft with POST /api/v2/tours. Omitting tour_template_id, or sending it as
null, applies your workspace's Default Tour template. An explicit template ID applies
only that template; it does not merge with Default.
GET /api/v2/tours/settings
The response contains default_tour_template_id. Read that template through
GET /api/v2/tour-templates/{tour_template_id} to preview its defaults and work. Tour creators
and ad-hoc starters can read this one protected template without permission to list named
templates. Default is editable with the normal template-update permission and cannot be deleted.
Responses mark it with the read-only is_default flag; its identity is independent of its name.
Example draft:
{
"description": "Morning maintenance visits",
"participant_user_ids": ["11111111-1111-4111-8111-111111111111"],
"planned_start_at": "2026-09-14T07:00:00Z",
"planned_end_at": "2026-09-14T15:00:00Z"
}
Participants must be active human users in the current tenant. A draft may omit participants
and both planned times. Start and end are independently optional; when both are set,
the planned end must be after the planned start. Creation returns 201 with the complete tour and an absolute Location
header. Read it with GET /api/v2/tours/{tour_id}. Include initial vehicles only with Tour-read,
tours:update and vehicles:read authority; create permission alone does not grant assignment.
Use PATCH /api/v2/tours/{tour_id} to edit a tour:
{ "description": "Morning and afternoon maintenance visits", "lock_version": 0 }
Omission preserves fields. Description, planned_start_at, and planned_end_at can be
cleared with null. Both planned times remain optional after publishing. Participants and
planned start become fixed after the tour starts. Planned end can still be edited or cleared
while the tour is in progress. Finished tours cannot be edited. Validation checks the resulting range,
including a stored time when only the other time is supplied.
Both application/merge-patch+json and application/json are accepted for Tour, Stop, assignment
and template PATCH bodies. See write semantics.
required_skill_ids describes the skills needed for a Tour. It is an array of existing Skill
UUIDs, supported by create, update, read, list and webhook payloads. Omit it on update to preserve
the set; send [] to clear it. Skills remain editable until the Tour finishes. They do not
automatically select participants or enforce worker eligibility.
Reusable tour templates
Templates store configuration separately from operational Tours and Tasks. Use
POST /api/v2/tour-templates to save a named template:
{
"name": "Morning inspection",
"tour_defaults": {
"description": "Check the depot before deliveries",
"timezone": "Europe/Vienna",
"planned_start": { "day_offset": 0, "time": "08:00:00" },
"planned_end": { "day_offset": 0, "time": "10:00:00" },
"required_skill_ids": []
},
"tasks": [
{
"id": "07b8775e-49d7-4980-adfe-1423a87765ab",
"type": "visit",
"title": "Inspect depot",
"location": { "lat": 48.2082, "lon": 16.3738, "address_label": "Depot" },
"linked_records": []
}
],
"stops": [
{
"id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
"origin": "task_visit",
"location": { "lat": 48.2082, "lon": 16.3738, "address_label": "Depot" }
}
],
"items": [
{
"type": "stop",
"stop_id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
"task_ids": ["07b8775e-49d7-4980-adfe-1423a87765ab"]
}
]
}
Template Tasks are simple or visit; visits require a location. Optional assignees and record
links must refer to accessible resources in the same workspace. They are validated again when
creating a Tour. Template items have stable UUIDs, but no live task number, completion or execution
state. A Task appears exactly once in items, either as {"type":"task","task_id":"…"}
or inside a Stop. An empty standalone Stop is valid; an empty task_visit Stop is not. A template
supports at most 500 Stops and 10,000 Tasks and Stops combined.
Simple and Visit template items accept an optional definition_id matching their type and a
data object keyed by custom attribute slug. Omitting the definition selects the corresponding
system definition. Workflow question definitions cannot appear in templates. The same custom-value
validation, choice resolution and relationship permissions apply as for Task creation. For example:
{
"id": "12d09711-2196-4b3c-a3aa-fb46064a3939",
"type": "simple",
"title": "Inspect vehicle",
"definition_id": "46700000-0000-4000-8000-000000000001",
"data": {"notes": "Check tyres and lights"}
}
A template save validates all inputs and captures applicable defaults without creating operational
Tasks. Replacing tasks replaces each item's complete inputs; omitted data is empty. Metadata-only
PATCH preserves existing inputs. Template items may explicitly select a different definition;
already-created Tasks retain their immutable definitions and values. New optional fields may apply
their defaults when future Tasks are created; existing Tasks are never backfilled.
A saved item counts as definition usage, even if no Task exists. Required additions, structural changes and definition deletion are blocked while used. Required relationship targets cannot be deleted; optional target deletion clears only that reference and advances the template revision.
Full workspace copies preserve and remap template configuration. Configuration-only workspace
copies preserve unaffected inputs but remove references to excluded operational records. If required
fields lose references, needs_configuration is true on the template and list summary, and affected
items expose configuration_required_fields as attribute slugs. Tour creation returns 409 tours/template-needs-configuration, with data.tour_template_id, until a
valid template save repairs those fields. Ordinary template saves never accept invalid inputs.
GET /api/v2/tour-templates supports search, page, size and sort. Its summaries include
defaults, required skills and counts. Read the complete aggregate through
GET /api/v2/tour-templates/{tour_template_id}. PATCH the same URL to edit it: nested defaults
merge, while supplied tasks, stops and items arrays replace their respective arrays.
Send the loaded lock_version to reject a stale save. A rejected aggregate leaves all saved
content unchanged. DELETE returns 204 for named templates; deleting Default returns 409.
Deletion does not delete generated Tours or Tasks.
Create a Tour using the ordinary creation endpoint:
{
"tour_template_id": "a46c234e-f8ba-42ad-955e-f103d514df76",
"tour_date": "2026-09-16",
"participant_user_ids": ["11111111-1111-4111-8111-111111111111"]
}
tour_date is required for a named template. With implicit Default it is required only when
inheriting relative planned times; an empty Default permits {}. It is a calendar date in the
template's timezone. Planned times are optional and relative to that date: day offset 0 is the
same day, 1 the next day, and -1 the previous day; offsets must be integers within ±365.
Nonexistent or ambiguous local times during a daylight-saving transition return 422.
Omitted description, planned times and required skills inherit the saved defaults. Explicit
absolute timestamps override relative times; null clears a description or planned bound;
required_skill_ids: [] clears skills. Only non-overridden relative bounds need resolving. The
final start/end range must still be valid. Participants default to an empty set.
Creation atomically copies one consistent, latest saved template into a draft Tour with fresh Task,
Stop and assignment IDs and new human numbers. A failure rolls back the complete creation and its
events. Tour responses include source_tour_template_id, source_tour_template_name,
source_tour_template_revision and source_tour_template_date. These record the effective
template and materialization date and survive later template edits or deletion. Older Tours
without this provenance omit these fields. Reusing the template creates independent
resources, including when the template and date are identical. This HTTP operation has no retry
key or replay guarantee; see retrying creates.
Template CRUD requires tour-templates:read, tour-templates:create, tour-templates:update or
tour-templates:delete, respectively. Draft creation requires tours:create; selecting a named
template additionally requires tour-templates:read. tasks:write is required only when the
effective template contains Tasks. Template lifecycle webhooks use tour_template.created,
tour_template.updated and tour_template.deleted; discover their exact payloads in the
webhook catalog.
Ad-hoc creation uses POST /api/v2/tours/start-ad-hoc with the same template and override fields.
It derives an omitted tour_date from the command time in the effective template's timezone,
adds the current human participant, publishes and starts the Tour atomically. It requires
tours:start-ad-hoc; named-template and Task permissions follow the same rules above. Vehicle
coordination runs in the same transaction. Starting an existing Tour does not apply a template again.
Find tours
GET /api/v2/tours returns the standard items and page envelope. Use search to match
description text or a number, natural_id for an exact human number, and participant_user_id
for a user's tours. The default order is natural_id:desc (newest number first). For example:
GET /api/v2/tours?natural_id=2
GET /api/v2/tours?search=maintenance&sort=description:asc
GET /api/v2/tours?participant_user_id=11111111-1111-4111-8111-111111111111&publication_status=published&execution_status=in_progress
Tour responses, including list items and webhook resource payloads, contain task_count and
stop_count. These are nonnegative counts calculated by the server. Task count includes every
assigned task, including completed tasks, tasks that share a stop, and tasks without a stop.
Combining stops reduces the stop count while preserving the task count.
Lifecycle
Publication is draft or published; execution is not_started, in_progress or finished.
The /publish, /start and /finish actions accept POST with an optional lock_version
and return the updated tour. Publishing requires at least one participant; planned times are optional.
published_at records publication. started_at records the actual start, and finished_at
remains absent while the tour runs. Finishing records finished_at. Actual timestamps are
independent of the optional planned times.
A participant can have only one active tour. Finish requires all assigned tasks and standalone
stops to be complete.
POST /api/v2/tours/start-ad-hoc starts a published tour immediately with the current human
user as its participant. An empty body {} applies Default, including its saved description, requirements and work;
callers may override its fields with the same rules as draft creation. Publication and actual start are recorded immediately. A participant already on an active tour produces 409.
Assign Vehicles
A Tour's vehicles is the complete current assignment set, with at most 100 distinct Vehicles.
Each response entry contains an assignment id, vehicle_id, assigned_at, optional descriptive
role, and actual-use timestamps when applicable. A single Vehicle needs no role. The role is
free text of 1–80 nonblank characters; it does not grant permissions or select a location source.
List, detail and full write responses also include permission-checked current Vehicle details:
vehicle_definition_id, vehicle_natural_id, vehicle_display_name and vehicle_eligibility.
These are current labels, even for a finished Tour, rather than historical snapshots.
vehicle_details_restricted is always present. When it is true, those four fields are omitted;
the assignment ID, Vehicle ID, role and use timestamps remain. A restricted assignment is never
silently removed from the list.
vehicle_eligibility describes the definition rule for this assignment:
| Value | Meaning |
|---|---|
eligible | The Vehicle definition is allowed for Tours. |
excluded | The definition is excluded; new assignments and first Start are blocked. |
retained_active_use | The definition was excluded while this assignment was already in use. This active episode may continue; after removal or finish, that exception ends. |
This is an advisory snapshot, not an availability or location-reporting decision. Commands still recheck active use, required Vehicles and permissions. It does not expose another Tour's details. For example, one readable current assignment can look like this:
{
"id": "00000000-0000-4000-8000-000000000061",
"vehicle_id": "00000000-0000-4000-8000-000000000027",
"assigned_at": "2026-10-09T06:00:00Z",
"vehicle_details_restricted": false,
"vehicle_definition_id": "00000000-0000-4000-8000-000000000017",
"vehicle_natural_id": "VAN-1",
"vehicle_display_name": "Service van",
"vehicle_eligibility": "eligible"
}
Use Tour create or PATCH with the whole desired set. Omit vehicles on PATCH to preserve it,
send [] to remove all assignments, and never send null. Omitted/null roles clear that entry's
role in a submitted set. Retained Vehicles keep their assignment identity.
PATCH /api/v2/tours/00000000-0000-4000-8000-000000000041
Content-Type: application/merge-patch+json
{
"lock_version": 7,
"vehicles": [
{
"vehicle_id": "00000000-0000-4000-8000-000000000027",
"role": "Equipment"
}
]
}
Planning does not associate phones, select GPS or reserve calendar availability. A Vehicle can be planned on several Tours, but only one may actively use it. On an active Tour, replacement/removal closes the old actual-use interval and reconciles participant Devices in the same transaction. An active Tour may remove its last Vehicle and continue with a warning, even when it required one at first Start. Finish ends actual use and retains Vehicle–Device associations. Finished Tours cannot be edited; removed assignments are retained internally.
Acknowledge active use while planning
When adding a busy Vehicle to an unstarted planned Tour, the server returns
409 tours/vehicle-confirmation-required. Its data.active_use_conflicts contains the submitted
vehicle_id for each conflict. After the user consciously agrees to
plan it, repeat the complete set with acknowledge_active_use: true on that selection:
{
"lock_version": 7,
"vehicles": [
{
"vehicle_id": "00000000-0000-4000-8000-000000000027",
"acknowledge_active_use": true
}
]
}
It acknowledges the observed active use for future planning, not permission to take over. Start, ad-hoc Start and active-Tour use always reject conflicting actual use, even after planning was acknowledged. No availability calendar or booking is created.
Eligibility and skills
GET /api/v2/tours/settings returns default_tour_template_id, vehicle_skill_id,
excluded_vehicle_definition_ids and lock_version. All Vehicle definitions are eligible by
default. A settings manager can replace the exclusion set:
PATCH /api/v2/tours/settings
Content-Type: application/merge-patch+json
{
"excluded_vehicle_definition_ids": ["00000000-0000-4000-8000-000000000080"],
"lock_version": 2
}
This requires tenant:settings:update. Omission preserves exclusions; [] permits all definitions;
null is invalid. Newly added Vehicles and first Start recheck exclusions. Existing active assignments
remain usable until removed; an excluded Vehicle cannot then be added again. The two identity fields
are read-only. Deleting an empty excluded definition removes its settings entry and advances the
settings version. Listing settings does not grant template or Vehicle-management access.
Every Vehicle supplies the protected system Vehicle skill. Add vehicle_skill_id to a Tour's or
Default/named template's required_skill_ids to require an eligible Vehicle at first Start.
Vehicle-defined requirements join Tour requirements; participants and eligible Vehicles can supply
any matching ordinary skill. Other uncovered skills warn without blocking execution. Detail/action
responses return requirement_coverage.skills with covered, requirement origins and providers;
restricted references are omitted and marked with has_restricted_references. Coverage also has
has_restricted_requirements. Recheck after resource changes; these snapshots are advisory.
Start or change the Vehicle with a phone
First register the human login with POST /api/v2/devices/current/user-association, using the human
bearer token and X-Device-Authorization: Bearer <device-token>. Read the observed context with
GET /api/v2/devices/current/vehicle-association. This identifies the request's Device, even if
the person is signed in elsewhere. See Device proof.
Use one top-level device_context on Start, ad-hoc Start or active Vehicle use:
| Intent | Request shape |
|---|---|
| Dispatcher starts the already planned Vehicles | No secondary Device header and no device_context; optional lock_version. |
| Phone starts a Tour with one planned Vehicle | Secondary header plus device_context; no vehicle_use is needed. |
| Select/add/replace a Vehicle while starting | Secondary header and device_context, plus vehicle_use describing the Vehicle change. |
| API selects a Vehicle without nominating a phone | vehicle_use on Start/ad-hoc Start, without Device header/context. |
| Change/use a Vehicle after Start | POST …/use-vehicle with vehicle_use (vehicle_id, optional replace_vehicle_id or add) and optional proven device_context. |
For example, Start with a selected Vehicle and a phone that has no association:
POST /api/v2/tours/00000000-0000-4000-8000-000000000041/start
Authorization: Bearer <human-access-token>
X-Device-Authorization: Bearer <device-access-token>
Content-Type: application/json
{
"lock_version": 8,
"vehicle_use": { "vehicle_id": "00000000-0000-4000-8000-000000000027" },
"device_context": { "expected_vehicle_association_id": null }
}
If expected_vehicle_association_id is supplied inside device_context, explicit null means no
association was observed; otherwise send its exact UUID. If omitted, the server acts on the current
Device association without an optimistic fence. The header without context returns a field-level 422;
context without valid proof returns 403. A changed observed episode returns 409 devices/vehicle-association-changed.
A valid proof without this registered human session returns 409 devices/current-user-association-required.
Both failure paths leave the Tour and associations unchanged.
With several assigned Vehicles, a portable phone needs an explicit Vehicle choice; the server does
not pick the first entry. A Vehicle already in the set keeps its assignment. To add a different one
to a nonempty set, send add: true; to replace one, send replace_vehicle_id. These are mutually
exclusive, and other assigned Vehicles remain. A new assignment has no role.
The backend atomically reconciles all participants' current Device contexts. It ends portable associations outside the resulting Vehicle set. For a nonempty set, it revokes the participant's human session on an incompatible fixed tablet while retaining the fixed association and Device credentials. With no Vehicles, portable associations end and fixed-tablet logins remain. Other participant phones can read/work on the Tour without any Vehicle association. Clients must not implement this as a chain of disconnect requests.
A configured tracker takes priority, then a fixed app Device. Stale configured hardware retains
priority. Otherwise an authorized starting portable phone is associated and selected as source;
this requires assignment authority, vehicles:read, devices:vehicles:assign-self and
vehicles:device-location:use-self. Missing authority rejects that requested phone flow atomically.
Starting without Device context does not nominate a phone and can succeed without GPS. Reporting
permission remains separate from source selection. See Vehicle location.
To replace the Vehicle while the Tour is active, refresh its version and the Device context, then:
POST /api/v2/tours/00000000-0000-4000-8000-000000000041/use-vehicle
Authorization: Bearer <human-access-token>
X-Device-Authorization: Bearer <device-access-token>
Content-Type: application/json
{
"lock_version": 9,
"vehicle_use": {
"vehicle_id": "00000000-0000-4000-8000-000000000028",
"replace_vehicle_id": "00000000-0000-4000-8000-000000000027"
},
"device_context": {
"expected_vehicle_association_id": "00000000-0000-4000-8000-000000000108"
}
}
Unlike Start, this action requires assignment authority without Tour-execution authority. All full
write responses return the resulting Tour, coverage and Start blockers. A repeated Start only
succeeds when its intent already holds; changed Vehicle/source intent returns
409 tours/vehicle-use-conflict and must use the active-Tour action. Supplied versions are checked
first. Ad-hoc Start takes the same vehicle_use and top-level device_context alongside creation
fields; it returns 201 and Location. Do not blindly retry an uncertain ad-hoc creation: it has no
HTTP replay key. Recover through authorized current/active Tour and Device reads before a new attempt.
Read complete Tour work
Detail and full action responses expose Vehicles, requirement coverage and Start blockers. For a complete ordered work view, request one expansion:
GET /api/v2/tours/{tour_id}?include=tasks
include=stopsreturnsstops[]with destinations, positions, versions and standalone completion state. It omits Task arrays and Task identifiers.include=tasksreturns all Stops, orderedstops[].tasks[], roottasks[], andtask_assignments[]with the corresponding membership IDs, timestamps and versions. Empty standalone Stops remain present. Requested arrays are present even when empty.- Without
include, these fields are absent.include=stops&include=tasksequalsinclude=tasks; unknown, empty or comma-separated include values return422at#/include.
Task entries use the ordinary Task representation, including linked-record access flags
and workflow questions, plus position. Root Task and Stop positions share one sequence; merge
those two arrays by position. Nested Task positions belong to their containing Stop. A Task's
lock_version differs from the membership version in task_assignments[] and the parent Tour
version; use the version belonging to the resource you update.
The response uses one consistent database snapshot. Limits are 500 Stops and 10,000 Tasks plus Stops
in total. Imported work over these limits returns 409 tours/capacity-exceeded; inconsistent
membership returns 409 resource-conflict. Successful responses never truncate work. Base reads
and separately authorized collection endpoints remain available to correct membership.
Normal permissions apply to every exposed resource. Task expansion requires tasks:read, as does a
Stop-only expansion containing a Task-derived destination. A standalone Stop can be read without
access to Tasks whose data is not exposed. Any denied expansion fails entirely with 403 access-denied and canonical denial metadata; there is no partial Tour body or protected content in
the error. The base Tour read is authorized first, preserving missing/concealed Tour behavior.
Restricted business-record links inside an authorized Task retain the same compact placeholders as
ordinary Task detail. No linked business-record contents are expanded.
The web/mobile work view and planning board use this complete read. Existing item-order GET/PUT and
Stop/Task-assignment endpoints remain available for independently authorized reads and writes.
The tours_get MCP tool accepts the same optional include list and applies the same rules.
Vehicle-assignment history
GET /api/v2/tours/{tour_id}/vehicle-assignments?lifecycle=all&page=0&size=20
This read-only collection returns {items, page}. Omit lifecycle for current membership:
assignments whose removed_at is absent. Choose all to include removed episodes. A finished
Tour can still have current assignments; use_started_at and use_ended_at describe actual use
separately. Role edits keep an assignment's id. Removing and later reassigning the same Vehicle
creates a new episode.
Pages use fixed assigned_at descending, then id ascending order. page starts at zero; size
defaults to 20 and accepts 1–100. There is no custom sort or independent assignment write endpoint.
Change the Tour's Vehicle selections through the existing Tour commands.
Each item carries its id, tour_id, vehicle_id, assignment/removal and actual-use timestamps,
known assigning/removing user IDs, creation/update timestamps and independent lock_version.
Normal Tour visibility applies before reading any episodes. Without Vehicle-read permission,
vehicle_details_restricted is true; Vehicle definition, natural ID and display name are omitted.
Otherwise those labels describe the current Vehicle, not its name at assignment time.
The tours_vehicle_assignments_list MCP tool accepts the same lifecycle and page options.
Subscribe to tour_vehicle_assignment.created and tour_vehicle_assignment.updated for assignment
changes. Each event identifies the episode, Tour and Vehicle. Updates cover role edits, actual-use
start/end and removal, with changed old values in data.previous_attributes. Removal retains the
episode and is an update. tour_vehicle_assignment.deleted occurs only when deleting a never-used
Tour destroys its episodes. These events carry assignment facts, without current Vehicle names.
Parent tour.updated events retain the previous Vehicle selections in data.previous_attributes.vehicles.
Failed commands commit neither assignment changes nor events. Repeating an already-achieved command
does not manufacture another assignment change. The Tour collection SSE notification requests a
refresh once per transaction, including when a Tour template also creates Tasks; it is not history
delivery. The association and source events
remain separate contracts.
Tasks and stops
Tasks remain independent resources. Assign one through
POST /api/v2/tour-task-assignments with task_id and tour_id. A visit task creates a stop;
other task types join the tour without a stop. Assignments do not change task content or its
individual assignee.
Dispatchers can create a standalone stop through POST /api/v2/tours/{tour_id}/stops using
location, using the same fixed location value as Task visits: paired
lat/lon, or an address with street and country_code, plus optional label, postal fields
and observation time. Stops have no separate name. Template destinations use that same value.
Maps and distance calculations require coordinates; address-only destinations are not silently geocoded.
A Stop PATCH merges supplied location fields, preserving omitted fields and clearing explicit nulls
only when the resulting destination remains complete.
Read stops through the same collection URL.
Combine stops explicitly with POST /api/v2/tours/{tour_id}/stops/{stop_id}/combine, passing
source_stop_id. The destination retains its identity and planned location; all source
task assignments move to it. Nearby coordinates do not combine stops automatically.
An automatic stop disappears when its last task leaves; an empty standalone stop remains.
Read the complete ordered sequence through GET /api/v2/tours/{tour_id}/item-order.
Replace it atomically with PUT on the same URL:
{
"items": [
{ "type": "task", "task_id": "07b8775e-49d7-4980-adfe-1423a87765ab" },
{
"type": "stop",
"stop_id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
"task_ids": ["9bd78c05-ad21-4da2-8f7a-a15ab5c25dd5"]
}
],
"lock_version": 2
}
Every assigned task must appear exactly once, either at the top level or inside a stop.
Any task type can be grouped in a stop. Every standalone stop must remain in the sequence;
automatic stops may disappear when their tasks move elsewhere. Duplicate references return
422; stale versions, missing tasks or foreign stops return 409 without changing the tour.
The response contains the saved sequence and the new parent lock_version.
Moving a stop preserves its nested task order. Assignment position is its index within the
parent stop, or within the root sequence when stop_id is absent. Stop position is its index
in that same root sequence. Reordering preserves task content and emits tour, assignment and
stop update events for changed resources.
MCP and Ask Rob
The Tour MCP surface exposes Tour, stop, Task-assignment, settings and item-order operations with
the same business authorization as REST.
Use tours_list / tours_get for discovery, tour_task_assignments_* for membership,
tour_stops_* for stop editing and combining, and tour_item_order_get /
tour_item_order_update for complete ordering. Lifecycle actions are tours_publish,
tours_start, tours_finish and tours_start_ad_hoc; tours_use_vehicle changes active Vehicle use.
MCP cannot supply secondary Device proof and rejects device_context. It can use the
Device-unaware command forms and still receives server-coordinated participant cleanup.
Payload objects use the REST snake_case fields; tool parameters such as tourId and
assignmentId use camelCase. Optional versions, omitted/null fields, validation and current
resource authorization have the same meaning as REST. Participant access does not grant planning
access to ordinary Tours. Ad-hoc creation requires the current active human user. MCP read-only
mode blocks mutations, including lifecycle actions. Ordinary creation has no retry receipt;
inspect state after an uncertain outcome before intentionally creating again.
Permissions, concurrency and recovery
| Operation | Required access | State restrictions |
|---|---|---|
| Read Tours, Stops, item order and assignments | tours:read, or tours:read-own for a published Tour containing the current human | Other own-access Tours return 404 |
| Create draft | tours:create; template copying also needs tour-templates:read and tasks:write | Template/date and all copied references must be valid |
| Edit Tour, Stops, membership, combine and order | tours:update, or tours:execute-own for one's own ad-hoc Tour | Finished Tours and their assigned Tasks are immutable |
| Assign Vehicles, or use one on an active Tour | Tour read and vehicles:read, plus tours:update or tours:vehicles:assign-own for a participant | Vehicle-only changes; use requires an active Tour |
| Publish | tours:update | At least one participant; Tour must not be finished |
| Start, finish, or set standalone Stop status | tours:update, or tours:execute-own for an active human participant | Published Tour; finish also requires a started Tour and completed work |
| Delete Tour | Both tours:delete and tours:update | Only before starting; Tasks survive and become unassigned |
| Start ad-hoc | tours:start-ad-hoc and an active human | No participant may already have an active Tour |
Vehicle assignment permission does not grant description, schedule, participant or execution
changes. A Vehicle-only PATCH sends vehicles and an optional lock_version. The active-Tour
POST /api/v2/tours/{tour_id}/use-vehicle command uses the same assignment authority; it does not
require tours:execute-own. A nonparticipant with own-assignment permission receives
403 access-denied with data.reason: not_member for a globally readable Tour, or 404 when
own-read visibility conceals it. Selecting the current phone as a source additionally requires
devices:vehicles:assign-self and vehicles:device-location:use-self; this is unnecessary when configured
hardware already supplies location. Device proof and observed association context follow the
authentication contract.
Execution without the real required grant returns 403 access-denied with data.reason: missing_grant and data.required_grants. Own execution hides nonvisible Tours with 404.
For a globally readable Tour, a grant holder who is not a participant receives
403 tours/execution-forbidden with data.reason: not_member, without required_grants.
API-only users, service accounts and non-user actors receive 403 tours/human-required for
human-only actions; non-user actors use wrong_actor_type, other exclusions use not_member.
A visible unpublished Tour returns 409 tours/not-published after access checks.
The optional, nonnegative lock_version protects the resource being edited:
| Write | Version to send |
|---|---|
| Task PATCH or interaction answer | Task version |
| Stop PATCH | Stop version |
| Assignment PATCH | Assignment version |
| Tour PATCH, publish, start, use or finish | Tour version |
| Combine Stops or replace complete order | Parent Tour version |
| Template PATCH | Template version |
Omission or null skips the optimistic precondition. It does not skip validation, access checks
or transactional serialization. DELETE has no supplied version precondition. A stale version or
concurrent database change returns 409 resource-conflict; reread before deciding whether to retry.
Repeated publish/finish calls return the current result when already in the requested state.
Repeated Start also requires matching Vehicle/source intent as described above,
except publishing or starting a finished Tour is rejected. The version check runs first, so retrying
with a stale supplied version still conflicts. Creating a Tour or assignment has no replay key.
Vehicle references in request bodies use 422 validation-failed when the Vehicle is unavailable.
The sub-error pointer identifies the submitted field: #/vehicles/0/vehicle_id for creation or
PATCH, #/vehicle_use/vehicle_id for Start/ad-hoc Start, and #/vehicle_id or
#/replace_vehicle_id for the active-Tour use-vehicle command. Unknown replacement references
also use that field-level response; a known Vehicle that is no longer assigned uses
409 tours/vehicle-use-conflict. An unreadable or missing addressed Tour remains 404 not-found.
These failures leave assignments unchanged. Branch on status and type, not the human-readable
detail text.
Membership growth enforces 500 Stops and 10,000 Tasks plus Stops under the same transaction
lock, including concurrent assignment, cross-Tour moves and template materialization. Rejection
leaves source and destination membership, versions and events unchanged. A valid aggregate fits a
complete order read/write. 409 tours/capacity-exceeded means reduce membership or choose another
Tour. Existing oversize data is preserved: inspect counts, unassign work or remove empty Stops
until within limits before replacing its complete order. No automatic deletion repairs old data.
Task visit destinations are copied when a Stop is created. Later Task or Stop location edits do not propagate to the other resource. A cross-Tour assignment move preserves the Task and either moves its exclusive automatic Stop or creates a destination Stop from the Task's current visit; other work in a combined Stop stays behind. Stop completion with assigned Tasks is derived from those Tasks: set their status instead of sending a status write to a task-backed Stop.
Conflict types describe the required recovery: tours/finished and tours/already-started reject
immutable changes; tours/participants-required requires participants before publication;
tours/not-started requires starting; tours/unfinished-work requires completing or unassigning
work. tours/participant-active identifies the blocking Tour in data.tour_id.
tours/task-already-assigned requires moving/removing the existing assignment;
tours/stop-has-tasks requires unassigning before deleting; tours/task-backed-stop requires
completing its Tasks. tours/membership-changed requires a fresh complete order; tours/same-stop
requires distinct combine IDs. For Vehicle coordination, handle these additional problem types:
| Status / type suffix | Recovery |
|---|---|
409 tours/vehicle-confirmation-required | Review data.active_use_conflicts and explicitly set acknowledge_active_use: true on each conflicting planned assignment. |
409 tours/vehicle-active | End or resolve the conflicting actual use before Start/use; planning acknowledgement cannot override it. |
409 tours/device-active | Resolve the Device's incompatible active work before reassignment/login. |
409 tours/vehicle-required | Assign an eligible Vehicle before first Start. |
409 tours/vehicle-ineligible | Replace the excluded assignment or change authorized settings before first Start. |
409 tours/vehicle-use-conflict | Refresh the Tour; use the active Vehicle command for changed intent or a changed replacement target. |
409 tours/default-template-protected | Edit Default; it cannot be deleted. |
409 vehicle-device-associations/mode-unconfirmed | Have a manager confirm fixed/portable mode before the operation. |
409 devices/vehicle-association-changed | Refresh the observed episode and obtain new intent; never apply an old disconnect to a newer association. |
Type URIs begin with https://problems.tourfold.com/. Device authentication, login/session and logout
errors follow the authentication guide. See the full
problem catalog.