# Task

URL: /business/nouns/task · Id: `noun:task`

> A Task is an Action waiting on a Worker, with an assignee, a due time, and a place in that Worker’s inbox.

A Task is an [Action](/business/nouns/action) waiting on a [Worker](/business/nouns/worker), with an assignee, a due time, and a place in that Worker’s inbox.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `due` | `datetime` | No | When the Task is due. |
| `priority` | `integer` | No | Its rank in the inbox, highest first. |
| `recurrence` | `string` | No | The schedule a recurring duty repeats on. |

<details>
<summary>Inherited from [Action](/business/nouns/action): 11 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | One of `pending`, `done`, `failed`, `canceled`, or `refused`. |
| `reason` | `string` | No | Why a pending Action waits: `queued`, `running`, `retrying`, `awaitingWorker`, `awaitingInput`, `awaitingSource`, `awaitingAction`, or `awaitingTime`. |
| `mode` | `string` | Yes | How the caller invoked it: `try`, `send`, or `do`. |
| `by` | [Worker](/business/nouns/worker) | No | The Worker that performed it. |
| `for` | [Party](/business/nouns/party) | No | The Party it was done on behalf of. |
| `via` | `string` | No | The Interface or request it arrived through. |
| `on` | `string` | No | The Action or Event that caused it, such as the failed attempt a retry follows. |
| `thing` | `string` | No | The record, at the Version the Action was decided against. |
| `input` | `json` | No | The input it was called with. |
| `createdAt` | `datetime` | No | When it was called. |
| `reserved` | `money` | No | The most this Action may cost, held against its Limits from the check until it settles, billed misses included. |

</details>

## Object
```json
{
  "$id": "https://api.sb/routewise.dev/tasks/task_1",
  "$type": "Task",
  "status": "pending",
  "reason": "queued",
  "mode": "try",
  "by": "worker_1",
  "for": "party_1",
  "via": "API",
  "on": "Invoice.overdue",
  "thing": "invoice_1@v3",
  "input": {},
  "createdAt": "2026-10-22T12:00:00Z",
  "reserved": {
    "amount": 25,
    "currency": "USD"
  },
  "due": "2026-10-22T12:00:00Z",
  "priority": 1,
  "recurrence": "Weekly on Friday"
}
```

## Relationships
- <a id="rel-assigned-to"></a>A Task **is assigned to** one [Worker](/business/nouns/worker): the [Worker](/business/nouns/worker) a Task waits on; the Task sits in that Worker’s inbox until it is done. `assignedTo`, inverse [`tasks`](/business/nouns/worker#rel-tasks).
- <a id="rel-project"></a>A Task **has** one [Project](/business/nouns/project): a [Project](/business/nouns/project) is made of Tasks. `project`, inverse [`plans`](/business/nouns/project#rel-plans).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Task.assign](/business/nouns/task/assign) | Assign gives a Task to a Worker, human or agent, and places it in that Worker’s worklist. | [Product Lead](/agents/product/product-lead) | [`Task.assigned`](/business/events/Task.assigned) | None. |
| [Task.claim](/business/nouns/task/claim) | Claim takes an offered Task from a shared queue or a handoff and makes the calling Worker its assignee. | [Supply Manager](/agents/operations/supply-manager) | [`Task.claimed`](/business/events/Task.claimed) | None. |
| [Task.complete](/business/nouns/task/complete) | Complete marks a Task done and resumes the Action that waited on it. | [Supply Manager](/agents/operations/supply-manager) | [`Task.completed`](/business/events/Task.completed) | None. |
| [Task.delegate](/business/nouns/task/delegate) | Delegate passes a Task to another Role along a declared handoff and keeps its history. | [Operations Lead](/agents/operations/operations-lead) | [`Task.delegated`](/business/events/Task.delegated) | None. |
| [Task.escalate](/business/nouns/task/escalate) | Escalate moves a Task to the Role its current Role escalates to, with the reason attached. | [Operations Lead](/agents/operations/operations-lead) | [`Task.escalated`](/business/events/Task.escalated) | None. |
| [Task.next](/business/nouns/task/next) | Next returns the oldest open Task the calling Worker’s Roles may claim, without claiming it. | [Worker](/business/nouns/worker) | [`Task.offered`](/business/events/Task.offered) | None. |
| [Task.return](/business/nouns/task/return) | Return hands an offered Task back to its sender, unchanged, with the reason the receiver cannot take it. | [Supply Manager](/agents/operations/supply-manager) | [`Task.returned`](/business/events/Task.returned) | None. |
| <a id="create"></a>[Task.create](/business/nouns/task/create) | Creates a Task. Inherited from [Noun](/business/nouns/noun). | None. | `Task.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Task.get](/business/nouns/task/get) | Returns one Task by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Task.list](/business/nouns/task/list) | Returns Tasks, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Task.update](/business/nouns/task/update) | Changes the given properties of a Task. Inherited from [Noun](/business/nouns/noun). | None. | `Task.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Task.delete](/business/nouns/task/delete) | Deletes a Task; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Task.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Task.create` | Yes | Yes | Yes | No |
| `Task.get` | Yes | Yes | Yes | Yes |
| `Task.list` | Yes | Yes | Yes | Yes |
| `Task.update` | Yes | Yes | Yes | No |
| `Task.delete` | Yes | Yes | Yes | No |
| `Task.assign` | Yes | Yes | Yes | No |
| `Task.claim` | Yes | Yes | Yes | No |
| `Task.complete` | Yes | Yes | Yes | No |
| `Task.delegate` | Yes | Yes | Yes | No |
| `Task.escalate` | Yes | Yes | Yes | No |
| `Task.next` | Yes | Yes | Yes | No |
| `Task.return` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Assign the latest task with a worker.
```

**API**

```bash
curl -X POST https://api.sb/quietcopy.com/tasks/task_1/assign \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"worker":"worker_1"}'
```

```json
{
  "api": "https://api.sb/quietcopy.com",
  "task": {
    "$id": "https://api.sb/quietcopy.com/tasks/task_1",
    "$type": "Task",
    "status": "pending",
    "mode": "try"
  },
  "action": {
    "$id": "https://api.sb/quietcopy.com/actions/action_1",
    "operation": "Task.assign",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/quietcopy.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const task = await $.Task.assign({ task: 'task_1', worker: 'worker_1' })
```

**CLI**

```bash
npx startup-builder do Task.assign --json '{"task":"task_1","worker":"worker_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Task.assign({ task: 'task_1', worker: 'worker_1' })"
  }
}
```

## Example
A parent asks a tutoring marketplace to reschedule. The reply is a Task assigned to the [Customer Lead](/agents/customer/customer-lead), due in 15 minutes, at the top of its inbox.