Create a project
POST /api/v1/projects
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.
| Name | Type | Description |
|---|---|---|
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"}'