API reference

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

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

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

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

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

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

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

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

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)

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

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

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

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

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

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)

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 '{}'

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

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

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

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

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)

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

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)

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

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)

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

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)

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

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. All resources: API reference.