# API: Competitive intelligence

| Method | Path | What it does | Scope |
|---|---|---|---|
| POST | `/v1/battlecard-proposals/:id/approve` | Approve a battlecard edit (optionally with your changes): a new version, kept with its provenance (owners, from the app) (web app only) | `settings:write` |
| POST | `/v1/battlecard-proposals/:id/reject` | Reject a battlecard edit (web app only) | `settings:write` |
| GET | `/v1/competitor-refresh` | Whether a refresh is queued or running | `knowledge:read` |
| GET | `/v1/competitor-stats` | Win/loss per competitor: win rate, cycle length, loss reasons and segments, with sample sizes | `knowledge:read` |
| GET | `/v1/competitors` | Tracked competitors with their recent changes, mentions, open battlecard edits and win/loss | `knowledge:read` |
| POST | `/v1/competitors` | Track a competitor: name, aliases (as buyers say it) and its own domains | `knowledge:write` |
| DELETE | `/v1/competitors/:id` | Stop tracking a competitor (its history stays) | `knowledge:write` |
| GET | `/v1/competitors/:id` | One competitor: pages, change log, mentions, battlecard, proposed edits, versions and win/loss | `knowledge:read` |
| PATCH | `/v1/competitors/:id` | Change a competitor's name, aliases, domains or notes | `knowledge:write` |
| POST | `/v1/competitors/:id/battlecard/proposals` | Propose your own edit to a battlecard section (it's approved like any other) (web app only) | `knowledge:write` |
| POST | `/v1/competitors/:id/battlecard/propose` | Propose battlecard edits now from page changes and active-evaluation mentions not used yet (each waits for approval) | `knowledge:write` |
| GET | `/v1/competitors/:id/battlecard/versions/:version` | One approved battlecard version with its provenance | `knowledge:read` |
| POST | `/v1/competitors/:id/check` | Read the competitor's monitored pages now: a change is logged with its diff, and battlecard edits are proposed from it | `knowledge:write` |
| POST | `/v1/competitors/:id/pages` | Monitor a public page on the competitor's own domain (pricing, release notes…; no query strings) | `knowledge:write` |
| DELETE | `/v1/competitors/:id/pages/:page` | Stop monitoring a page (its change log stays until the competitor is removed) | `knowledge:write` |
| POST | `/v1/competitors/refresh` | The monthly pass in the background now: pages, mentions and battlecard proposals for every competitor (at most every 10 minutes; poll the list) | `knowledge:write` |
| POST | `/v1/competitors/scan-mentions` | Look for competitor mentions in the last N days of conversations, notes and emails (open deals' owners are told about new ones) | `knowledge:write` |

## Examples

### GET /v1/competitor-refresh

Whether a refresh is queued or running

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

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

### GET /v1/competitor-stats

Win/loss per competitor: win rate, cycle length, loss reasons and segments, with sample sizes

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

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

### GET /v1/competitors

Tracked competitors with their recent changes, mentions, open battlecard edits and win/loss

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

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

### POST /v1/competitors

Track a competitor: name, aliases (as buyers say it) and its own domains

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

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

### DELETE /v1/competitors/$ID

Stop tracking a competitor (its history stays)

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

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

### GET /v1/competitors/$ID

One competitor: pages, change log, mentions, battlecard, proposed edits, versions and win/loss

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

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

### PATCH /v1/competitors/$ID

Change a competitor's name, aliases, domains or notes

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

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

Propose battlecard edits now from page changes and active-evaluation mentions not used yet (each waits for approval)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/competitors/${id}/battlecard/propose`, {
  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/competitors/$ID/battlecard/versions/$VERSION

One approved battlecard version with its provenance

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

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

### POST /v1/competitors/$ID/check

Read the competitor's monitored pages now: a change is logged with its diff, and battlecard edits are proposed from it

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

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

Monitor a public page on the competitor's own domain (pricing, release notes…; no query strings)

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

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

### DELETE /v1/competitors/$ID/pages/$PAGE

Stop monitoring a page (its change log stays until the competitor is removed)

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/competitors/$ID/pages/$PAGE" \
  -H "Authorization: Bearer $RA_API_KEY"
```

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

### POST /v1/competitors/refresh

The monthly pass in the background now: pages, mentions and battlecard proposals for every competitor (at most every 10 minutes; poll the list)

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

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

Look for competitor mentions in the last N days of conversations, notes and emails (open deals' owners are told about new ones)

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

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