# Availability

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

> An Availability is the weekly hours a Worker can be booked in, less what their connected calendars already hold, with buffers and notice.

An Availability is the weekly hours a [Worker](/business/nouns/worker) can be booked in, less what their connected calendars already hold, with buffers and notice.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `worker` | [Worker](/business/nouns/worker) | Yes | Who is booked: a Human, or an Agent that takes calls. |
| `hours` | `json` | Yes | Open hours by weekday, in its time zone. |
| `timezone` | `string` | Yes | An IANA time zone. |
| `calendars` | `string[]` | No | Connected calendars whose busy times it subtracts. |
| `buffer` | `integer` | No | Minutes kept free before and after each Meeting. |
| `notice` | `integer` | No | The fewest hours ahead a Meeting can be booked. |

## Object
```json
{
  "$id": "https://api.sb/leaseline.app/availabilities/availability_8Zj0a7vvRl",
  "$type": "Availability",
  "worker": "worker_whZFpOKWIV",
  "hours": {
    "mon": [
      "09:00-12:00"
    ],
    "thu": [
      "13:00-17:00"
    ]
  },
  "timezone": "America/Chicago",
  "calendars": [
    "Example calendars"
  ],
  "buffer": 10,
  "notice": 12
}
```

## Relationships
- <a id="rel-meeting-types"></a>An Availability **has** many [Meeting Types](/business/nouns/meeting-type): each [Meeting Type](/business/nouns/meeting-type) books into one Availability, and an Availability serves many Meeting Types. `meetingTypes`, inverse [`booksInto`](/business/nouns/meeting-type#rel-books-into).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Availability.set](/business/nouns/availability/set) | Set records the weekly hours a Worker can be booked in and the calendars whose busy times it subtracts. | [Customer Lead](/agents/customer/customer-lead) | [`Availability.set`](/business/events/Availability.set) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Availability.create](/business/nouns/availability/create) | Creates an Availability. Inherited from [Noun](/business/nouns/noun). | None. | `Availability.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Availability.get](/business/nouns/availability/get) | Returns one Availability by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Availability.list](/business/nouns/availability/list) | Returns Availabilities, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Availability.update](/business/nouns/availability/update) | Changes the given properties of an Availability. Inherited from [Noun](/business/nouns/noun). | None. | `Availability.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Availability.delete](/business/nouns/availability/delete) | Deletes an Availability: a soft delete that keeps its history, undone by `Thing.restore`. Inherited from [Noun](/business/nouns/noun). | None. | `Availability.deleted` | Two-way: `try`, `send`, `do` |

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Availability.create` | Yes | Yes | Yes | No |
| `Availability.get` | Yes | Yes | Yes | Yes |
| `Availability.list` | Yes | Yes | Yes | Yes |
| `Availability.update` | Yes | Yes | Yes | No |
| `Availability.delete` | Yes | Yes | Yes | No |
| `Availability.set` | Yes | Yes | Yes | No |

## Call it
In code: [API](/code/api/availability) · [SDK](/code/sdk/availability) · [CLI](/code/cli/availability) · [MCP](/code/mcp/availability).

**Ask**

```text
Set the latest availability with a worker.
```

**API**

```bash
curl -X POST https://api.sb/leaseline.app/availabilities/set \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"worker":"worker_whZFpOKWIV","hours":{"tue":["09:00-12:00"],"thu":["13:00-17:00"]},"timezone":"America/Chicago"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "availability": {
    "$id": "https://api.sb/leaseline.app/availabilities/availability_8Zj0a7vvRl",
    "$type": "Availability",
    "worker": "worker_whZFpOKWIV",
    "hours": {
      "mon": [
        "09:00-12:00"
      ],
      "thu": [
        "13:00-17:00"
      ]
    },
    "timezone": "America/Chicago"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Availability.set",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

**SDK**

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

const availability = await $.Availability.set({ worker: 'worker_whZFpOKWIV', hours: { tue: ['09:00-12:00'], thu: ['13:00-17:00'] }, timezone: 'America/Chicago' })
```

**CLI**

```bash
npx startup-builder do Availability.set --json '{"worker":"worker_whZFpOKWIV","hours":{"tue":["09:00-12:00"],"thu":["13:00-17:00"]},"timezone":"America/Chicago"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Availability.set({ worker: 'worker_whZFpOKWIV', hours: { tue: ['09:00-12:00'], thu: ['13:00-17:00'] }, timezone: 'America/Chicago' })"
  }
}
```

## Works with
| With | Links |
| --- | --- |
| Roles | [Customer Lead](/agents/customer/customer-lead) |
| Systems | [Scheduling](/systems/scheduling) |
| Guides | [Give me a booking link](/systems/sales/give-me-a-booking-link) |

## Example
Dana Okafor keeps two mornings a week open for calls, in `America/Chicago`. Her Availability subtracts whatever her connected calendar already holds and keeps 10 minutes free around each [Meeting](/business/nouns/meeting). It refuses a booking less than 12 hours ahead.