# Scheduled tasks

> Prosaic AI tasks that run a prompt unattended on a schedule, and running one now.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List scheduled tasks

`GET /api/public/v1/scheduled-tasks`

SDK: `prosaic.scheduledTasks.list()`

Returns the Prosaic AI scheduled tasks in the workspace associated with the API key, newest first.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `name` (string, required)
    - `prompt` (string, required)
    - `entityId` (string, nullable, required)
    - `cron` (string, required)
    - `schedule` (string, required)
    - `timezone` (string, required)
    - `isEnabled` (boolean, required)
    - `autoApproveWrites` (boolean, required)
    - `emailTo` (string, nullable, required)
    - `lastRunAt` (string, date-time, nullable, required)
    - `lastStatus` (string, nullable, required)
    - `lastError` (string, nullable, required)
    - `runCount` (number, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Workspace not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/scheduled-tasks \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Get a scheduled task

`GET /api/public/v1/scheduled-tasks/{id}`

SDK: `prosaic.scheduledTasks.retrieve(id)`

Returns a single Prosaic AI scheduled task, including how its last run went.

### Path parameters

- `id` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `prompt` (string, required)
    - `entityId` (string, nullable, required)
    - `cron` (string, required)
    - `schedule` (string, required)
    - `timezone` (string, required)
    - `isEnabled` (boolean, required)
    - `autoApproveWrites` (boolean, required)
    - `emailTo` (string, nullable, required)
    - `lastRunAt` (string, date-time, nullable, required)
    - `lastStatus` (string, nullable, required)
    - `lastError` (string, nullable, required)
    - `runCount` (number, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Task not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.retrieve(id);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a scheduled task

`POST /api/public/v1/scheduled-tasks`

SDK: `prosaic.scheduledTasks.create(params)`

Creates a Prosaic AI scheduled task. The task runs its prompt unattended on the
given cadence, in Pacific/Auckland time.

`emailTo` must be the address of a member of the same workspace — a task is a
standing instruction to send a workspace's books somewhere, so arbitrary
recipients are refused with 400.

### Request body

Content type: `application/json`

- `name` (string, required)
- `prompt` (string, required)
- `schedule` (object, required)
  - `cadence` (string, required): One of: `daily`, `weekdays`, `weekly`, `monthly`.
  - `hour` (number, required)
  - `minute` (number, required)
  - `weekday` (number)
  - `dayOfMonth` (number)
- `entityId` (string, nullable)
- `isEnabled` (boolean)
- `autoApproveWrites` (boolean)
- `emailTo` (string, nullable)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `prompt` (string, required)
    - `entityId` (string, nullable, required)
    - `cron` (string, required)
    - `schedule` (string, required)
    - `timezone` (string, required)
    - `isEnabled` (boolean, required)
    - `autoApproveWrites` (boolean, required)
    - `emailTo` (string, nullable, required)
    - `lastRunAt` (string, date-time, nullable, required)
    - `lastStatus` (string, nullable, required)
    - `lastError` (string, nullable, required)
    - `runCount` (number, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
- `400`: Validation failed, or the email recipient is not a workspace member
- `401`: Unauthorized
- `403`: Entity is outside the caller's access
- `404`: Workspace not found
- `409`: Workspace is at its scheduled-task limit
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.create({
  name: 'Example Ltd',
  prompt: 'string',
  schedule: {
    cadence: 'daily',
    hour: 1,
    minute: 1,
  },
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/scheduled-tasks \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "prompt": "string",
    "schedule": {
      "cadence": "daily",
      "hour": 1,
      "minute": 1
    }
  }'
```

## Update a scheduled task

`PATCH /api/public/v1/scheduled-tasks/{id}`

SDK: `prosaic.scheduledTasks.update(id, params)`

Updates a Prosaic AI scheduled task. Every field is optional; omitted fields are
left as they are. Supplying `schedule` replaces the cadence, and `isEnabled`
is how a task is paused or resumed.

### Path parameters

- `id` (string, required)

### Request body

Content type: `application/json`

- `name` (string)
- `prompt` (string)
- `entityId` (string, nullable)
- `schedule` (object)
  - `cadence` (string, required): One of: `daily`, `weekdays`, `weekly`, `monthly`.
  - `hour` (number, required)
  - `minute` (number, required)
  - `weekday` (number)
  - `dayOfMonth` (number)
- `isEnabled` (boolean)
- `autoApproveWrites` (boolean)
- `emailTo` (string, nullable)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `prompt` (string, required)
    - `entityId` (string, nullable, required)
    - `cron` (string, required)
    - `schedule` (string, required)
    - `timezone` (string, required)
    - `isEnabled` (boolean, required)
    - `autoApproveWrites` (boolean, required)
    - `emailTo` (string, nullable, required)
    - `lastRunAt` (string, date-time, nullable, required)
    - `lastStatus` (string, nullable, required)
    - `lastError` (string, nullable, required)
    - `runCount` (number, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation failed, or the email recipient is not a workspace member
- `401`: Unauthorized
- `403`: Entity is outside the caller's access
- `404`: Task not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.update(id, {
  name: 'Example Ltd',
  prompt: 'string',
  entityId: 'ENTITY_ID',
  schedule: {
    cadence: 'daily',
    hour: 1,
    minute: 1,
  },
  isEnabled: true,
  autoApproveWrites: true,
  emailTo: 'accounts@example.com',
});
```

### Example (curl)

```bash
curl -X PATCH https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "prompt": "string",
    "entityId": "ENTITY_ID",
    "schedule": {
      "cadence": "daily",
      "hour": 1,
      "minute": 1
    },
    "isEnabled": true,
    "autoApproveWrites": true,
    "emailTo": "accounts@example.com"
  }'
```

## Run a scheduled task now

`POST /api/public/v1/scheduled-tasks/{id}/run`

SDK: `prosaic.scheduledTasks.run(id)`

Queues one immediate run of the task without touching its schedule. The run is
enqueued rather than executed inline, so a 202 means "accepted", not "finished" —
poll the task and read `lastRunAt` / `lastStatus` to see how it went.

Note the run executes with the task's own settings, which includes writing to the
books unattended when `autoApproveWrites` is true.

### Path parameters

- `id` (string, required)

### Responses

- `202`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `queued` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid task ID
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Task not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.run(id);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID/run \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Delete a scheduled task

`DELETE /api/public/v1/scheduled-tasks/{id}`

SDK: `prosaic.scheduledTasks.del(id)`

Soft-deletes a Prosaic AI scheduled task and unregisters its schedule. The chat
sessions its past runs produced are kept — they are the record of what was spent
and what was changed.

### Path parameters

- `id` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `deleted` (boolean, required)
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Task not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.scheduledTasks.del(id);
```

### Example (curl)

```bash
curl -X DELETE https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```