> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md).

# Route schedules

Scheduled routes, created on a repeating basis like recurring tasks.

These operations schedule [routes](/docs/navixy-api/user-api/resources/field-service/task/route.md) the same way [recurring tasks](/docs/navixy-api/user-api/resources/field-service/task/schedule.md) schedule single tasks: the Navixy platform creates the route and its checkpoints on each day the schedule is due.

## Route schedule entry

## The RouteScheduleEntry object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"RouteScheduleEntry":{"type":"object","description":"A recurring route. It carries no location or timing of its own: those live on its checkpoint schedules.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this route schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"}}},"ScheduleParameters":{"type":"object","description":"When a schedule fires. `type` selects which of the two forms applies, and the matching array must not be empty.","properties":{"type":{"type":"string","description":"Which form this is. `weekdays` repeats on days of the week, `month_days` on days of the month.","enum":["weekdays","month_days"]},"weekdays":{"type":"array","description":"Days of the week to create tasks on, where 1 is Monday and 7 is Sunday. Used when `type` is `weekdays`.","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7},"month_days":{"type":"array","description":"Days of the month to create tasks on, from 1 to 31. Used when `type` is `month_days`.","items":{"type":"integer","minimum":1,"maximum":31},"minItems":1,"maxItems":31}},"required":["type"]}}}}
```

## Checkpoint schedule entry

## The CheckpointScheduleEntry object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"CheckpointScheduleEntry":{"type":"object","description":"One stop on a recurring route. It carries the location and timing that a route schedule does not, and takes its firing days from its parent route schedule rather than holding `parameters` of its own.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this checkpoint schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parent_id":{"type":"integer","description":"ID of the route schedule this checkpoint schedule belongs to.","minimum":1},"order":{"type":"integer","description":"Zero-based position within the route schedule.","minimum":0},"location":{"type":"object","description":"The circular geofence for the generated task. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"from_time":{"type":"string","description":"Time of day at which the generated task starts, as `HH:MM:SS`."},"duration":{"type":"integer","description":"Total duration in minutes between the generated task's `from` and `to`. From 1 to 46080, which is 32 days.","minimum":1,"maximum":46080},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"tags":{"type":"array","description":"IDs of tags applied to this checkpoint schedule.","items":{"type":"integer"}},"form_template_id":{"type":["integer","null"],"description":"ID of a form template to build a form from on each generated task. Nullable.","minimum":1},"fields":{"type":"object","description":"Custom field values, keyed by custom field ID as a string.","additionalProperties":true}}}}}}
```

