Contents

API reference / Projects

Create a project

POST /api/v1/projects

create_project Write MCP tool

Creates a project with 'My brand' and 'Competitors' keyword groups and the default categories. Pass keywords (the brand's names, domain and handles), competitors and topics (category phrases like “qr code generator”) to start searching right away.

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

Request body

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

NameTypeDescription
name required string
1–80 characters
Display name, e.g. the brand.
mode string mentions: track what people say about you (the only mode).
One of: mentions
description string
up to 1000 characters
What the brand is, in a sentence or two. The AI uses it to tell real mentions from namesakes.
audience string
up to 1000 characters
Optional: who the brand is for, in a sentence.
color string Hex colour.
icon string An emoji or short label.
sources array of string Sources to search. Omit for every source available.
One of: reddit linkedin x hn instagram github stackoverflow devto bluesky news youtube tiktok threads facebook appstore feeds jobs pages
window_days number
0.5–30
Lookback per scan, in days.
backfill_days number
1–730
Lookback for the first scan.
scan_every string Scan cadence, e.g. 24h, 6h, 1h. Omit for the workspace default.
timezone string IANA timezone, e.g. America/New_York.
paused boolean
settings object source_every {platform: "7d"} (search that platform only that often; 6h to 90d, the project's own cadence still applies to the rest), handles {platform: [..]}, team [..], domains [..], ambiguous {anchors, namesakes}, operatesIn (text, up to 200 characters: where the brand does business, e.g. "San Francisco Bay Area, United States"; a post about a same-named business elsewhere is ruled out), autoRuleOut (boolean, default on: posts the AI reviewer and the ranking model both read as noise move to Ruled out by themselves, with Restore), hashtags [..]; reply voice for drafts: replyStyle (text), cautions [claims never to make], useWords [..], avoidWords [..], replyExamples [up to 3 replies they liked], brandGuide (a pasted style guide, up to 6000 characters); conquest mode, off by default (auto-reply and drafts join conversations about competitors and the category problem, and challenge them with one attack point): conquest (boolean), attackPoints (text, up to 5000 characters, one block per incumbent: what they do well, the gaps we exploit, our proof for each gap, optionally a 'never say' line; replies may only claim what the fact sheet, the description and these points say; anything that isn't text is dropped), conquestPerDay (whole number 1 to 100, default 10: the most conquest replies a day, posted or waiting for approval); posts to ignore: excludeAuthors [..], excludeCommunities [subreddits and other places], onlyCommunities [subreddits; Reddit only], excludeDomains [..]; languages [two-letter codes, the default for keywords with none]; appStoreApps [App Store links or app ids, optionally "id:country"; their reviews are collected when the appstore source is on].
public boolean Publish a read-only public dashboard.
public_slug string URL slug for the public dashboard.
public_description string
up to 500 characters
Shown on the public dashboard.
public_website string Link shown on the public dashboard.
keywords array of string Create project: keywords to start with (added to the 'My brand' group).
competitors array of string Create project: competitor names to start with (added to the 'Competitors' group).
topics array of string Create project: category phrases to watch, like “qr code generator” (added to a 'Topics' group, not to the brand).

Example

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