# Role

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

> A Role is a seat that owns a set of work and holds the Permissions to do it, filled by a Human or an Agent.

A Role is a seat that owns a set of work and holds the [Permissions](/business/nouns/permission) to do it, filled by a [Human](/business/nouns/human) or an [Agent](/business/nouns/agent). The work and its Permissions stay with the seat when a new filler takes it.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The title of the seat. |
| `responsibilities` | `text` | No | The work the seat owns. |
| `status` | `string` | Yes | One of `vacant` or `filled`. |
| `autonomy` | `json` | No | How much its agent does without asking: a rung, `assist`, `supervised` or `full`, with another rung per decision class where it differs. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/roles/role_1",
  "$type": "Role",
  "name": "Kiln Bakery",
  "responsibilities": "Example responsibilities",
  "status": "vacant",
  "autonomy": {
    "default": "supervised",
    "byClass": {
      "high": "assist"
    }
  }
}
```

## Relationships
- <a id="rel-filled-by"></a>A Role **is filled by** many [Workers](/business/nouns/worker): a [Worker](/business/nouns/worker), human or agent, fills a Role and acts under its [Permissions](/business/nouns/permission); one [Agent](/business/nouns/agent) can fill Roles in many [Startups](/business/nouns/startup). `filledBy`, inverse [`fills`](/business/nouns/worker#rel-fills).
- <a id="rel-holds"></a>A Role **holds** many [Permissions](/business/nouns/permission): a Role’s [Permissions](/business/nouns/permission) are what its [Worker](/business/nouns/worker) may do: [Verbs](/business/nouns/verb) on [Nouns](/business/nouns/noun) within a scope and a [Limit](/business/nouns/limit). `holds`, inverse [`heldBy`](/business/nouns/permission#rel-held-by).
- <a id="rel-openings"></a>A Role **has** many [Openings](/business/nouns/opening): an [Opening](/business/nouns/opening) is a need for a [Human](/business/nouns/human) in one Role, taking a share of that Role’s work. `openings`, inverse [`staffs`](/business/nouns/opening#rel-staffs).
- <a id="rel-personas"></a>A Role **has** many [Personas](/business/nouns/persona): the Role whose [Permissions](/business/nouns/permission) a [Persona](/business/nouns/persona) signs in with, so an [App](/business/nouns/app) compiles its [Dashboards](/business/nouns/dashboard) and [Verbs](/business/nouns/verb) from one record. `personas`, inverse [`holds`](/business/nouns/persona#rel-holds).
- <a id="rel-requires"></a>A Role **requires** many [Skills](/business/nouns/skill): the [Skills](/business/nouns/skill), each at a level, a [Worker](/business/nouns/worker) needs to fill the Role. `requires`, inverse [`requiredBy`](/business/nouns/skill#rel-required-by).
- <a id="rel-role-reviews"></a>A Role **has** many [Role Reviews](/business/nouns/role-review): each [Role Review](/business/nouns/role-review) checks one Role, and a Role keeps every review it has had. `roleReviews`, inverse [`reviews`](/business/nouns/role-review#rel-reviews).
- <a id="rel-team"></a>A Role **has** one [Team](/business/nouns/team): a [Team](/business/nouns/team) groups the Roles that do one kind of work under one owner. `team`, inverse [`groups`](/business/nouns/team#rel-groups).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `vacant` (first) | No Worker fills it, so its work waits for the Role above. | `filled` by [Role.staff](/business/nouns/role/staff) |
| `filled` | A Human or an Agent fills it and performs its Verbs under its Permissions. | `vacant` by [Role.vacate](/business/nouns/role/vacate); `vacant` on [`Agent.retired`](/business/events/Agent.retired) when the Agent filling this Role is retired; `vacant` on `Agent.deleted` when the Agent filling this Role is deleted; `vacant` on `Human.deleted` when the Human filling this Role is deleted |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Role.review](/business/nouns/role/review) | Review checks one Role against its contract for a period and records a Role Review. | [Founder](/agents/founding/founder) | [`Role.reviewed`](/business/events/Role.reviewed) | Two-way: `try`, `send`, `do` |
| [Role.staff](/business/nouns/role/staff) | Staff fills a Role with a Worker, human or agent, who then performs the Role’s Verbs under its Permissions. | [People Lead](/agents/people/people-lead) | [`Role.staffed`](/business/events/Role.staffed) | None. |
| [Role.vacate](/business/nouns/role/vacate) | Vacate takes the Worker out of a Role, and the seat’s Tasks route to the Role it escalates to until a new Worker is staffed. | [People Lead](/agents/people/people-lead) | [`Role.vacated`](/business/events/Role.vacated) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Role.create](/business/nouns/role/create) | Creates a Role. Inherited from [Noun](/business/nouns/noun). | None. | `Role.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Role.get](/business/nouns/role/get) | Returns one Role by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Role.list](/business/nouns/role/list) | Returns Roles, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Role.update](/business/nouns/role/update) | Changes the given properties of a Role. Inherited from [Noun](/business/nouns/noun). | None. | `Role.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Role.delete](/business/nouns/role/delete) | Deletes a Role; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Role.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` |
| --- | --- | --- | --- | --- |
| `Role.create` | Yes | Yes | No | No |
| `Role.get` | Yes | Yes | Yes | Yes |
| `Role.list` | Yes | Yes | Yes | Yes |
| `Role.update` | Yes | Yes | No | No |
| `Role.delete` | Yes | Yes | No | No |
| `Role.review` | Yes | Yes | No | No |
| `Role.staff` | Yes | Yes | No | No |
| `Role.vacate` | Yes | Yes | No | No |

## Call it

**Ask**

```text
Staff the latest role with a worker.
```

**API**

```bash
curl -X POST https://api.sb/kilnbakery.com/roles/role_1/staff \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"worker":"worker_1"}'
```

```json
{
  "api": "https://api.sb/kilnbakery.com",
  "role": {
    "$id": "https://api.sb/kilnbakery.com/roles/role_1",
    "$type": "Role",
    "name": "Kiln Bakery",
    "status": "vacant"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/action_1",
    "operation": "Role.staff",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/action_1"
  }
}
```

**SDK**

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

const role = await $.Role.staff({ role: 'role_1', worker: 'worker_1' })
```

**CLI**

```bash
npx startup-builder do Role.staff --json '{"role":"role_1","worker":"worker_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Role.staff({ role: 'role_1', worker: 'worker_1' })"
  }
}
```

## Example
The [Customer Lead](/agents/customer/customer-lead) Role at a tutoring marketplace owns first replies and refunds under $100. An Agent fills it on weekdays and the [Founder](/agents/founding/founder) on weekends; the $100 refund [Limit](/business/nouns/limit) binds both.