---
title: "Workflow: Schedules"
section: "API Reference"
route: /apiworkflowschedules
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Workflow: Schedules

Schedules raise tickets on a repeating cycle, such as a monthly inspection of a set of assets. Each time the schedule comes due, it raises a ticket, or puts an existing ticket back into its starting status and queue.

This article will cover how a schedule runs and how to manage schedules. You can read about tickets in [Workflow: Tickets](/apiworkflowtickets).

## Data model

```typescript
interface ISchedule {
    // Unique ID for the schedule.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 200 characters.
    // Also used as the name of each raised ticket's own Entity.
    Name: string;
    // Copied to each raised ticket's description.
    Description?: string;
    // ISO 8601 date time string of the first run.
    "Start.DateTime": string;
    // Days between runs. Must be greater than 0.
    // Default is 30.
    "Recurrence.Days"?: number;
    // The type, status and queue each raised ticket is given. All three are required.
    "Workflow.ItemType.ID": number;
    "Workflow.ItemStatus.ID": number;
    "Workflow.Queue.ID": number;
    // Days after a run that the ticket is due. Leave empty for no due date.
    "DueDate.Interval.Days"?: number | null;
    // Internal IDs of the Entities each raised ticket is about.
    // An Entity's internal ID is its "Bruce.InternalID" value.
    "Subject.Entity.InternalID"?: number[];
    // If true then each run puts the same ticket back into the starting status and queue,
    // rather than raising a new one. See below.
    "Reset.On"?: boolean;
    // ID of the ticket that is put back each run. Set by the API on the first run.
    "Reset.Workflow.Item.ID"?: number | null;
    // ID of a bookmark showing where the work is. Limited to 40 characters.
    "UI.Slide.ID"?: string;
    // ID of a Client File used as each ticket's thumbnail. Limited to 64 characters.
    "Thumbnail.ClientFile.ID"?: string;
    // Set by the API.
    "Created.DateTime"?: string;
    "Created.ByUser.ID"?: string;
}
```

## How a schedule runs

A schedule comes due at its start time and every "Recurrence.Days" after that. Each time it comes due:

- If a ticket it raised is still in the schedule's status and queue, nothing happens. The work from the last cycle has not started, so no second ticket is raised.
- Otherwise, if "Reset.On" is true and the schedule has a ticket to put back, that ticket is moved back into the schedule's type, status and queue, with a new due date.
- Otherwise a new ticket is raised, with a new Entity of the type's Entity Type. When "Reset.On" is true, this ticket becomes the one that is put back on later runs.

Tickets are raised as the user who created the schedule, and the queue's user groups are notified as usual. The type must have an Entity Type set, or the schedule is skipped.

## Requesting records

You can list every schedule, or only the schedules about a given Entity.

### Get a list of schedules

```http
GET https://{accountId}.api.nextspace.host/workflow/schedules?EntityID={entity_id}&EntityInternalID={internal_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `EntityID={entity_id}` | query | no | Only schedules with this Entity as a subject. |
| `EntityInternalID={internal_id}` | query | no | The same filter, by the Entity's internal ID. |

**Response**

```typescript
interface IResponse {
    Items: ISchedule[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/schedules";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get schedule by ID

```http
GET https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{schedule_id}` | path | yes | The ID of the schedule to get. |

**Response**

```typescript
// The response is the schedule record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Create and update records

You can create a schedule by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed. Send null for "DueDate.Interval.Days" to remove the due date.

### Create or update schedule

```http
POST https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{schedule_id}` | path | yes | The ID of the schedule to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the schedule JSON as specified above.
```

**Example request body**

```json
{
    "Name": "Monthly pump inspection",
    "Start.DateTime": "2026-11-01T00:00:00Z",
    "Recurrence.Days": 30,
    "Workflow.ItemType.ID": 2,
    "Workflow.ItemStatus.ID": 4,
    "Workflow.Queue.ID": 1,
    "DueDate.Interval.Days": 7,
    "Subject.Entity.InternalID": [
        1024
    ]
}
```

**Response**

```typescript
// The response is the schedule record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}";
const method = "post";
const token = "your-token";
const body = {
    "Name": "Monthly pump inspection",
    "Start.DateTime": "2026-11-01T00:00:00Z",
    "Recurrence.Days": 30,
    "Workflow.ItemType.ID": 2,
    "Workflow.ItemStatus.ID": 4,
    "Workflow.Queue.ID": 1,
    "DueDate.Interval.Days": 7,
    "Subject.Entity.InternalID": [
        1024
    ]
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete a record

Deleting a schedule stops future runs. Tickets it already raised are kept.

### Delete schedule

```http
DELETE https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{schedule_id}` | path | yes | The ID of the schedule to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/schedule/{schedule_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apiworkflowschedules
