# Gathering

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

> A Gathering is a scheduled session many people attend at once, such as a webinar, a workshop, or a launch call, hosted by a Startup.

A Gathering is a scheduled session many people attend at once, such as a webinar, a workshop, or a launch call, hosted by a [Startup](/business/nouns/startup).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Yes | What the Gathering is called on its Page and invitations. |
| `at` | `datetime` | Yes | When it starts. |
| `capacity` | `integer` | No | The most Registrations it admits before new ones join the waitlist. |
| `recording` | `url` | No | Where the replay lives once it ends. |

## Object
```json
{
  "$id": "https://api.sb/shiftnote.app/gatherings/gathering_1",
  "$type": "Gathering",
  "title": "Clinic schedule",
  "at": "2026-10-22T12:00:00Z",
  "capacity": 1,
  "recording": "https://shiftnote.app"
}
```

## Relationships
- <a id="rel-admits"></a>A Gathering **admits** many [Registrations](/business/nouns/registration): a Gathering admits [Registrations](/business/nouns/registration) up to its capacity, then waitlists the rest. `admits`, inverse [`gathering`](/business/nouns/registration#rel-gathering).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Gathering.register](/business/nouns/gathering/register) | Register gives a Contact a place at a Gathering, or a waitlist place when the Gathering is full. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Gathering.registered`](/business/events/Gathering.registered) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Gathering.create](/business/nouns/gathering/create) | Creates a Gathering. Inherited from [Noun](/business/nouns/noun). | None. | `Gathering.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Gathering.get](/business/nouns/gathering/get) | Returns one Gathering by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Gathering.list](/business/nouns/gathering/list) | Returns Gatherings, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Gathering.update](/business/nouns/gathering/update) | Changes the given properties of a Gathering. Inherited from [Noun](/business/nouns/noun). | None. | `Gathering.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Gathering.delete](/business/nouns/gathering/delete) | Deletes a Gathering; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Gathering.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` |
| --- | --- | --- | --- | --- |
| `Gathering.create` | Yes | Yes | Yes | No |
| `Gathering.get` | Yes | Yes | Yes | Yes |
| `Gathering.list` | Yes | Yes | Yes | Yes |
| `Gathering.update` | Yes | Yes | Yes | No |
| `Gathering.delete` | Yes | Yes | Yes | No |
| `Gathering.register` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Register the latest gathering with a contact.
```

**API**

```bash
curl -X POST https://api.sb/kilnbakery.com/gatherings/gathering_1/register \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact":"contact_1"}'
```

```json
{
  "api": "https://api.sb/kilnbakery.com",
  "registration": {
    "$id": "https://api.sb/kilnbakery.com/registrations/registration_1",
    "$type": "Registration",
    "status": "invited"
  },
  "gathering": {
    "$id": "https://api.sb/kilnbakery.com/gatherings/gathering_1",
    "$type": "Gathering",
    "title": "Saturday sourdough",
    "at": "2026-10-22T12:00:00Z"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/action_1",
    "operation": "Gathering.register",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/action_1"
  }
}
```

**SDK**

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

const { registration, gathering } = await $.Gathering.register({ gathering: 'gathering_1', contact: 'contact_1' })
```

**CLI**

```bash
npx startup-builder do Gathering.register --json '{"gathering":"gathering_1","contact":"contact_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Gathering.register({ gathering: 'gathering_1', contact: 'contact_1' })"
  }
}
```

## Example
A bookkeeping app hosts a 45-minute workshop on closing the month, with capacity for 300. The 301st [Registration](/business/nouns/registration) joins the waitlist, and the replay link goes to every registrant the next morning.