# API: Desktop

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/desk/items` | The queue: conversations the AI handed to people (calls, website chats, text threads, escalated emails), offered to you first, then waiting, then with others. Only what you may see in each channel | `calls:read` |
| GET | `/v1/desk/items/:id` | One conversation: why the AI handed it off, what it collected, its summary, the conversation so far, the 360° panel (contact, account, deals, history across channels, consent and do-not-contact) and a suggested next action with its sources | `messages:read` |
| POST | `/v1/desk/items/:id/accept` | Take the conversation (a chat or text thread: the AI stops answering it; an email: it's assigned to you). A call is taken on your phone (web app only) | `calls:write` |
| POST | `/v1/desk/items/:id/hand-back` | Give the conversation back to the AI agent (a chat's visitor is told; a call gets a new voice session, which says the disclosure first) (web app only) | `messages:send` |
| POST | `/v1/desk/items/:id/pass` | Pass on what's offered to you: it goes to the next available person (web app only) | `calls:write` |
| POST | `/v1/desk/items/:id/transfer` | Hand the conversation to a teammate with a note. A call rings their own confirmed phone with the context and moves on 1; you stay on until they take it (web app only) | `messages:send` |
| GET | `/v1/desk/people` | Everyone's presence and how many conversations they have (for handing one on) | `calls:read` |
| PUT | `/v1/desk/presence` | Your presence: available (conversations are offered to you, up to your capacity), busy or away (nothing is offered, and transfers skip you) | `calls:write` |
| GET | `/v1/desk/settings` | Desktop settings: the SLA per channel, how long an offer to one person stands, sales-floor wins in Slack, owners' live listen and the monitoring notice | `calls:read` |
| PUT | `/v1/desk/settings` | Change the desktop settings (owner) (web app only) | `settings:write` |

## Examples

### GET /v1/desk/items

The queue: conversations the AI handed to people (calls, website chats, text threads, escalated emails), offered to you first, then waiting, then with others. Only what you may see in each channel

```bash
curl -s "https://api.closefinch.com/v1/desk/items" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/desk/items`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/desk/items/$ID

One conversation: why the AI handed it off, what it collected, its summary, the conversation so far, the 360° panel (contact, account, deals, history across channels, consent and do-not-contact) and a suggested next action with its sources

```bash
curl -s "https://api.closefinch.com/v1/desk/items/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/desk/items/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/desk/people

Everyone's presence and how many conversations they have (for handing one on)

```bash
curl -s "https://api.closefinch.com/v1/desk/people" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/desk/people`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/desk/presence

Your presence: available (conversations are offered to you, up to your capacity), busy or away (nothing is offered, and transfers skip you)

```bash
curl -s -X PUT "https://api.closefinch.com/v1/desk/presence" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/desk/presence`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/desk/settings

Desktop settings: the SLA per channel, how long an offer to one person stands, sales-floor wins in Slack, owners' live listen and the monitoring notice

```bash
curl -s "https://api.closefinch.com/v1/desk/settings" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/desk/settings`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).