# API: Interview synthesis

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/interview-syntheses` | Discovery-interview syntheses | `knowledge:read` |
| POST | `/v1/interview-syntheses` | Synthesize discovery interviews (activity ids, or a tag, date range and accounts) in the background, up to 20 interviews a run; poll it until done | `knowledge:write` |
| GET | `/v1/interview-syntheses/:id` | A synthesis: themes by kind ranked by interviews (n of N), single mentions flagged, quotes with speaker, interview and time | `knowledge:read` |
| POST | `/v1/interview-syntheses/:id/kb-proposal` | Offer the synthesis to the knowledge base's icp or positioning section (a person accepts it) | `knowledge:write` |
| POST | `/v1/interview-syntheses/:id/run` | Re-run in the background: add interviews the filter now picks (and any ids given) and rebuild the themes (refused while a run is queued or running) | `knowledge:write` |

## Examples

### GET /v1/interview-syntheses

Discovery-interview syntheses

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

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

### POST /v1/interview-syntheses

Synthesize discovery interviews (activity ids, or a tag, date range and accounts) in the background, up to 20 interviews a run; poll it until done

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

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

A synthesis: themes by kind ranked by interviews (n of N), single mentions flagged, quotes with speaker, interview and time

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

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

### POST /v1/interview-syntheses/$ID/kb-proposal

Offer the synthesis to the knowledge base's icp or positioning section (a person accepts it)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/interview-syntheses/${id}/kb-proposal`, {
  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/interview-syntheses/$ID/run

Re-run in the background: add interviews the filter now picks (and any ids given) and rebuild the themes (refused while a run is queued or running)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/interview-syntheses/${id}/run`, {
  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).