# API: Research

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/research` | Research briefs, newest first (by subject or kind) | `prospecting:read` |
| POST | `/v1/research` | Research an account, a person, or a question over accounts (runs in the background; a fresh brief for the same subject is reused) | `prospecting:write` |
| GET | `/v1/research-settings` | Web research settings and which providers are set up | `prospecting:read` |
| PUT | `/v1/research-settings` | Change web research settings (owner): on/off, default prompts, staleness, sites never read | `settings:write` |
| GET | `/v1/research-sources/:id` | A source a brief read (its text, to check a citation) | `prospecting:read` |
| GET | `/v1/research/:id` | One brief: plan, trace, labelled findings with citations, ranked rows (question briefs) | `prospecting:read` |
| POST | `/v1/research/:id/export` | Turn a question brief's ranked accounts into a static list (fit at or above min_fit, default 50) | `prospecting:write` |
| PUT | `/v1/research/:id/plan` | Approve a brief's plan (as is or edited): it runs next | `prospecting:write` |

## Examples

### GET /v1/research

Research briefs, newest first (by subject or kind)

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

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

### POST /v1/research

Research an account, a person, or a question over accounts (runs in the background; a fresh brief for the same subject is reused)

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

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

Web research settings and which providers are set up

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

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

### PUT /v1/research-settings

Change web research settings (owner): on/off, default prompts, staleness, sites never read

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

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

A source a brief read (its text, to check a citation)

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

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

### GET /v1/research/$ID

One brief: plan, trace, labelled findings with citations, ranked rows (question briefs)

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

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

### POST /v1/research/$ID/export

Turn a question brief's ranked accounts into a static list (fit at or above min_fit, default 50)

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

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

### PUT /v1/research/$ID/plan

Approve a brief's plan (as is or edited): it runs next

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

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

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