# Opening

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

> An Opening is a Startup’s computed need for a Human in a Role: its kind, its reason, and the Hypothesis a hire must prove.

An Opening is a [Startup](/business/nouns/startup)’s computed need for a [Human](/business/nouns/human) in a [Role](/business/nouns/role): its kind, its reason, and the [Hypothesis](/business/nouns/hypothesis) a hire must prove.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role the Human joins, by taking a share of it. |
| `kind` | `string` | Yes | One of `floor`, `contractor`, `employee`, or `cofounder`. |
| `reason` | `string` | Yes | One of `floor`, `credential`, `edge`, `relationship`, `capital`, `capacity`, or `distribution`. |
| `hypothesis` | [Hypothesis](/business/nouns/hypothesis) | Yes | The result a hire must beat the incumbent Agent on. |
| `skills` | list of [Skill](/business/nouns/skill) | No | The Skills required, each citing the Evidence that shows the gap. |
| `credentials` | list of [Credential](/business/nouns/credential) | No | The Credentials a Reserved Act in the Role requires. |
| `commitment` | `string` | No | Hours per week, from a few hours to full time. |
| `terms` | `url` | No | The published terms for this kind of Opening. |
| `listed` | `boolean` | No | True once the Opening is public; unlisted Openings reach only the talent pool. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/openings/opening_1",
  "$type": "Opening",
  "role": "role_1",
  "kind": "floor",
  "reason": "floor",
  "hypothesis": "hypothesis_1",
  "skills": [
    "skill_1"
  ],
  "credentials": [
    "credential_1"
  ],
  "commitment": "Example commitment",
  "terms": "https://quietcopy.com",
  "listed": true
}
```

## Relationships
- <a id="rel-candidates"></a>An Opening **has** many [Candidates](/business/nouns/candidate): [Candidates](/business/nouns/candidate) for an Opening are screened only on what its [Hypothesis](/business/nouns/hypothesis) still lacks. `candidates`, inverse [`appliesTo`](/business/nouns/candidate#rel-applies-to).
- <a id="rel-staffs"></a>An Opening **staffs** one [Role](/business/nouns/role): an Opening is a need for a [Human](/business/nouns/human) in one [Role](/business/nouns/role), taking a share of that Role’s work. `staffs`, inverse [`openings`](/business/nouns/role#rel-openings).
- <a id="rel-tests"></a>An Opening **tests** one [Hypothesis](/business/nouns/hypothesis): a hire into an Opening must prove its [Hypothesis](/business/nouns/hypothesis). `tests`, inverse [`testedByOpening`](/business/nouns/hypothesis#rel-tested-by-opening).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Opening.create](/business/nouns/opening/create) | Creates an Opening. Inherited from [Noun](/business/nouns/noun). | None. | `Opening.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Opening.get](/business/nouns/opening/get) | Returns one Opening by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Opening.list](/business/nouns/opening/list) | Returns Openings, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Opening.update](/business/nouns/opening/update) | Changes the given properties of an Opening. Inherited from [Noun](/business/nouns/noun). | None. | `Opening.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Opening.delete](/business/nouns/opening/delete) | Deletes an Opening; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Opening.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` |
| --- | --- | --- | --- | --- |
| `Opening.create` | Yes | Yes | Yes | No |
| `Opening.get` | Yes | Yes | Yes | Yes |
| `Opening.list` | Yes | Yes | Yes | Yes |
| `Opening.update` | Yes | Yes | Yes | No |
| `Opening.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add an opening to TutorLoop with a role and a hypothesis.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/openings \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"role_1","kind":"floor","reason":"floor","hypothesis":"hypothesis_1"}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "opening": {
    "$id": "https://api.sb/tutorloop.com/openings/opening_1",
    "$type": "Opening",
    "role": "role_1",
    "kind": "floor",
    "reason": "floor",
    "hypothesis": "hypothesis_1"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "Opening.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

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

const opening = await $.Opening.create({ role: 'role_1', kind: 'floor', reason: 'floor', hypothesis: 'hypothesis_1' })
```

**CLI**

```bash
npx startup-builder do Opening.create --json '{"role":"role_1","kind":"floor","reason":"floor","hypothesis":"hypothesis_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Opening.create({ role: 'role_1', kind: 'floor', reason: 'floor', hypothesis: 'hypothesis_1' })"
  }
}
```

## Example
A visa-petition Startup opens a `floor` Opening with reason `credential` in its [Legal Lead](/agents/legal/legal-lead) Role. It asks for a licensed attorney, four hours a week, to file what its [Agents](/business/nouns/agent) draft. It stays unlisted until the talent pool comes up empty.