> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/engineering-reference/api/planner.md).

# Planner API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/api/planner.md).
{% endhint %}

Planned and repeating tasks (schedules): creating, changing, pausing and deleting them, listing them and the tasks they are due to create, and bulk uploads. The calendar-event and future-task actions in php-apis have no live caller.

A **schedule** is a repeat rule plus a task template (`job_json`), stored as a row of [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md). Nothing in these requests creates tasks: py\_scheduler turns due schedules into tasks on its own cron, and those are ordinary tasks of the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md).

* **Services:** `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`, `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`. api\_php\_live\_v2 has no planner route; its checklist schedules are in [Checklists](https://docs.snapfix.com/engineering-reference/api/checklists.md).
* **Auth:** apipy: user token (authpy access JWT in `Authorization: Bearer`). The create, change, delete and planned-task list routes take the user from the request body, not from the token. The schedule routes check no group membership at all. `/v3/scheduler/job` takes no login. `/schedule-upload` checks no staff flag. php-apis: its actions have no live caller (see the notes under the table).
* **Used by:** web\_app\_v2 (planner, planned task editor, asset planned tasks), iOS (scheduler list, schedule editor, planner timeline, asset planned tasks), Android (manage schedules, schedule editor, planner timeline, asset planned tasks), webadmin\_angular (bulk upload), py\_scheduler (task creation); 19 of the 33 endpoints have no live caller.
* **Answers:** apipy answers `{result, message, serverTs, data}`; `message` is "success" on the happy path. Almost every failure is HTTP `200` with `result: false` and the message; the token and blocked-address errors are in [API conventions](https://docs.snapfix.com/engineering-reference/api.md).

The product: [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md).

| Method | Path                                               | Service      | Purpose                                                                                                                                                                                                                     |
| ------ | -------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ANY    | `?action=create_serveronly_jobcalevent`            | php-apis     | Create a calendar event for a task and email it (no caller)                                                                                                                                                                 |
| ANY    | `?action=future_jobs`                              | php-apis     | Copy a task onto future dates (`initCreatingFutureJobs`) (no caller)                                                                                                                                                        |
| ANY    | `?action=future_jobs_dev`                          | php-apis     | Runs the `future_jobs` checks but copies nothing (no caller)                                                                                                                                                                |
| ANY    | `?action=future_jobs_test`                         | php-apis     | Runs the `future_jobs` checks but copies nothing (no caller)                                                                                                                                                                |
| ANY    | `?action=future_jobs_v2`                           | php-apis     | Runs the test handler `executeCreatingFutureJobsTest` (no caller)                                                                                                                                                           |
| ANY    | `?action=send_calendar_event`                      | php-apis     | Meant to email a calendar event (iCal); calls a method `Functions` doesn't have, so it fails (no caller)                                                                                                                    |
| ANY    | `?action=webcust_plan_job`                         | php-apis web | Create a planned task (no caller)                                                                                                                                                                                           |
| ANY    | `?action=webcust_schedule_added`                   | php-apis web | Save a task chat message for an added schedule, type 38 (no caller)                                                                                                                                                         |
| ANY    | `?action=webcust_schedule_cancelled`               | php-apis web | Save a task chat message for a cancelled schedule, type 40 (no caller)                                                                                                                                                      |
| ANY    | `?action=webcust_schedule_updated`                 | php-apis web | Save a task chat message for an updated schedule, type 39 (no caller)                                                                                                                                                       |
| POST   | `/jobs`                                            | apipy        | List tasks (no caller)                                                                                                                                                                                                      |
| POST   | `/schedule`                                        | apipy        | Create a schedule for an existing task, version 1 (no caller)                                                                                                                                                               |
| PUT    | `/schedule`                                        | apipy        | Replace a task's version 1 schedule (no caller)                                                                                                                                                                             |
| DELETE | `/schedule`                                        | apipy        | Delete a task's version 1 schedule (no caller)                                                                                                                                                                              |
| POST   | [`/schedule-upload`](#post-schedule-upload)        | apipy        | Create schedules in bulk from a spreadsheet                                                                                                                                                                                 |
| GET    | `/schedule/{uuid}`                                 | apipy        | Get a task's version 1 schedule; `{uuid}` is the task (no caller)                                                                                                                                                           |
| PUT    | [`/schedule/{uuid}/pause`](#put-scheduleuuidpause) | apipy        | Pause a schedule                                                                                                                                                                                                            |
| PUT    | [`/schedule/{uuid}/play`](#put-scheduleuuidplay)   | apipy        | Resume a schedule                                                                                                                                                                                                           |
| PUT    | `/schedule_task_data`                              | apipy        | Copy a task's details into its schedule template (`scheduleTaskData`) (no caller)                                                                                                                                           |
| POST   | [`/schedules`](#post-schedules)                    | apipy        | List schedules                                                                                                                                                                                                              |
| POST   | [`/schedules-v2`](#post-schedules-v2)              | apipy        | List schedules, with a total                                                                                                                                                                                                |
| POST   | [`/schedules-v2/uuids`](#post-schedules-v2uuids)   | apipy        | List the UUIDs of the matching schedules                                                                                                                                                                                    |
| POST   | [`/schedules/pause`](#post-schedulespause)         | apipy        | Pause schedules in bulk                                                                                                                                                                                                     |
| POST   | `/schedules/play`                                  | apipy        | Resume schedules in bulk (no caller)                                                                                                                                                                                        |
| POST   | [`/v3/jobs`](#post-v3jobs)                         | apipy        | List planned tasks in a time window, created and not yet created (`listScheduledJobsV4_1`)                                                                                                                                  |
| POST   | `/v3/jobs-retd`                                    | apipy        | List tasks (`listJobsV3`) (no caller)                                                                                                                                                                                       |
| POST   | [`/v3/schedule`](#post-v3schedule)                 | apipy        | Create a schedule                                                                                                                                                                                                           |
| PUT    | [`/v3/schedule`](#put-v3schedule)                  | apipy        | Change a schedule                                                                                                                                                                                                           |
| DELETE | [`/v3/schedule`](#delete-v3schedule)               | apipy        | Delete a schedule, or part of it                                                                                                                                                                                            |
| GET    | [`/v3/schedule/{uuid}`](#get-v3scheduleuuid)       | apipy        | Get a schedule                                                                                                                                                                                                              |
| POST   | [`/v3/scheduler/job`](#post-v3schedulerjob)        | apipy        | Create a task from a schedule trigger; py\_scheduler's fallback when it can't create it locally \[[ASK-50](https://github.com/snapfix/docs/blob/main/ASK.md#ask-50-which-job_create_mode-does-production-py_scheduler-use)] |
| POST   | [`/v4/jobs`](#post-v4jobs)                         | apipy        | List planned tasks that are not created yet, with the calendar days that have them (`listScheduledJobsV4_2`)                                                                                                                |
| POST   | `/v4/schedules`                                    | apipy        | List planned tasks with the time zone (`listScheduledJobsV4`) (no caller)                                                                                                                                                   |

Notes on the table:

* Rows marked "(no caller)" have no caller in the pinned clones. The only references are in code that never runs: a block comment or commented-out call (Android `JobChatFragment.java`, iOS `MessagesVC.swift`, iOS `APIManager.swift`), a method nothing calls (Android `callCopyJobOnSelectedDataApiOLD`, `callJobImageUploadToServerAPi`), or a screen that nothing opens. Android's old schedule screen `ScheduleTaskOldActivity`, the only client of the four version 1 `/schedule` routes, is started only from a popup menu that `showListPopupWindow` builds, and nothing calls that method (android @ 86068bfeea, `fragment/JobChatFragment.java:4973`, `:5026`). Whether to remove these endpoints is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The ten `ANY` rows keep `ANY`: no live caller sends a method for them.
* Version 1 schedules (`/schedule`, the legacy [`schedule`](https://docs.snapfix.com/engineering-reference/db/tables/schedule.md) table) hang off an existing task, and every version 1 write is copied into `schedule_v3` with `sch_version` `v2`. py\_scheduler reads only `schedule_v3`, so those copies still run.
* `PUT /schedule_task_data` copies a task's current details into its version 1 schedule template, and then into `schedule_v3`. It works only within 30 seconds of the task's last change.
* The php-apis actions are not described further. Their code includes `future_jobs` copying one task per day, week or month with no upper limit, and the calendar-email code behind `create_serveronly_jobcalevent` holds a mail-service key in the source.

## POST /schedule-upload

Creates one schedule for each row of an Excel workbook. The admin app's groups menu offers it as "Upload Multiple Schedules", when a site is selected.

* **Auth:** user token. Any signed-in user can call it, for any group named in the sheet; the admin app is the only screen that does. Each row names its creator, who must be a member of the row's group, and the schedule is saved as that user.
* **Used by:** webadmin\_angular (`UploadMultipleSchedulesModalComponent`, opened from the groups page menu).

**Request** (multipart form)

| Name             | In   | Type | Required | Rules                                                                                                                                             |
| ---------------- | ---- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule_excel` | body | file | yes      | An `.xlsx` workbook. Missing: "schedule\_excel is mandatory". The admin app allows 150 rows and offers a sample workbook; the server has no limit |

The workbook has a `Task_details` sheet with one row per schedule and these columns: `parent_uuid`, `group_uuid`, `job_title`, `job_image_url`, `job_status`, `checklist_worksheet`, `tags_worksheet`, `user_assigned_worksheet`, `user_following_worksheet`, `user_created_uuid`, `start_date_excel`, `day_week_month_year_once` (`day`, `week`, `month`, `year` or `once`, saved as `daily`, `weekly`, `monthly`, `yearly` or `single`), `mon_tue_wed_thu_fri_sat_sun`, `frequency`, `priority`, `notes` and `reminder`. The worksheet columns name the other sheets: checklists (`title`, `sortorder`, `yes_no`, `pass_flag_fail`, `add_notes_photo`, `mandatory`, `section`), tags (`tag_header_uuid`, `tag_name`, `comments`), and assigned and following users (`uuid`, `email`, `country_code`, `mobile_number`). Every sheet is checked before any row is saved.

**Response** `200`: the `data` field has one of three shapes.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": { "message": "2 schedules created successfully!" }
}
```

When the workbook fails its checks, `data` holds `validationFlag: false` and a `messageList`, and nothing is saved:

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "validationFlag": false,
    "messageList": [{ "message": "invalid user assignees(email)(Task_details)" }]
  }
}
```

When some rows fail to save, `data` is a list of the failed rows, each with its `schedule` and a `message` (for example "User Bueinss record does not exist" when the creator isn't in the group), and `result` is still `true`. The admin app then shows "Success".

**Errors:** `200` with `result: false` and the message (for example "schedule\_excel is mandatory").

**Side effects:**

* For each row that passes the checks, saves a schedule as [POST /v3/schedule](#post-v3schedule) does, with `preview` 0, into [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md). No task is created here; py\_scheduler creates the tasks when they are due.
* Rows are saved one after another in the request.

## PUT /schedule/{uuid}/pause

Pauses a schedule. py\_scheduler creates no tasks for a paused schedule until it is resumed.

* **Auth:** user token. The token's user is saved as the modifier. The schedule is not checked against the caller's groups.
* **Used by:** web\_app\_v2 (the scheduler card's switch, through `PlannerHttpService.updateScheduleState`), iOS (scheduler list and schedule editor, through `pausePlaySchedulerAPI` with `schedule-pause`), Android (`ScheduleViewModel.playPauseSchedule` from the schedule editor and the manage schedules screen).

**Request**

| Name   | In   | Type   | Required | Rules               |
| ------ | ---- | ------ | -------- | ------------------- |
| `uuid` | path | string | yes      | The schedule's UUID |

No body.

**Response** `200`

```json
{
  "result": true,
  "message": "schedule paused successfully",
  "serverTs": 1794387601000,
  "data": {
    "uuid": "schedule-123",
    "paused": 1,
    "pausedTs": 1794387601000,
    "playTs": 1794300000000,
    "job_json": { "uuid_tBusiness": "group-200", "fTitle": "Check fire doors", "fDescription": "" },
    "fCreatedTs": 1794000000000,
    "type": "weekly",
    "uuid_tBusiness": "group-200",
    "business_name": "Maintenance",
    "group_name": "NA",
    "uuid_tUser_CreatedBy": "user-100",
    "user_name": "Jane Smith"
  }
}
```

`data` is a [schedule summary](#schedule-summary), without the list-only fields.

**Errors:** `200` with `result: false`: "invalid schedule!" (not found or deleted); "schedule already paused!".

**Side effects:** updates [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md): `paused` 1, `pausedTs`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`. Tasks already created are not changed.

## PUT /schedule/{uuid}/play

Resumes a paused schedule. If its next task time has passed, the next time is worked out again from today, so no past tasks are created.

* **Auth:** user token. The token's user is saved as the modifier. The schedule is not checked against the caller's groups.
* **Used by:** web\_app\_v2 (`PlannerHttpService.updateScheduleState` with `play`), iOS (`pausePlaySchedulerAPI` with `schedule-play`), Android (`ScheduleViewModel.playPauseSchedule` with `schedule-play`).

**Request**

| Name   | In   | Type   | Required | Rules               |
| ------ | ---- | ------ | -------- | ------------------- |
| `uuid` | path | string | yes      | The schedule's UUID |

No body.

**Response** `200`: the same shape as the pause response, with the message "schedule resumed successfully" and `paused: 0`.

**Errors:** `200` with `result: false`: "invalid schedule!" (not found or deleted); "schedule is already active!"; "invalid schedule to resume!" (no next time can be worked out; the schedule stays paused).

**Side effects:** updates [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md): `paused` set to 0, `nextTriggerTs`, `nextTriggerDatetime`, `playTs`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`.

## POST /schedules

Lists the schedules of one or more groups, newest first, with paging. It backs the iOS scheduler list and the Android manage schedules screen.

* **Auth:** user token. The token's user replaces any `user_uuid` in the body, but it only labels the rows; the groups come from the request and are not checked against the caller.
* **Used by:** iOS (`SchedularListVC.getPlannedList`, from the scheduler tab), Android (`ScheduleViewModel.getScheduleTask`, from the manage schedules screen).

**Request** (JSON body; `offset` and `limit` may also come in the query string, which Android uses)

| Name                                                             | In            | Type              | Required                        | Rules                                                                                                                |
| ---------------------------------------------------------------- | ------------- | ----------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `business_uuids`                                                 | body          | array of string   | one of this or `parent_uuid`    | The groups to list. Used when not empty                                                                              |
| `parent_uuid`                                                    | body          | string            | one of this or `business_uuids` | A site; its groups are listed when `business_uuids` is empty. Neither, or a site with no groups: "no business found" |
| `search`                                                         | body          | string            | no                              | Case-insensitive match on the title, the stored search text, the tags, or a room name on the site                    |
| `priority`                                                       | body          | `0` or `1`        | no                              | The old star flag, `job_json.fPriority`                                                                              |
| `priorityLevel`                                                  | body          | array of integers | no                              | Meant to match `job_json.fPriorityLevel`. A non-empty list makes the call fail with HTTP `500`                       |
| `uuid_tUser_assignee`                                            | body          | array of string   | no                              | Compared with the whole stored assignee list, so it never matches                                                    |
| `uuids_room`, `uuids_area`                                       | body          | array of string   | no                              | Compared with the whole stored list, so they never match                                                             |
| `uuids_tag`, `uuid_assets`                                       | body          | array of string   | no                              | Text match on the template's tags, and on its linked tasks (`joblinks`)                                              |
| `uuid_tUser_created`                                             | body          | array of string   | no                              | Schedules created by one of these users                                                                              |
| `site_template_uuids_in`, `site_template_uuids_not_in`           | body          | array of string   | no                              | Checklist site templates. Groups where the template is hidden are left out                                           |
| `multisite_template_uuids_in`, `multisite_template_uuids_not_in` | body          | array of string   | no                              | Checklist multi-site templates, with the same rule                                                                   |
| `offset`                                                         | body or query | integer           | no                              | Row offset, default 0. Put straight into the SQL                                                                     |
| `limit`                                                          | body or query | integer           | no                              | Page size, default 10. No maximum                                                                                    |

When any template filter is sent, only live schedules come back: not deleted, not paused, and with a next task time in the future. Otherwise every schedule that isn't deleted comes back.

**Response** `200`: `data` is a list of [schedule summaries](#schedule-summary). The total is counted and then dropped. An empty page is still `result: true`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": [
    {
      "uuid": "schedule-123",
      "type": "weekly",
      "paused": 0,
      "pausedTs": 0,
      "playTs": 0,
      "fCreatedTs": 1794000000000,
      "startDate": "2026-11-13",
      "endDate": null,
      "nextTriggerTs": 1794387600000,
      "uuid_tBusiness": "group-200",
      "business_name": "Maintenance",
      "group_name": "NA",
      "uuid_tUser_CreatedBy": "user-100",
      "user_name": "Jane Smith",
      "user_onboard_type": "Active",
      "job_json": { "uuid_tBusiness": "group-200", "fTitle": "Check fire doors" }
    }
  ]
}
```

**Errors:** `200` with `result: false`: "no business found". HTTP `500` for a `priorityLevel` list.

**Side effects:** none. Each listed room, area and checklist template is loaded with its own query.

## POST /schedules-v2

Lists schedules for the web planner's schedule list, with a total count.

* **Auth:** as [POST /schedules](#post-schedules).
* **Used by:** web\_app\_v2 (`PlannerHttpService.getScheduleList`, from the planner's schedule list and the task and schedule list).

**Request** (JSON body; `offset` and `limit` may come in the query string): the fields of [POST /schedules](#post-schedules). The web sends `parent_uuid`, `business_uuids`, `search`, `priorityLevel`, `uuid_tUser_assignee`, `uuid_tUser_created`, `uuid_assets`, `uuid_asset_registers` (not read) and the template filters. So the web's priority filter makes the list fail, and its assignee filter never matches.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "schedules": [
      {
        "uuid": "schedule-123",
        "type": "weekly",
        "paused": 0,
        "startDate": "2026-11-13",
        "endDate": null,
        "nextTriggerTs": 1794387600000,
        "uuid_tBusiness": "group-200",
        "business_name": "Maintenance",
        "user_name": "Jane Smith",
        "job_json": { "uuid_tBusiness": "group-200", "fTitle": "Check fire doors" }
      }
    ],
    "total_count": 42
  }
}
```

`schedules` are [schedule summaries](#schedule-summary). `total_count` is counted only when `offset` is 0; any other offset returns `total_count` 0.

**Errors:** as [POST /schedules](#post-schedules).

**Side effects:** none.

## POST /schedules-v2/uuids

Returns the UUIDs of every schedule the same filters match, newest first, for "select all" in the web planner.

* **Auth:** as [POST /schedules](#post-schedules).
* **Used by:** web\_app\_v2 (`PlannerHttpService.getScheduleUuids`, from the task and schedule list's select all).

**Request** (JSON body): the same filters as [POST /schedules-v2](#post-schedules-v2). Paging is not read.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "uuids": ["schedule-123", "schedule-124"],
    "truncated": false,
    "limit": 5000
  }
}
```

`uuids` holds at most 5,000 UUIDs (`SCHEDULE_SELECT_ALL_LIMIT`). `truncated` is `true` when more match.

**Errors:** as [POST /schedules](#post-schedules).

**Side effects:** none.

## POST /schedules/pause

Pauses several schedules. The work is queued, and the response comes back before any schedule changes.

* **Auth:** user token. The token's user is saved as the modifier. The schedules are not checked against the caller's groups.
* **Used by:** web\_app\_v2 (`PlannerHttpService.pauseSchedules`, from the planner's multi-select actions).

**Request** (JSON body)

| Name    | In   | Type            | Required | Rules                                                                                 |
| ------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------- |
| `uuids` | body | array of string | yes      | Schedule UUIDs. Must be a non-empty list. No maximum; each schedule is paused in turn |

**Response** `200`, with no `data`:

```json
{
  "result": true,
  "message": "Request to pause schedules is accepted and will be processed shortly",
  "serverTs": 1794387600000
}
```

**Errors:** `200` with `result: false` and "invalid uuids" when `uuids` is missing, empty or not a list.

**Side effects:** a background (Celery) job pauses each schedule the same way as [PUT /schedule/{uuid}/pause](#put-scheduleuuidpause). Schedules that are already paused, or missing, are left out and are recorded only in the worker log. The response does not list them.

## POST /v3/jobs

Lists the planned tasks in a time window, oldest first: tasks that have been created from a schedule, and the occurrences schedules will create (the apps call these "ghost jobs"). The planner timelines and the asset planned-tasks tabs use it.

* **Auth:** user token. The body's `user_uuid` decides which groups are listed and whether the caller sees every task or only their own. The token's user is not compared with it.
* **Used by:** iOS (`SchedulerVC`, the planner timeline; `JobDetailViewModel.fetchPlannedTaskList`, the asset's planned tasks), Android (`ScheduleFragment.callScheduleJobApi` from the planner, and `SharedAssetDetailViewModel.getPlannedTasks` from the asset's tasks tab).

**Request** (form data; arrays are JSON text)

| Name                                                     | In   | Type                 | Required | Rules                                                                                                                                                                                                     |
| -------------------------------------------------------- | ---- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`                                              | body | string               | yes      | The user. Must be a string: "user\_uuid must be a valid string"                                                                                                                                           |
| `timestamp`                                              | body | integer              | no       | Milliseconds. Default now. The centre of the window                                                                                                                                                       |
| `lookup_direction`                                       | body | `0`, `1` or `2`      | no       | Default `0`. `0`: two days either side of `timestamp`. `1`: the tasks before `timestamp`, with no lower bound. `2`: the 10 days after `timestamp`. Created tasks are cut at now; occurrences start at now |
| `business_uuids`                                         | body | JSON array of string | no       | Groups to list. Deleted and inactive groups are dropped, and then only groups where `user_uuid` is a member are kept                                                                                      |
| `parent_uuids`                                           | body | JSON array of string | no       | Sites; their active groups are used when `business_uuids` gives no group. With neither field, the groups of `user_uuid`                                                                                   |
| `my_tasks`                                               | body | `1`                  | no       | Only the user's own tasks: created or followed by them in groups where they aren't an admin, or assigned to them                                                                                          |
| `priority`                                               | body | `0` or `1`           | no       | The old star flag                                                                                                                                                                                         |
| `colors`                                                 | body | JSON array of string | no       | `red`, `amber`, `green`. Without `red`, occurrences are left out                                                                                                                                          |
| `user_uuids_created_by`, `user_uuids_assigned_to`        | body | JSON array of string | no       | Creators or assignees                                                                                                                                                                                     |
| `tagname`                                                | body | string               | no       | A tag name. The match is built with quotes inside the value, so it never matches                                                                                                                          |
| `only_schedules`                                         | body | boolean              | no       | Default true: only created tasks that are planned tasks. False adds every other task in the window                                                                                                        |
| `schedule_uuids`                                         | body | JSON array of string | no       | Occurrences of these schedules only                                                                                                                                                                       |
| `priorityLevel`, `uuids_tag`, `uuids_room`, `uuids_area` | body | JSON array           | no       | Filter the occurrences only                                                                                                                                                                               |
| `uuid_assets`                                            | body | JSON array of string | no       | Assets. Filters occurrences by linked asset; created tasks are not filtered                                                                                                                               |
| `asset_attribute_value`                                  | body | string               | no       | Filters occurrences by asset attribute. The value is put into the SQL text                                                                                                                                |
| `uuid_asset_registers`, `schedule`                       | body |                      | no       | The apps send them; the server does not read them                                                                                                                                                         |

For groups where `user_uuid` is an admin or has "view all tasks", the created tasks are every planned task of the group. In other groups they are the tasks the user created, follows or is assigned to. When no group is left to list, the request fails with a server error instead of an empty list.

**Response** `200`: `data` is a list of [planned task objects](#planned-task-object), sorted by `fCreatedTs`. Occurrences stop after about 50: once 50 are listed, only those at the same time as the last one are added.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": [
    {
      "uuid": "job-300",
      "fTitle": "Check fire doors",
      "fCreatedTs": 1794387600000,
      "fPlannedJob": 1,
      "uuid_tBusiness": "group-200",
      "business_name": "Maintenance",
      "uuid_schedule_planned": "schedule-123",
      "color": "red"
    }
  ]
}
```

**Errors:** `200` with `result: false`: "user\_uuid must be a valid string"; "no jobs found" when nothing matches.

**Side effects:** none.

## POST /v3/schedule

Creates a schedule: a repeat pattern and a task template. Nothing is created in the task list until py\_scheduler reaches a due date.

* **Auth:** user token. The body's `user_uuid` is saved as the creator and must be an existing user; the token's user is not compared with it. The group in `job_json` is not checked against the caller's memberships.
* **Used by:** web\_app\_v2 (`PlannerHttpService.savePlannedTask`, planned task editor), iOS (`APIManager.schedulerAPIV3`, schedule editor), Android (`ScheduleTaskActivity`, schedule editor).

**Request** (form data; JSON objects and arrays are sent as text)

| Name                                        | In   | Type                 | Required              | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------- | ---- | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_uuid`                                 | body | string               | yes                   | An existing, not deleted user: "invalid user"                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `type`                                      | body | string               | yes                   | `single`, `daily`, `weekly`, `monthly` or `yearly`. Anything else: "invalid type"                                                                                                                                                                                                                                                                                                                                                                                                          |
| `start_date`                                | body | string               | yes                   | `YYYY-MM-DD`: "invalid start\_date". A date of today or earlier moves to tomorrow \[[ASK-63](https://github.com/snapfix/docs/blob/main/ASK.md#ask-63-should-a-schedule-that-starts-today-really-start-tomorrow)]; the web and iOS date pickers do not offer today, so only Android and direct calls reach this. For `single` a past date is refused ("invalid schedule request -> schedule date looks like a past one, please check"), but that check is skipped when `start_time` is sent |
| `end_date`                                  | body | string               | no                    | `YYYY-MM-DD`: "invalid end\_date". The schedule stops after this date                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `start_time`                                | body | JSON array of string | no                    | Times of day, `HH:MM`, in the site's time zone, one task per time. Empty or missing: `00:01`                                                                                                                                                                                                                                                                                                                                                                                               |
| `job_json`                                  | body | JSON object          | yes                   | The task to create. See the rules below. Missing: "job\_json must be a mentioned"; not an object: "job\_json must be a valid JSON Object"                                                                                                                                                                                                                                                                                                                                                  |
| `preview`                                   | body | `0` or `1`           | yes in practice       | `1` returns the first dates without saving; `0` saves. Every client sends `0`. If the field is missing, nothing is saved but the call succeeds with `schedule_uuid` "dummy-schedule-uuid"                                                                                                                                                                                                                                                                                                  |
| `reminder`                                  | body | `0` or `1`           | no                    | Default `0`. `1` sets the first reminder 12 hours before the next task, or 15 minutes from now when that time has already passed. Later reminders are set 24 hours before their task, by py\_scheduler                                                                                                                                                                                                                                                                                     |
| `job_uuid`                                  | body | string               | no                    | An existing task the schedule comes from. The task's `uuid_schedule_origin` is set to the new schedule                                                                                                                                                                                                                                                                                                                                                                                     |
| `weekly`                                    | body | JSON object          | with `type` `weekly`  | `{ "recurrence": 1, "days": [1, 3] }`: `days` are weekdays 0 to 6, where 0 is Monday and 6 is Sunday                                                                                                                                                                                                                                                                                                                                                                                       |
| `monthly`                                   | body | JSON object          | with `type` `monthly` | `recurrence`, a whole number above 0, and optionally `first_day` with `first_weekday`, `last_day` with `last_weekday`, or `nearst_weekday_to_start_date` (spelled so)                                                                                                                                                                                                                                                                                                                      |
| `yearly`                                    | body | JSON object          | no                    | `{ "recurrence": 1 }`. Accepted; not checked                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `exclude_date`                              | body | JSON array of string | no                    | Dates to skip, `YYYY-MM-DD`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `interval`                                  | body | JSON object          | no                    | `{ "start_time", "end_time", "duration" }`: the times are `HH:MM`; `duration` must be an integer                                                                                                                                                                                                                                                                                                                                                                                           |
| `config_work_days`                          | body | JSON object          | no                    | `{ "region": "IE", "days": [0, 1, 2, 3, 4] }`: weekdays 0 to 6, where 0 is Monday                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sch_work_days_only`, `sch_work_hours_only` | body | boolean              | no                    | The check wants a real boolean, but form values are text, so the field fails ("invalid sch\_work\_days\_only") whenever it is the one checked                                                                                                                                                                                                                                                                                                                                              |
| `config_work_hours`                         | body | JSON object          | no                    | Work hours. No client sends it; it never passes its check                                                                                                                                                                                                                                                                                                                                                                                                                                  |

The checks of the optional fields are one `elif` chain: only the first of `end_date`, `start_time`, `exclude_date`, `interval`, `config_work_days`, `sch_work_days_only`, `config_work_hours`, `sch_work_hours_only`, and then the `monthly`, `weekly` or `single` rule, is checked. Every client sends `start_time`, so the rest are stored unchecked.

Rules for `job_json` (checked when saving):

* `uuid_tBusiness` is required. The group must exist and not be deleted: "uuid\_tBusiness must be mentioned in job\_json", "group does not exist", "group has been deleted".
* `fTitle` and `fDescription` must be strings: "invalid job title", "invalid job description".
* `fImage` must be an `http` URL, or `fLargeTextTitle` must be a non-empty string: "invalid job image".
* Other fields (`uuid_tUserBusiness`, assignees, followers, tags, checklist `todo`, files, `joblinks`, rooms, areas, compliance systems, checklist templates, priority, time range, due date, `search_text`) are stored and copied to each task when it is created.

The dates are read in the group's site time zone (`timezone_name`, or `Europe/Dublin` when the site has none), and the next task time is stored in UTC. The `timezone` column is stored empty.

**Response** `200`: `data.schedule_uuid` is the new schedule. With `preview: 1`, `data` holds up to 24 dates instead.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": { "schedule_uuid": "schedule-123" }
}
```

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "schedule_uuid": "preview-schedule-uuid",
    "dates": ["2026-11-13 09:00", "2026-11-20 09:00"]
  }
}
```

**Errors:** `200` with `result: false` and the message: the validation messages above; "invalid schedule preferences as we couldnt find any valid date to schedule the task" (the rules leave no date).

**Side effects:**

* Inserts one row in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md): the request as `schedule_json`, the task template as `job_json`, the first task time in UTC, the reminder fields, `paused` 0 and the creator. The insert is SQL built from the request values.
* With `job_uuid`, sets `uuid_schedule_origin` on [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md).
* Sends no notification. The reminder is sent by py\_scheduler.

## PUT /v3/schedule

Changes a schedule. The old schedule row is closed and a new row replaces it, for the whole schedule or from a date.

* **Auth:** the same as [POST /v3/schedule](#post-v3schedule).
* **Used by:** web\_app\_v2 (`PlannerHttpService.savePlannedTask` with PUT), iOS (`APIManager.schedulerAPIV3` with PUT, schedule editor), Android (`ScheduleTaskActivity`, schedule editor).

**Request** (form data): the same fields as [POST /v3/schedule](#post-v3schedule), plus:

| Name            | In   | Type   | Required | Rules                                                                                                                                                                                                                  |
| --------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule_uuid` | body | string | yes      | The schedule to change: "schedule\_uuid must be a valid string"; "invalid schedule" when not found; "schedule has been deleted already"                                                                                |
| `update_type`   | body | string | no       | `all` (default, the whole schedule), `single_date` (only the date in `start_date`; `end_date` must match or be empty) or `future_dates` (from `start_date` on). The type is used as sent, also for a `single` schedule |
| `job_uuid`      | body | string | no       | The task the schedule comes from. When missing, the stored one is kept                                                                                                                                                 |

The route doesn't require `job_json` on PUT, but the new row is built from it, so a change without a valid one fails. For `single_date` and `future_dates`, a date today or earlier is refused: "schedule cannot be edited when it has been created already". A date outside the schedule's range is refused: "invalid task date".

**Response** `200`: `data.schedule_uuid` is the new schedule, or `data` is `{ "data": null }` when the split leaves nothing to create.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": { "schedule_uuid": "schedule-124" }
}
```

**Errors:** `200` with `result: false`: the messages above, "invalid user", and the validation messages from [POST /v3/schedule](#post-v3schedule). "something went wrong!" when no new row is made. With `update_type` `all`, new settings that leave no date delete the old schedule and still answer "something went wrong!".

**Side effects:**

* Sets the old row's `fDeleted` to 1, or moves its end date to the day before the change, and inserts the new row (or up to three rows for a split) in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md). The new row keeps the paused state, `pausedTs` and `playTs`.
* For a schedule copied from version 1 (`sch_version` `v2`), soft-deletes its row in the legacy [`schedule`](https://docs.snapfix.com/engineering-reference/db/tables/schedule.md) table, and clears `uuid_schedule_origin` and `uuid_schedule_planned` on the tasks that point to it.
* Tasks already created are not changed, except for the links above, and `job_uuid` gets `uuid_schedule_origin` as on create.

## DELETE /v3/schedule

Deletes a schedule, or only one date or the part from a date on.

* **Auth:** user token. The body's `user_uuid` must be an existing user; the token's user is not compared with it. The schedule is not checked against the caller's groups.
* **Used by:** web\_app\_v2 (`PlannerHttpService.deletePlannedTask`, planned task editor), iOS (`CreateScheduleVC.deleteSchedule`), Android (`ScheduleTaskActivity`, schedule editor).

**Request** (form data)

| Name            | In   | Type   | Required                             | Rules                                                                                                                                                                                                                                          |
| --------------- | ---- | ------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`     | body | string | yes                                  | An existing, not deleted user: "invalid user"                                                                                                                                                                                                  |
| `schedule_uuid` | body | string | yes                                  | The schedule. Not a string: "schedule\_uuid must be a valid string". Not found or deleted: "sorry, we couldnt find the schedule!"                                                                                                              |
| `update_type`   | body | string | no                                   | `all` (default), `single_date` (one date: the dates around it continue as new rows) or `future_dates` (from `start_date` on). A `single` schedule is always deleted as `all`                                                                   |
| `start_date`    | body | string | with `single_date` or `future_dates` | `YYYY-MM-DD`. Missing: "invalid date to delete the schedule". Today or earlier: "schedule cannot be edited when it has been created already" (`single_date`) or "schedule cannot be deleted when it has been created already" (`future_dates`) |

`type` is not required here, so the create checks don't run.

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": { "schedule_uuid": "schedule-123", "info": "schedule has been deleted" }
}
```

**Errors:** `200` with `result: false`: the messages above, and "invalid task date" when the date is outside the schedule.

**Side effects:** marks the schedule's row in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) as deleted, or ends it at the date given, inserting rows for the dates that remain. For a schedule copied from version 1, the legacy row is soft-deleted and the tasks linked to it lose their schedule links. Otherwise tasks keep pointing at the deleted schedule: their `uuid_schedule_origin` is not cleared. Tasks already created stay as they are.

## GET /v3/schedule/{uuid}

Gets one schedule with its task template and settings. The schedule editors load it.

* **Auth:** user token. The schedule is not checked against the caller's groups.
* **Used by:** web\_app\_v2 (`PlannerHttpService.getPlannedTaskServerData`, planned task editor), iOS (`APIManager.getScheduleData`, schedule editor), Android (`ScheduleTaskActivity`, `doGetSchedule`).

**Request**

| Name   | In   | Type   | Required | Rules               |
| ------ | ---- | ------ | -------- | ------------------- |
| `uuid` | path | string | yes      | The schedule's UUID |

**Response** `200`: `data` is a [schedule object](#schedule-object).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "uuid": "schedule-123",
    "uuid_tJob": "",
    "sch_version": "v3",
    "paused": 0,
    "nextTriggerTs": 1794387600000,
    "nextTriggerDatetime": "2026-11-13 09:00:00",
    "schedule_json": { "type": "weekly", "start_date": "2026-11-13", "start_time": ["09:00"], "weekly": { "recurrence": 1, "days": [4] } },
    "job_json": { "uuid_tBusiness": "group-200", "fTitle": "Check fire doors", "fPriorityLevel": 0, "todos": [] },
    "uuid_tUser_CreatedBy": "user-100",
    "createdBy_username": "Jane Smith"
  }
}
```

**Errors:** `200` with `result: false` and "record(s) not found" when the schedule is missing or deleted.

**Side effects:** none.

## POST /v3/scheduler/job

Creates one task from a schedule trigger. py\_scheduler calls it when it cannot create the task itself, and for every trigger when its mode is not `local`.

* **Auth:** none. The token check on this route is commented out. Anyone can create a task in any group with it.
* **Used by:** py\_scheduler (`create_job_via_api_http` in `models/schedule_job_common.py`). py\_scheduler's config sets `JOB_CREATE_MODE = 'local'` with `JOB_CREATE_LOCAL_FALLBACK_TO_API = True` (py\_scheduler @ c8b1344036, `config/constant.py:138-141`), so the route is called when local creation fails.

**Request** (JSON body)

| Name              | In   | Type      | Required | Rules                                                                                                                                                                                                                                        |
| ----------------- | ---- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule_uuid`   | body | string    | no       | The schedule the trigger belongs to                                                                                                                                                                                                          |
| `job_json`        | body | JSON text | yes      | The task template. `uuid_tBusiness` must be a group that exists and is not deleted. The `uuid_tUserBusiness` key must be present: it names the creating member, and when it is empty or that member is gone, the group's first admin is used |
| `schedule_json`   | body | JSON text | yes      | The schedule settings                                                                                                                                                                                                                        |
| `fCreatedTs`      | body | integer   | yes      | The trigger time, in ms. The task is dated to it                                                                                                                                                                                             |
| `job_origin_uuid` | body | string    | no       | The task the schedule came from                                                                                                                                                                                                              |
| `pre_create`      | body | boolean   | no       | `true` for the tasks py\_scheduler creates ahead of time; they stay hidden (`fDeleted` 1) until due                                                                                                                                          |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": { "job_uuid": "job-300", "schedulelog_uuid": "log-400" }
}
```

**Errors:** `200` with `result: false` and the message: "invalid business", "invalid user business" (no member and no admin to create as), "invalid status" (the group has no "Red" status), "invalid sub status" (no "New" sub-status), and the other checks in the task creation path.

**Side effects:** creates the task (red, sub-status "New", planned) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) with its rows in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md), [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md) and [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md). It adds tags to the group's [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md) when the template names new ones, and writes a row to [`schedule_log_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_log_v3.md). No notification is sent; the push code is commented out. The schedule's next trigger is moved on by py\_scheduler, not here.

## POST /v4/jobs

Lists the planned tasks that are not created yet, for the web planner. It also returns the days that have them, for the calendar.

* **Auth:** the same as [POST /v3/jobs](#post-v3jobs).
* **Used by:** web\_app\_v2 (`PlannerHttpService.getPlannedTaskList`, from the planner's planned-task list and the asset's planned-task list).

**Request** (form data): the same fields as [POST /v3/jobs](#post-v3jobs). Only occurrences are listed; created tasks are not. The web sends `user_uuid`, `timestamp`, `lookup_direction`, `parent_uuids`, `business_uuids`, `priorityLevel`, `colors`, `my_tasks`, the people filters, `tagname`, `search`, `uuid_assets`, `asset_attribute_value`, `schedule_uuids` and `num_of_records`, which is not read.

**Response** `200`: `data.jobs` is a list of [planned task objects](#planned-task-object). `cal_highlight_ms` lists each distinct `fCreatedTs`, and `cal_highlight_dt` gives the same times in the site's time zone, `YYYY-MM-DD HH:MM:SS`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387600000,
  "data": {
    "jobs": [
      {
        "id": "schedule-123_2026-11-13 09:00:00",
        "uuid": "job-301",
        "schedule_uuid": "schedule-123",
        "schedule_date": "2026-11-13 09:00:00",
        "fCreatedTs": 1794387600000,
        "fTitle": "Check fire doors",
        "fPlannedJob": 1,
        "color": "red",
        "uuid_tBusiness": "group-200",
        "business_name": "Maintenance"
      }
    ],
    "cal_highlight_ms": [1794387600000],
    "cal_highlight_dt": ["2026-11-13 09:00:00"]
  }
}
```

**Errors:** as [POST /v3/jobs](#post-v3jobs).

**Side effects:** none.

## Schedule object

A schedule as [GET /v3/schedule/{uuid}](#get-v3scheduleuuid) returns it: the whole [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) row, with these changes.

| Field                                               | Type    | Meaning                                                                                                                                                                                                                                                 |
| --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                              | string  | The schedule's UUID, passed as `schedule_uuid` or in the path                                                                                                                                                                                           |
| `uuid_tJob`                                         | string  | The task the schedule came from, or empty                                                                                                                                                                                                               |
| `sch_version`                                       | string  | `v3`, or `v2` for a row copied from a version 1 schedule                                                                                                                                                                                                |
| `schedule_json`                                     | object  | The repeat settings as sent on create, without any `job_json`                                                                                                                                                                                           |
| `job_json`                                          | object  | The task template. `todo` and `todos` are copied onto each other; `job_links_data`, `room_data`, `area_data`, and `checklist_site_template_data` or `checklist_multisite_template_data`, describe the linked tasks, rooms, areas and checklist template |
| `radioReminder`, `lastReminderTs`, `nextReminderTs` | integer | The reminder flag and times, in ms                                                                                                                                                                                                                      |
| `lastTriggerTs`, `nextTriggerTs`                    | integer | The previous and next task times, in ms; 0 when the schedule has finished                                                                                                                                                                               |
| `lastTriggerDatetime`, `nextTriggerDatetime`        | string  | The same times, `YYYY-MM-DD HH:MM:SS` in UTC                                                                                                                                                                                                            |
| `paused`, `pausedTs`, `playTs`                      | integer | `1` while paused, and when it was paused and last resumed, in ms (`0` if never)                                                                                                                                                                         |
| `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy`     | string  | Who created it and who last changed it                                                                                                                                                                                                                  |
| `createdBy_username`                                | string  | The creator's first and last name, or "Snapfix Admin" when the creator isn't found                                                                                                                                                                      |

## Schedule summary

A schedule in [POST /schedules](#post-schedules) and [POST /schedules-v2](#post-schedules-v2), and in the pause and resume answers.

| Field                                               | Type           | Meaning                                                                                                                                                                                                 |
| --------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                              | string         | The schedule's UUID                                                                                                                                                                                     |
| `type`                                              | string         | `single`, `daily`, `weekly`, `monthly` or `yearly`                                                                                                                                                      |
| `paused`, `pausedTs`, `playTs`                      | integer        | As in the [schedule object](#schedule-object)                                                                                                                                                           |
| `fCreatedTs`                                        | integer        | When the schedule was created, in ms                                                                                                                                                                    |
| `job_json`                                          | object         | The task template; in lists also `room_data`, `area_data` and `checklist_template`                                                                                                                      |
| `uuid_tBusiness`, `business_name`                   | string         | The group and its name                                                                                                                                                                                  |
| `group_name`                                        | string         | Always `NA`                                                                                                                                                                                             |
| `uuid_tUser_CreatedBy`, `user_name`                 | string         | The creator and their name. Pause and resume give "Snapfix Admin" when the creator isn't found. Lists use a group admin's name, or another member's, when the creator isn't found or isn't in the group |
| `startDate`, `endDate`                              | string or null | `YYYY-MM-DD` from the repeat settings (lists only)                                                                                                                                                      |
| `nextTriggerTs`                                     | integer        | The next task's time, in ms (lists only)                                                                                                                                                                |
| `user_image`, `business_image`, `business_inactive` |                | The creator's photo, the group's image, and the group's `fInActive` flag (lists only)                                                                                                                   |
| `user_onboard_type`                                 | string         | The caller's onboarding state in the group, or "Active" when there is none (lists only)                                                                                                                 |

## Planned task object

A planned task in the lists of [POST /v3/jobs](#post-v3jobs) and [POST /v4/jobs](#post-v4jobs). There are two kinds, both with `uuid`, `fTitle`, `fCreatedTs`, `color`, `fPlannedJob`, `uuid_tBusiness`, `business_name` and `business_image`:

* A created task: its [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) columns, with `fPlannedJob` 1 and `uuid_schedule_planned` set to the schedule.
* An occurrence that is not created yet: a made-up `uuid`, `id` (`{schedule uuid}_{YYYY-MM-DD HH:MM:SS}`), `schedule_uuid`, `schedule_date` (the due time as text), `fCreatedTs` (the due time in ms), `job_json` (the template), `created_by` (`user_name`, `user_image`) and the task fields copied from the template, such as `fDescription`, `fPriorityLevel`, the due date fields and `search_text`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/engineering-reference/api/planner.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
