# API: Conversations

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/conversations` | Your conversations (yours and ones you were added to), most recent first | `search:read` |
| POST | `/v1/conversations` | Start a conversation, optionally with its first question | `search:read` |
| GET | `/v1/conversations/:id` | A conversation with its messages. Answers show only claims whose every source you may see now. | `search:read` |
| PATCH | `/v1/conversations/:id` | Rename, archive or reopen a conversation (archive and reopen: its owner) | `search:read` |
| POST | `/v1/conversations/:id/handoff` | Hand the conversation to a teammate: they own it; you stay in it (web app only) | `search:read` |
| POST | `/v1/conversations/:id/messages` | Ask in the conversation (follow-ups see the earlier turns you may see) | `search:read` |
| POST | `/v1/conversations/:id/participants` | Add a teammate (they see only the claims whose sources they may see) (web app only) | `search:read` |
| DELETE | `/v1/conversations/:id/participants/:userId` | Leave a conversation, or (its owner) remove someone (web app only) | `search:read` |
| POST | `/v1/conversations/:id/runs` | Start one of your agents from the conversation; the run shows in the thread | `agents:write` |

## Examples

### GET /v1/conversations

Your conversations (yours and ones you were added to), most recent first

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

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

### POST /v1/conversations

Start a conversation, optionally with its first question

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

```js
const res = await fetch(`https://api.closefinch.com/v1/conversations`, {
  method: "POST",
  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/conversations/$ID

A conversation with its messages. Answers show only claims whose every source you may see now.

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

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

### PATCH /v1/conversations/$ID

Rename, archive or reopen a conversation (archive and reopen: its owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/conversations/${id}`, {
  method: "PATCH",
  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();
```

### POST /v1/conversations/$ID/messages

Ask in the conversation (follow-ups see the earlier turns you may see)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/conversations/${id}/messages`, {
  method: "POST",
  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();
```

### POST /v1/conversations/$ID/runs

Start one of your agents from the conversation; the run shows in the thread

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

```js
const res = await fetch(`https://api.closefinch.com/v1/conversations/${id}/runs`, {
  method: "POST",
  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();
```

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).