Zum Hauptinhalt springen

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:

ValueMeaning
eligibleThe Vehicle definition is allowed for Tours.
excludedThe definition is excluded; new assignments and first Start are blocked.
retained_active_useThe 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:

IntentRequest shape
Dispatcher starts the already planned VehiclesNo secondary Device header and no device_context; optional lock_version.
Phone starts a Tour with one planned VehicleSecondary header plus device_context; no vehicle_use is needed.
Select/add/replace a Vehicle while startingSecondary header and device_context, plus vehicle_use describing the Vehicle change.
API selects a Vehicle without nominating a phonevehicle_use on Start/ad-hoc Start, without Device header/context.
Change/use a Vehicle after StartPOST …/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=stops returns stops[] with destinations, positions, versions and standalone completion state. It omits Task arrays and Task identifiers.
  • include=tasks returns all Stops, ordered stops[].tasks[], root tasks[], and task_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=tasks equals include=tasks; unknown, empty or comma-separated include values return 422 at #/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​

OperationRequired accessState restrictions
Read Tours, Stops, item order and assignmentstours:read, or tours:read-own for a published Tour containing the current humanOther own-access Tours return 404
Create drafttours:create; template copying also needs tour-templates:read and tasks:writeTemplate/date and all copied references must be valid
Edit Tour, Stops, membership, combine and ordertours:update, or tours:execute-own for one's own ad-hoc TourFinished Tours and their assigned Tasks are immutable
Assign Vehicles, or use one on an active TourTour read and vehicles:read, plus tours:update or tours:vehicles:assign-own for a participantVehicle-only changes; use requires an active Tour
Publishtours:updateAt least one participant; Tour must not be finished
Start, finish, or set standalone Stop statustours:update, or tours:execute-own for an active human participantPublished Tour; finish also requires a started Tour and completed work
Delete TourBoth tours:delete and tours:updateOnly before starting; Tasks survive and become unassigned
Start ad-hoctours:start-ad-hoc and an active humanNo 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:

WriteVersion to send
Task PATCH or interaction answerTask version
Stop PATCHStop version
Assignment PATCHAssignment version
Tour PATCH, publish, start, use or finishTour version
Combine Stops or replace complete orderParent Tour version
Template PATCHTemplate 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 suffixRecovery
409 tours/vehicle-confirmation-requiredReview data.active_use_conflicts and explicitly set acknowledge_active_use: true on each conflicting planned assignment.
409 tours/vehicle-activeEnd or resolve the conflicting actual use before Start/use; planning acknowledgement cannot override it.
409 tours/device-activeResolve the Device's incompatible active work before reassignment/login.
409 tours/vehicle-requiredAssign an eligible Vehicle before first Start.
409 tours/vehicle-ineligibleReplace the excluded assignment or change authorized settings before first Start.
409 tours/vehicle-use-conflictRefresh the Tour; use the active Vehicle command for changed intent or a changed replacement target.
409 tours/default-template-protectedEdit Default; it cannot be deleted.
409 vehicle-device-associations/mode-unconfirmedHave a manager confirm fixed/portable mode before the operation.
409 devices/vehicle-association-changedRefresh 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.