# API: AI fields

| Method | Path | What it does | Scope |
|---|---|---|---|
| POST | `/v1/ai/fill` | Fill one AI field of one record now. The value applies with its source and reason when the model is confident enough and no person set the field; otherwise it's a suggestion. | `records:write` |
| GET | `/v1/capture-batches` | Capture batches, newest first | `records:read` |
| POST | `/v1/capture-batches` | Fill captured fields over existing records from their conversation history (owner; budget-checked; a report per record) | `settings:write` |
| GET | `/v1/capture-batches/:id` | One capture batch: progress, cost, and the report (record, field, outcome) | `records:read` |
| POST | `/v1/capture-batches/:id/cancel` | Stop a capture batch (records done keep their values) | `settings:write` |
| POST | `/v1/capture-batches/estimate` | Preview a capture batch: records in scope (the first ten), fields, model and estimated cost | `records:read` |
| GET | `/v1/field-suggestions` | Values the AI proposed but didn't apply (low confidence, or a person set the field), for a record | `records:read` |
| POST | `/v1/field-suggestions/:id/accept` | Apply a suggested value as your own change (its source and reason stay with it) | `records:write` |
| POST | `/v1/field-suggestions/:id/dismiss` | Dismiss a suggested value | `records:write` |
| GET | `/v1/fields/:id/backfill-estimate` | Before filling an AI field across existing records: how many records and the estimated model cost | `records:read` |
| POST | `/v1/objects/:object/fields/generate` | Describe a field in words; the model proposes its name, type, options and fill instructions. Nothing is created: review it, then POST …/fields with ai. | `records:write` |
| GET | `/v1/settings/capture` | Built-in fields filled from emails, meetings and calls as they land (AI fields have their own setting) | `records:read` |
| PUT | `/v1/settings/capture` | Choose which built-in fields fill from conversations (owner). Empty instructions use the default. | `settings:write` |
| GET | `/v1/settings/capture-retro` | Retro capture rules: re-run capture over a record's conversation history when it's created or changes | `records:read` |
| PUT | `/v1/settings/capture-retro` | Set the retro capture rules (owner) | `settings:write` |

## Examples

### POST /v1/ai/fill

Fill one AI field of one record now. The value applies with its source and reason when the model is confident enough and no person set the field; otherwise it's a suggestion.

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

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

Capture batches, newest first

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

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

### POST /v1/capture-batches

Fill captured fields over existing records from their conversation history (owner; budget-checked; a report per record)

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

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

One capture batch: progress, cost, and the report (record, field, outcome)

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

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

### POST /v1/capture-batches/$ID/cancel

Stop a capture batch (records done keep their values)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/capture-batches/${id}/cancel`, {
  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/capture-batches/estimate

Preview a capture batch: records in scope (the first ten), fields, model and estimated cost

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

```js
const res = await fetch(`https://api.closefinch.com/v1/capture-batches/estimate`, {
  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/field-suggestions

Values the AI proposed but didn't apply (low confidence, or a person set the field), for a record

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

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

### POST /v1/field-suggestions/$ID/accept

Apply a suggested value as your own change (its source and reason stay with it)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/field-suggestions/${id}/accept`, {
  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/field-suggestions/$ID/dismiss

Dismiss a suggested value

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

```js
const res = await fetch(`https://api.closefinch.com/v1/field-suggestions/${id}/dismiss`, {
  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/fields/$ID/backfill-estimate

Before filling an AI field across existing records: how many records and the estimated model cost

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

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

### POST /v1/objects/$OBJECT/fields/generate

Describe a field in words; the model proposes its name, type, options and fill instructions. Nothing is created: review it, then POST …/fields with ai.

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

```js
const res = await fetch(`https://api.closefinch.com/v1/objects/${object}/fields/generate`, {
  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/settings/capture

Built-in fields filled from emails, meetings and calls as they land (AI fields have their own setting)

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

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

### PUT /v1/settings/capture

Choose which built-in fields fill from conversations (owner). Empty instructions use the default.

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

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

Retro capture rules: re-run capture over a record's conversation history when it's created or changes

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

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

### PUT /v1/settings/capture-retro

Set the retro capture rules (owner)

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

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