# Role routes: review, staff, vacate

URL: /code/api/role/verbs · Id: `page:code/api/role/verbs`

> The Role Verbs review, staff, vacate as api.sb routes, with inputs, result, refusals and an example.

Reference for [Role](/business/nouns/role), one group of [Role routes](/code/api/role).

### Role.review
Review checks one Role against its contract for a period and records a Role Review. [Verb page](/business/nouns/role/review?interface=api).

```text
POST /{namespace}/roles/{role}/review
```

Path: `role`. Body, as JSON: the other inputs. Emits [`Role.reviewed`](/business/events/Role.reviewed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to review. |
| `period` | `string` | Yes | The period it covers, such as `2026-W43`. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The reviewed Role. |
| `roleReview` | [Role Review](/business/nouns/role-review) | Yes | The recorded Role Review. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/roles/role_oloMFMUeCH/review \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"Example period"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "role": {
    "$id": "https://api.sb/leaseline.app/roles/role_oloMFMUeCH",
    "$type": "Role",
    "name": "Success Manager",
    "status": "filled"
  },
  "roleReview": {
    "$id": "https://api.sb/leaseline.app/role-reviews/rolereview_Eflst84AOW",
    "$type": "RoleReview",
    "role": "role_oloMFMUeCH",
    "period": "2026-W43"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Role.review",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Role.staff
Staff fills a Role with a Worker, human or agent, who then performs the Role’s Verbs under its Permissions. [Verb page](/business/nouns/role/staff?interface=api).

```text
POST /{namespace}/roles/{role}/staff
```

Path: `role`. Body, as JSON: the other inputs. Emits [`Role.staffed`](/business/events/Role.staffed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to fill. |
| `worker` | [Worker](/business/nouns/worker) | Yes | The Worker who fills it. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The staffed Role. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| The record is not in a state that allows this Verb, so the call is refused. | [`refused`](/code/api/errors/refused) | Read the record, run the Verb that moves it to an allowed state, then retry. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/roles/role_oloMFMUeCH/staff \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"worker":"worker_whZFpOKWIV"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "role": {
    "$id": "https://api.sb/leaseline.app/roles/role_oloMFMUeCH",
    "$type": "Role",
    "name": "Success Manager",
    "status": "filled"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Role.staff",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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. [Verb page](/business/nouns/role/vacate?interface=api).

```text
POST /{namespace}/roles/{role}/vacate
```

Path: `role`. Body, as JSON: the other inputs. Emits [`Role.vacated`](/business/events/Role.vacated).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to empty. |
| `reason` | `text` | No | Why the seat empties. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The vacant Role. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/roles/role_oloMFMUeCH/vacate \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "role": {
    "$id": "https://api.sb/leaseline.app/roles/role_oloMFMUeCH",
    "$type": "Role",
    "name": "Success Manager",
    "status": "filled"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Role.vacate",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```