The `parameters` of a route schedule are the [schedule parameters](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#task-schedule-entry-object) described on the recurring tasks page: `weekdays` for creation on days of the week, where 1 is Monday and 7 is Sunday, or `month_days` for creation on days of the month, from 1 to 31.

## API actions

API base path: `/task/schedule/route`.

***

*Required sub-user rights:* `task_update`.

## Create route schedule

> Create a route schedule together with its checkpoint schedules, and return its ID.\
> \
> \*\*At least 2 checkpoints are required\*\*, the same rule as a real route.\
> \
> Requires the \`task\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"RouteScheduleEntry":{"type":"object","description":"A recurring route. It carries no location or timing of its own: those live on its checkpoint schedules.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this route schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"}}},"ScheduleParameters":{"type":"object","description":"When a schedule fires. `type` selects which of the two forms applies, and the matching array must not be empty.","properties":{"type":{"type":"string","description":"Which form this is. `weekdays` repeats on days of the week, `month_days` on days of the month.","enum":["weekdays","month_days"]},"weekdays":{"type":"array","description":"Days of the week to create tasks on, where 1 is Monday and 7 is Sunday. Used when `type` is `weekdays`.","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7},"month_days":{"type":"array","description":"Days of the month to create tasks on, from 1 to 31. Used when `type` is `month_days`.","items":{"type":"integer","minimum":1,"maximum":31},"minItems":1,"maxItems":31}},"required":["type"]},"CheckpointScheduleEntry":{"type":"object","description":"One stop on a recurring route. It carries the location and timing that a route schedule does not, and takes its firing days from its parent route schedule rather than holding `parameters` of its own.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this checkpoint schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parent_id":{"type":"integer","description":"ID of the route schedule this checkpoint schedule belongs to.","minimum":1},"order":{"type":"integer","description":"Zero-based position within the route schedule.","minimum":0},"location":{"type":"object","description":"The circular geofence for the generated task. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"from_time":{"type":"string","description":"Time of day at which the generated task starts, as `HH:MM:SS`."},"duration":{"type":"integer","description":"Total duration in minutes between the generated task's `from` and `to`. From 1 to 46080, which is 32 days.","minimum":1,"maximum":46080},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"tags":{"type":"array","description":"IDs of tags applied to this checkpoint schedule.","items":{"type":"integer"}},"form_template_id":{"type":["integer","null"],"description":"ID of a form template to build a form from on each generated task. Nullable.","minimum":1},"fields":{"type":"object","description":"Custom field values, keyed by custom field ID as a string.","additionalProperties":true}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/schedule/route/create":{"post":{"tags":["Tasks"],"summary":"Create route schedule","description":"Create a route schedule together with its checkpoint schedules, and return its ID.\n\n**At least 2 checkpoints are required**, the same rule as a real route.\n\nRequires the `task_update` right.","operationId":"taskScheduleRouteCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"route":{"allOf":[{"$ref":"#/components/schemas/RouteScheduleEntry"}],"description":"The route schedule to create, without `id`."},"checkpoints":{"type":"array","description":"The checkpoint schedules, in order of execution. At least 2.","items":{"$ref":"#/components/schemas/CheckpointScheduleEntry"},"minItems":2}},"required":["route","checkpoints"]}}}},"responses":{"200":{"description":"The created route schedule","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new route schedule entry."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* [General](/docs/navixy-api/general/errors.md#error-codes) types.

***

*Required sub-user rights:* `task_update`.

## Delete route schedule

> Delete a route schedule \*\*and its checkpoint schedules\*\* by ID.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`task\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/schedule/route/delete":{"post":{"tags":["Tasks"],"summary":"Delete route schedule","description":"Delete a route schedule **and its checkpoint schedules** by ID.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskScheduleRouteDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the route schedule.","minimum":1}},"required":["id"]}}}},"responses":{"200":{"description":"Route schedule deleted","$ref":"#/components/responses/OK"},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* [General](/docs/navixy-api/general/errors.md#error-codes) types.

***

If a checkpoint is being created, then it should have no id. If a checkpoint is being updated, then it should have an ID. If an old checkpoint is not present in the request, then it will be deleted.

*Required sub-user rights:* `task_update`.

## Update route schedule

> Update a route schedule and its checkpoint schedules.\
> \
> A checkpoint carrying an \`id\` is updated, one without an \`id\` is created, and \*\*any existing checkpoint absent from the request is deleted\*\*. When \`checkpoints\` is given it must still hold at least 2.\
> \
> Requires the \`task\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"RouteScheduleEntry":{"type":"object","description":"A recurring route. It carries no location or timing of its own: those live on its checkpoint schedules.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this route schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"}}},"ScheduleParameters":{"type":"object","description":"When a schedule fires. `type` selects which of the two forms applies, and the matching array must not be empty.","properties":{"type":{"type":"string","description":"Which form this is. `weekdays` repeats on days of the week, `month_days` on days of the month.","enum":["weekdays","month_days"]},"weekdays":{"type":"array","description":"Days of the week to create tasks on, where 1 is Monday and 7 is Sunday. Used when `type` is `weekdays`.","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7},"month_days":{"type":"array","description":"Days of the month to create tasks on, from 1 to 31. Used when `type` is `month_days`.","items":{"type":"integer","minimum":1,"maximum":31},"minItems":1,"maxItems":31}},"required":["type"]},"CheckpointScheduleEntry":{"type":"object","description":"One stop on a recurring route. It carries the location and timing that a route schedule does not, and takes its firing days from its parent route schedule rather than holding `parameters` of its own.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this checkpoint schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"parent_id":{"type":"integer","description":"ID of the route schedule this checkpoint schedule belongs to.","minimum":1},"order":{"type":"integer","description":"Zero-based position within the route schedule.","minimum":0},"location":{"type":"object","description":"The circular geofence for the generated task. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"from_time":{"type":"string","description":"Time of day at which the generated task starts, as `HH:MM:SS`."},"duration":{"type":"integer","description":"Total duration in minutes between the generated task's `from` and `to`. From 1 to 46080, which is 32 days.","minimum":1,"maximum":46080},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"tags":{"type":"array","description":"IDs of tags applied to this checkpoint schedule.","items":{"type":"integer"}},"form_template_id":{"type":["integer","null"],"description":"ID of a form template to build a form from on each generated task. Nullable.","minimum":1},"fields":{"type":"object","description":"Custom field values, keyed by custom field ID as a string.","additionalProperties":true}}}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/schedule/route/update":{"post":{"tags":["Tasks"],"summary":"Update route schedule","description":"Update a route schedule and its checkpoint schedules.\n\nA checkpoint carrying an `id` is updated, one without an `id` is created, and **any existing checkpoint absent from the request is deleted**. When `checkpoints` is given it must still hold at least 2.\n\nRequires the `task_update` right.","operationId":"taskScheduleRouteUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"route":{"allOf":[{"$ref":"#/components/schemas/RouteScheduleEntry"}],"description":"The route schedule to update, including its `id`."},"checkpoints":{"type":"array","description":"The checkpoint schedules this route should end up with. Anything absent is deleted.","items":{"$ref":"#/components/schemas/CheckpointScheduleEntry"},"minItems":2}},"required":["route"]}}}},"responses":{"200":{"description":"Route schedule updated","$ref":"#/components/responses/OK"},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* [General](/docs/navixy-api/general/errors.md#error-codes) types.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.