> 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.md).

# Schedule

Schedule entries that create tasks automatically, each day they are due.

A task schedule creates [tasks](/docs/navixy-api/user-api/resources/field-service/task.md) automatically instead of someone creating the same task by hand every week. Shortly after midnight in the [user's timezone](/docs/navixy-api/user-api/resources/commons/user/settings.md), the Navixy platform checks the schedule, and any task due to start that day is created and assigned to its employee.

A schedule entry looks much like a task, with one difference that matters when writing one. A task carries `from` and `to` as specific dates and times; a schedule entry carries `from_time`, `duration`, and `parameters` instead, because it describes a shape rather than an occurrence.

## Task schedule entry object

## The TaskScheduleEntry object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","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 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},"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},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this 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. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"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"]}}}}
```

## The ScheduleParameters object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}
```

## API actions

API base path: `/task/schedule`.

Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes).

***

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

## Create task schedule

> Create a task schedule, and return its ID.\
> \
> Just after midnight in the user's own time zone, the platform checks every schedule and creates the tasks due that day, assigning them where an assignee is set.\
> \
> 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":{"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","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 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},"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},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this 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. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"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"]}},"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/create":{"post":{"tags":["Tasks"],"summary":"Create task schedule","description":"Create a task schedule, and return its ID.\n\nJust after midnight in the user's own time zone, the platform checks every schedule and creates the tasks due that day, assigning them where an assignee is set.\n\nRequires the `task_update` right.","operationId":"taskScheduleCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"allOf":[{"$ref":"#/components/schemas/TaskScheduleEntry"}],"description":"The schedule to create, without `id`. Read-only fields are ignored."}},"required":["schedule"]}}}},"responses":{"200":{"description":"The created 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 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"},"402":{"description":"Error 236: the tracker's plan does not allow tasks.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 204: `schedule.form_template_id` names a form template that does not exist.","$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):

* 201 - Not found in the database - if schedule.tracker\_id belongs to nonexistent tracker.
* 204 - Entity not found - if schedule.form\_template\_id belongs to nonexistent form template.
* 208 - Device blocked - if tracker exists but was blocked due to tariff restrictions or some other reason.
* 236 - Feature unavailable due to tariff restrictions - if device's tariff does not allow usage of tasks.

***

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

## Delete task schedule

> Delete a task schedule by ID. Tasks it has already generated are left alone.\
> \
> Note the parameter is \`schedule\_id\`, not \`id\`, unlike \`task/schedule/read\`.\
> \
> 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/delete":{"post":{"tags":["Tasks"],"summary":"Delete task schedule","description":"Delete a task schedule by ID. Tasks it has already generated are left alone.\n\nNote the parameter is `schedule_id`, not `id`, unlike `task/schedule/read`.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskScheduleDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule_id":{"type":"integer","description":"ID of the task schedule to delete.","minimum":1}},"required":["schedule_id"]}}}},"responses":{"200":{"description":"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):

* 201 - Not found in the database - if there is no task schedule with such an ID.

***

This call also returns all unassigned task schedules.

## List task schedules

> List the task or route schedules of the current user, including every unassigned one.\
> \
> Callable with an empty body. Also accepts GET with the same parameters as query-string values.

```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":{"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","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 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},"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},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this 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. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"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"]}},"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/list":{"post":{"tags":["Tasks"],"summary":"List task schedules","description":"List the task or route schedules of the current user, including every unassigned one.\n\nCallable with an empty body. Also accepts GET with the same parameters as query-string values.","operationId":"taskScheduleList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trackers":{"type":"array","description":"Optional. IDs of the trackers the schedules are assigned to.","items":{"type":"integer"}},"filter":{"type":"string","description":"Optional. Filter over schedule label and description."},"tag_ids":{"type":"array","description":"Optional. Tag IDs. A schedule must carry **all** the tags in the list to be returned.","items":{"type":"integer"}},"types":{"type":"array","description":"Optional. Default `[\"task\"]`. Which kind of schedule to return.","items":{"type":"string","enum":["task","route"]}}}}}}},"responses":{"200":{"description":"Matching schedules","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/TaskScheduleEntry"}}}}}}},"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"}}}}}}
```

***

## Read task schedule

> Return a task, route or checkpoint schedule by ID.\
> \
> \`checkpoints\` is present only when the ID belongs to a route schedule.\
> \
> Note the parameter is \`id\`, not \`schedule\_id\`, unlike \`task/schedule/delete\`.\
> \
> Also accepts GET with the same parameters as query-string values.

```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":{"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","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 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},"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},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this 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. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"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/read":{"post":{"tags":["Tasks"],"summary":"Read task schedule","description":"Return a task, route or checkpoint schedule by ID.\n\n`checkpoints` is present only when the ID belongs to a route schedule.\n\nNote the parameter is `id`, not `schedule_id`, unlike `task/schedule/delete`.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"taskScheduleRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID of a task, route or checkpoint schedule.","minimum":1}},"required":["id"]}}}},"responses":{"200":{"description":"The schedule","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/TaskScheduleEntry"},"checkpoints":{"type":"array","description":"Every checkpoint schedule of the route schedule. Present only when the given ID is a route schedule.","items":{"$ref":"#/components/schemas/CheckpointScheduleEntry"}}}}}}},"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"}}}}}}
```

***

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

## Update task schedule

> Update a task schedule. Pass a full schedule object including its \`id\`.\
> \
> Changing a schedule does not touch tasks it has already generated.\
> \
> 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":{"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","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 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},"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},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this 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. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"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"]}},"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/update":{"post":{"tags":["Tasks"],"summary":"Update task schedule","description":"Update a task schedule. Pass a full schedule object including its `id`.\n\nChanging a schedule does not touch tasks it has already generated.\n\nRequires the `task_update` right.","operationId":"taskScheduleUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"allOf":[{"$ref":"#/components/schemas/TaskScheduleEntry"}],"description":"The schedule to update, including its `id`. Read-only fields are ignored."}},"required":["schedule"]}}}},"responses":{"200":{"description":"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"},"402":{"description":"Error 236: the tracker's plan does not allow tasks.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 204: no task schedule with this ID exists.","$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):

* 201 - Not found in the database - if schedule.tracker\_id belongs to nonexistent tracker.
* 204 - Entity not found - if there is no task schedule with specified ID.
* 208 - Device blocked - if tracker exists but was blocked due to tariff restrictions or some other reason.
* 236 - Feature unavailable due to tariff restrictions - if device's tariff does not allow usage of tasks.

## More in this section

#### Task schedule checkpoints

| Endpoint                                                                                                                                                       | Method | What it does                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------- |
| [`/task/schedule/checkpoint/delete`](/docs/navixy-api/user-api/resources/field-service/task/schedule/checkpoint.md#post-task-schedule-checkpoint-delete)       | POST   | Delete schedule checkpoint          |
| [`/task/schedule/checkpoint/transmute`](/docs/navixy-api/user-api/resources/field-service/task/schedule/checkpoint.md#post-task-schedule-checkpoint-transmute) | POST   | Convert schedule checkpoint to task |

#### Schedule proposals

| Endpoint                                                                                                                                       | Method | What it does            |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------- |
| [`/task/schedule/proposal/list`](/docs/navixy-api/user-api/resources/field-service/task/schedule/proposal.md#post-task-schedule-proposal-list) | POST   | List schedule proposals |

#### Route schedules

| Endpoint                                                                                                                                  | Method | What it does          |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------- |
| [`/task/schedule/route/create`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-create) | POST   | Create route schedule |
| [`/task/schedule/route/delete`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-delete) | POST   | Delete route schedule |
| [`/task/schedule/route/update`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-update) | POST   | Update route schedule |


---

# 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.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.