# API: Voice

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/voice/brand` | Your company's voice (accepted and newly built), example snippets with their sources, and its knowledge-base proposal | `knowledge:read` |
| PUT | `/v1/voice/brand` | Edit the company's voice (owners, from the app): saved to the KB voice section as a new version (web app only) | `settings:write` |
| POST | `/v1/voice/brand/rebuild` | Learn the company's voice from your site, the team's org-visible emails and calls, and playbooks (owner): a proposal for the KB voice section | `settings:write` |
| GET | `/v1/voice/me` | Your own voice, learned only from your own sent emails (only you can see it) | `knowledge:read` |
| PUT | `/v1/voice/me` | Edit your own voice | `knowledge:read` |
| POST | `/v1/voice/me/rebuild` | Learn your own voice again from your sent emails and your ratings | `knowledge:read` |
| GET | `/v1/voice/ratings` | Your ratings of drafts and edits, and the company-voice ratings everyone shares | `knowledge:read` |
| POST | `/v1/voice/ratings` | Rate a draft or your edit of it (thumbs up or down, with a note): the next rebuild of that voice uses it | `knowledge:read` |
| POST | `/v1/voice/score` | Score a draft 0–100 against the company's voice and your own, with specific issues | `knowledge:read` |

## Examples

### GET /v1/voice/brand

Your company's voice (accepted and newly built), example snippets with their sources, and its knowledge-base proposal

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

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

### POST /v1/voice/brand/rebuild

Learn the company's voice from your site, the team's org-visible emails and calls, and playbooks (owner): a proposal for the KB voice section

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

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

Your own voice, learned only from your own sent emails (only you can see it)

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

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

### PUT /v1/voice/me

Edit your own voice

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

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

### POST /v1/voice/me/rebuild

Learn your own voice again from your sent emails and your ratings

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

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

Your ratings of drafts and edits, and the company-voice ratings everyone shares

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

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

### POST /v1/voice/ratings

Rate a draft or your edit of it (thumbs up or down, with a note): the next rebuild of that voice uses it

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

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

Score a draft 0–100 against the company's voice and your own, with specific issues

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

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