Contents

API reference / Competitors

Add a competitor

POST /api/v1/projects/{project}/competitors

create_competitor Write MCP tool

Tracks its name, domain and handles, and tags each post about it by what the author is doing (complaint, praise, alternative, pricing). Uses one keyword from the plan.

A full-access key (ss_sk_…), or an editor or owner signed in.

Parameters

NameTypeDescription
project required
path
string The project's id.

Request body

JSON, sent with Content-Type: application/json.

NameTypeDescription
phrases array of string
up to 3 items
Create only: search phrases that find people shopping around, like "Fernbill alternative". Each one is a keyword that keeps every post it finds (max 3).
name required string
2–60 characters
The competitor's name.
aliases array of string
up to 8 items
Other spellings of the name (max 8).
domain string Its website, e.g. fernbill.com. Posts that link to it count.
handles object {platform: [handles]}, e.g. {"x": ["fernbill"]}. Posts that tag them count.
feeds array of string
up to 5 items
Blog or changelog feed URLs (https). New items show in the feed.
pages array of string
up to 3 items
Pages to watch for changes, such as its pricing page and home page (https, up to 3). A price or headline change that holds across two checks shows in the feed with before and after.
jobs array of object
up to 3 items
Public job boards to watch for new roles.
jobs[].ats required string
One of: greenhouse lever ashby
jobs[].slug required string The company's board name on that system, e.g. fernbill.

Example

curl -X POST "https://sniffington.com/api/v1/projects/{project}/competitors" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme"}'