# Handle

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

> A Handle is an account or name a Startup or Brand holds on an outside platform, bound to an Integration credential.

A Handle is an account or name a [Startup](/business/nouns/startup) or [Brand](/business/nouns/brand) holds on an outside platform, bound to an [Integration](/business/nouns/integration) credential.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `venue` | `string` | Yes | The venue it lives on, by id. |
| `name` | `string` | Yes | The name as the platform shows it, such as `@example`. |
| `shared` | `boolean` | No | True for a Studio account shared across sibling Startups; every Post names the Startup it speaks for. |
| `agent` | `boolean` | No | True when an Agent runs it; its bio says so. |
| `integration` | [Integration](/business/nouns/integration) | No | The Integration credential it publishes through. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/handles/handle_1",
  "$type": "Handle",
  "venue": "Example venue",
  "name": "TutorLoop",
  "shared": true,
  "agent": true,
  "integration": "integration_1"
}
```

## Relationships
- <a id="rel-publishes"></a>A Handle **publishes** many [Posts](/business/nouns/post): every [Post](/business/nouns/post) goes out from one Handle, so its reach and replies count toward that Handle. `publishes`, inverse [`handle`](/business/nouns/post#rel-handle).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Handle.connect](/business/nouns/handle/connect) | Connect binds a Handle to the Integration credential it publishes through, once the platform confirms the account. | [Content Lead](/agents/marketing/content-lead) | [`Handle.connected`](/business/events/Handle.connected) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Handle.create](/business/nouns/handle/create) | Creates a Handle. Inherited from [Noun](/business/nouns/noun). | None. | `Handle.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Handle.get](/business/nouns/handle/get) | Returns one Handle by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Handle.list](/business/nouns/handle/list) | Returns Handles, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Handle.update](/business/nouns/handle/update) | Changes the given properties of a Handle. Inherited from [Noun](/business/nouns/noun). | None. | `Handle.updated` | 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` |
| --- | --- | --- | --- | --- |
| `Handle.create` | Yes | Yes | Yes | No |
| `Handle.get` | Yes | Yes | Yes | Yes |
| `Handle.list` | Yes | Yes | Yes | Yes |
| `Handle.update` | Yes | Yes | Yes | No |
| `Handle.connect` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Connect the latest handle with an integration.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/handles/handle_1/connect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration":"integration_1"}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "handle": {
    "$id": "https://api.sb/tutorloop.com/handles/handle_1",
    "$type": "Handle",
    "venue": "Example venue",
    "name": "TutorLoop"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "Handle.connect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

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

const handle = await $.Handle.connect({ handle: 'handle_1', integration: 'integration_1' })
```

**CLI**

```bash
npx startup-builder do Handle.connect --json '{"handle":"handle_1","integration":"integration_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Handle.connect({ handle: 'handle_1', integration: 'integration_1' })"
  }
}
```

## Example
A recipe app holds the Handle `@weeknightplates` on two social venues, both bound to one [Integration](/business/nouns/integration). An [Agent](/business/nouns/agent) runs them, and each bio says so.