{"openapi":"3.1.0","info":{"title":"social-scout API","version":"1.0.0","description":"Brand and keyword mention monitoring. Every operation here is also an MCP tool with the same name."},"servers":[{"url":"https://sniffington.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key (ss_sk_… full, ss_ro_… read-only) or an OAuth access token."}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"paths":{"/api/v1/projects":{"get":{"operationId":"list_projects","tags":["Projects"],"summary":"List projects","description":"Every project (a brand or topic you monitor) in the workspace.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_project","tags":["Projects"],"summary":"Create a project","description":"Creates a project with 'My brand' and 'Competitors' keyword groups and the default categories. Pass keywords/competitors to start searching right away.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name, e.g. the brand.","minLength":1,"maxLength":80},"mode":{"type":"string","enum":["mentions","leads"],"description":"mentions: track what people say about you. leads: find people describing a problem you solve."},"description":{"type":"string","description":"What the brand is, in a sentence or two. The AI uses it to tell real mentions from namesakes.","maxLength":1000},"audience":{"type":"string","description":"Leads mode: who counts as a lead.","maxLength":1000},"color":{"type":"string","description":"Hex colour."},"icon":{"type":"string","description":"An emoji or short label."},"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Sources to search. Omit for every source available."},"window_days":{"type":"number","minimum":0.5,"maximum":30,"description":"Lookback per scan, in days."},"backfill_days":{"type":"number","minimum":1,"maximum":730,"description":"Lookback for the first scan."},"scan_every":{"type":"string","description":"Scan cadence, e.g. 24h, 6h, 1h. Omit for the workspace default.","pattern":"^\\s*\\d+(\\.\\d+)?\\s*[smhdSMHD]\\s*$","x-pattern-hint":"must be a duration with a unit, like 30m, 6h or 1d"},"timezone":{"type":"string","description":"IANA timezone, e.g. America/New_York."},"paused":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"handles {platform: [..]}, team [..], domains [..], ambiguous {anchors, namesakes}, hashtags [..]."},"public":{"type":"boolean","description":"Publish a read-only public dashboard."},"public_slug":{"type":"string","description":"URL slug for the public dashboard."},"public_description":{"type":"string","description":"Shown on the public dashboard.","maxLength":500},"public_website":{"type":"string","description":"Link shown on the public dashboard."},"keywords":{"type":"array","items":{"type":"string"},"description":"Create project: keywords to start with (added to the 'My brand' group)."},"competitors":{"type":"array","items":{"type":"string"},"description":"Create project: competitor names to start with (added to the 'Competitors' group)."}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/projects/{project}":{"get":{"operationId":"get_project","tags":["Projects"],"summary":"Get a project","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_project","tags":["Projects"],"summary":"Update a project","description":"Change settings, sources, cadence, pause/resume, or publish a public dashboard (public: true).","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name, e.g. the brand.","minLength":1,"maxLength":80},"mode":{"type":"string","enum":["mentions","leads"],"description":"mentions: track what people say about you. leads: find people describing a problem you solve."},"description":{"type":"string","description":"What the brand is, in a sentence or two. The AI uses it to tell real mentions from namesakes.","maxLength":1000},"audience":{"type":"string","description":"Leads mode: who counts as a lead.","maxLength":1000},"color":{"type":"string","description":"Hex colour."},"icon":{"type":"string","description":"An emoji or short label."},"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Sources to search. Omit for every source available."},"window_days":{"type":"number","minimum":0.5,"maximum":30,"description":"Lookback per scan, in days."},"backfill_days":{"type":"number","minimum":1,"maximum":730,"description":"Lookback for the first scan."},"scan_every":{"type":"string","description":"Scan cadence, e.g. 24h, 6h, 1h. Omit for the workspace default.","pattern":"^\\s*\\d+(\\.\\d+)?\\s*[smhdSMHD]\\s*$","x-pattern-hint":"must be a duration with a unit, like 30m, 6h or 1d"},"timezone":{"type":"string","description":"IANA timezone, e.g. America/New_York."},"paused":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"handles {platform: [..]}, team [..], domains [..], ambiguous {anchors, namesakes}, hashtags [..]."},"public":{"type":"boolean","description":"Publish a read-only public dashboard."},"public_slug":{"type":"string","description":"URL slug for the public dashboard."},"public_description":{"type":"string","description":"Shown on the public dashboard.","maxLength":500},"public_website":{"type":"string","description":"Link shown on the public dashboard."},"keywords":{"type":"array","items":{"type":"string"},"description":"Create project: keywords to start with (added to the 'My brand' group)."},"competitors":{"type":"array","items":{"type":"string"},"description":"Create project: competitor names to start with (added to the 'Competitors' group)."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_project","tags":["Projects"],"summary":"Delete a project","description":"Stops scanning and hides the project. Its mentions are kept privately unless purge=true.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"purge","in":"query","required":false,"description":"Also delete every mention and scan record.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/projects/{project}/scan":{"post":{"operationId":"scan_project","tags":["Projects"],"summary":"Scan a project now","description":"Queues an immediate scan. Results arrive as mentions (and mention.created webhooks).","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/projects/{project}/groups":{"get":{"operationId":"list_keyword_groups","tags":["Keywords"],"summary":"List keyword groups","description":"Every project has 'My brand' and 'Competitors'; add custom ones for products, people or topics.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_keyword_group","tags":["Keywords"],"summary":"Create a keyword group","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Group name.","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["brand","competitor","custom"]},"color":{"type":"string","description":"Hex colour."}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/groups/{group}":{"patch":{"operationId":"update_keyword_group","tags":["Keywords"],"summary":"Update a keyword group","parameters":[{"name":"group","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Group name.","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["brand","competitor","custom"]},"color":{"type":"string","description":"Hex colour."},"position":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_keyword_group","tags":["Keywords"],"summary":"Delete a keyword group","description":"Its keywords stay, ungrouped.","parameters":[{"name":"group","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/projects/{project}/keywords":{"get":{"operationId":"list_keywords","tags":["Keywords"],"summary":"List keywords","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"Only active (or only inactive) keywords.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_keyword","tags":["Keywords"],"summary":"Add a keyword","description":"Aliases catch other spellings, handles and domains; excluded terms skip posts that also contain them.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","description":"The keyword, 2–200 characters.","minLength":2,"maxLength":200},"aliases":{"type":"array","items":{"type":"string"},"description":"Other spellings, handles or domains that count as the same thing (max 10).","maxItems":10},"excluded":{"type":"array","items":{"type":"string"},"description":"Skip any post that also contains one of these (max 10).","maxItems":10},"case_sensitive":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Sources to search. Omit for every source available."},"group_id":{"type":["integer","null"],"description":"Keyword group; omit for 'My brand'."},"active":{"type":"boolean","description":"Inactive keywords keep their history but aren't searched."}},"required":["term"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/keywords/{keyword}":{"get":{"operationId":"get_keyword","tags":["Keywords"],"summary":"Get a keyword","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_keyword","tags":["Keywords"],"summary":"Update a keyword","description":"Set active:false to stop searching it while keeping its mentions.","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","description":"The keyword, 2–200 characters.","minLength":2,"maxLength":200},"aliases":{"type":"array","items":{"type":"string"},"description":"Other spellings, handles or domains that count as the same thing (max 10).","maxItems":10},"excluded":{"type":"array","items":{"type":"string"},"description":"Skip any post that also contains one of these (max 10).","maxItems":10},"case_sensitive":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Sources to search. Omit for every source available."},"group_id":{"type":["integer","null"],"description":"Keyword group; omit for 'My brand'."},"active":{"type":"boolean","description":"Inactive keywords keep their history but aren't searched."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_keyword","tags":["Keywords"],"summary":"Delete a keyword","description":"Mentions it found are kept.","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/projects/{project}/categories":{"get":{"operationId":"list_categories","tags":["Categories"],"summary":"List categories","description":"The AI files every relevant mention into one of these.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_category","tags":["Categories"],"summary":"Create a category","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Category name.","minLength":1,"maxLength":60},"description":{"type":"string","description":"What belongs here, in plain words – the AI files mentions by it.","maxLength":300},"icon":{"type":"string","description":"An emoji."},"color":{"type":"string","description":"Hex colour."},"position":{"type":"integer"}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/categories/{category}":{"patch":{"operationId":"update_category","tags":["Categories"],"summary":"Update a category","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Category name.","minLength":1,"maxLength":60},"description":{"type":"string","description":"What belongs here, in plain words – the AI files mentions by it.","maxLength":300},"icon":{"type":"string","description":"An emoji."},"color":{"type":"string","description":"Hex colour."},"position":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_category","tags":["Categories"],"summary":"Delete a category","description":"Mentions in it become uncategorised.","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/mentions":{"get":{"operationId":"list_mentions","tags":["Mentions"],"summary":"List mentions","description":"Filter, search and page through mentions. Cursor-paginated: pass next_cursor back as cursor.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"status","in":"query","required":false,"description":"Workflow status.","schema":{"type":"array","items":{"type":"string","enum":["open","done","follow_up"]}}},{"name":"relevance","in":"query","required":false,"description":"Urgency band (high ≥70, medium ≥40).","schema":{"type":"array","items":{"type":"string","enum":["high","medium","low"]}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"authors","in":"query","required":false,"description":"Exact author handles, e.g. @someone or u/someone.","schema":{"type":"array","items":{"type":"string"}}},{"name":"urgency_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"urgency_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_engagement","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"engagement","in":"query","required":false,"description":"Per-source minimum engagement, e.g. x:10,reddit:5.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"found_since","in":"query","required":false,"description":"Only mentions first collected at or after this ISO date/time or epoch ms, however old the post itself is.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Full-text search over text, author, place and the AI's summary.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}},{"name":"range","in":"query","required":false,"description":"A relative date window; since/until win when both are given.","schema":{"type":"string","enum":["today","7d","30d","90d","12m","all"]}},{"name":"view","in":"query","required":false,"description":"Apply a saved view's filters.","schema":{"type":"integer"}},{"name":"order","in":"query","required":false,"description":"found = most recently collected first.","schema":{"type":"string","enum":["newest","oldest","urgency","engagement","found"]}},{"name":"limit","in":"query","required":false,"description":"Page size (default 25, max 100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's next_cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data: Mention[], next_cursor, total }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/brief":{"get":{"operationId":"get_brief","tags":["Mentions"],"summary":"Today's brief","description":"What needs a person today: open mentions ranked by urgency, each with the AI's one-line reason, how many are open per project and how many arrived in the last 24 hours. Start here when asked what people are saying about a brand.","parameters":[{"name":"project","in":"query","required":false,"description":"Only this project.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many mentions to return (default 10).","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"{ data: { open, new_24h, projects: [{ id, name, open }], mentions: Mention[] } }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/mentions/bulk":{"post":{"operationId":"bulk_update_mentions","tags":["Mentions"],"summary":"Change the status of many mentions","description":"Sets the status of every mention matching the filters (the list_mentions query parameters), or of the given ids. Useful for clearing an old backlog, e.g. status=done with status filter open and until=90 days ago.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"status","in":"query","required":false,"description":"Workflow status.","schema":{"type":"array","items":{"type":"string","enum":["open","done","follow_up"]}}},{"name":"relevance","in":"query","required":false,"description":"Urgency band (high ≥70, medium ≥40).","schema":{"type":"array","items":{"type":"string","enum":["high","medium","low"]}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"authors","in":"query","required":false,"description":"Exact author handles, e.g. @someone or u/someone.","schema":{"type":"array","items":{"type":"string"}}},{"name":"urgency_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"urgency_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_engagement","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"engagement","in":"query","required":false,"description":"Per-source minimum engagement, e.g. x:10,reddit:5.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"found_since","in":"query","required":false,"description":"Only mentions first collected at or after this ISO date/time or epoch ms, however old the post itself is.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Full-text search over text, author, place and the AI's summary.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}},{"name":"range","in":"query","required":false,"description":"A relative date window; since/until win when both are given.","schema":{"type":"string","enum":["today","7d","30d","90d","12m","all"]}},{"name":"view","in":"query","required":false,"description":"Apply a saved view's filters.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","done","follow_up"],"description":"The new status."},"ids":{"type":"array","items":{"type":"string"},"description":"Only these mention ids (max 5000).","maxItems":5000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/mentions/{mention}":{"get":{"operationId":"get_mention","tags":["Mentions"],"summary":"Get a mention","parameters":[{"name":"mention","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_mention","tags":["Mentions"],"summary":"Update a mention","description":"Set status (open, done, follow_up), or correct the AI's category, sentiment, urgency or relevance.","parameters":[{"name":"mention","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","done","follow_up"]},"category_id":{"type":["integer","null"]},"sentiment":{"type":"string","enum":["positive","negative","neutral"]},"urgency":{"type":"integer","minimum":0,"maximum":100},"relevant":{"type":"boolean","description":"true restores a mention the AI filtered out."},"draft":{"type":"string","description":"Save a reply draft."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_mention","tags":["Mentions"],"summary":"Delete a mention","description":"Removes it from every view. It stays remembered so it's never collected again.","parameters":[{"name":"mention","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/mentions/{mention}/irrelevant":{"post":{"operationId":"mark_mention_irrelevant","tags":["Mentions"],"summary":"Mark a mention irrelevant","description":"Moves it out of the feed for good (it will never be re-collected). The reason teaches the AI what to skip next time.","parameters":[{"name":"mention","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why it isn't relevant, e.g. 'about the diarist, not the app'.","maxLength":500}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/mentions/{mention}/draft":{"post":{"operationId":"draft_reply","tags":["Mentions"],"summary":"Draft a reply","description":"Writes a short, help-first reply in the post's own register. Nothing is posted; you copy it.","parameters":[{"name":"mention","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/authors":{"get":{"operationId":"list_authors","tags":["Authors"],"summary":"List authors","description":"mode=all for autocomplete (with q), supporters for the most positive, critics for the most negative.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"status","in":"query","required":false,"description":"Workflow status.","schema":{"type":"array","items":{"type":"string","enum":["open","done","follow_up"]}}},{"name":"relevance","in":"query","required":false,"description":"Urgency band (high ≥70, medium ≥40).","schema":{"type":"array","items":{"type":"string","enum":["high","medium","low"]}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"authors","in":"query","required":false,"description":"Exact author handles, e.g. @someone or u/someone.","schema":{"type":"array","items":{"type":"string"}}},{"name":"urgency_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"urgency_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_engagement","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"engagement","in":"query","required":false,"description":"Per-source minimum engagement, e.g. x:10,reddit:5.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"found_since","in":"query","required":false,"description":"Only mentions first collected at or after this ISO date/time or epoch ms, however old the post itself is.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Full-text search over text, author, place and the AI's summary.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}},{"name":"range","in":"query","required":false,"description":"A relative date window; since/until win when both are given.","schema":{"type":"string","enum":["today","7d","30d","90d","12m","all"]}},{"name":"view","in":"query","required":false,"description":"Apply a saved view's filters.","schema":{"type":"integer"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["all","supporters","critics"]}},{"name":"limit","in":"query","required":false,"description":"Page size (default 25, max 100).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/analytics":{"get":{"operationId":"get_analytics","tags":["Analytics"],"summary":"Mention analytics","description":"Totals, mentions over time with the sentiment split, and the mix by source, category, keyword and group, plus the weekday × hour heatmap and top supporters and critics – one call.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/analytics/breakdown":{"get":{"operationId":"get_breakdown","tags":["Analytics"],"summary":"Break mentions down by one dimension","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}},{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["source","sentiment","status","category","keyword","group","place","author","project"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/analytics/volume":{"get":{"operationId":"get_volume","tags":["Analytics"],"summary":"Mentions per day by source, project, sentiment, category or group","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"sources","in":"query","required":false,"description":"Sources to search. Omit for every source available.","schema":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]}}},{"name":"groups","in":"query","required":false,"description":"Keyword group ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"keywords","in":"query","required":false,"description":"Keyword ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"categories","in":"query","required":false,"description":"Category ids.","schema":{"type":"array","items":{"type":"integer"}}},{"name":"sentiment","in":"query","required":false,"description":"Sentiment.","schema":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]}}},{"name":"since","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"ISO date/time or epoch ms.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"relevant (default): real mentions. irrelevant: filtered out as namesakes or noise.","schema":{"type":"string","enum":["relevant","irrelevant","all"]}},{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["source","watcher","sentiment","category","group"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/analytics/sql":{"post":{"operationId":"query_sql","tags":["Analytics"],"summary":"Run a read-only SQL query","description":"SELECT/WITH over the workspace's tables (mentions, projects, keywords, categories, keyword_groups, runs). Capped at 1,000 rows.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sql"],"properties":{"sql":{"type":"string","description":"A single SELECT or WITH statement."},"limit":{"type":"integer","minimum":1,"maximum":1000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/views":{"get":{"operationId":"list_views","tags":["Views"],"summary":"List saved views","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_view","tags":["Views"],"summary":"Save a view","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"View name.","minLength":1,"maxLength":60},"project_id":{"type":["string","null"]},"filters":{"type":"object","additionalProperties":true,"description":"Any list_mentions query parameters."}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/views/{view}":{"patch":{"operationId":"update_view","tags":["Views"],"summary":"Update a saved view","parameters":[{"name":"view","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"View name.","minLength":1,"maxLength":60},"project_id":{"type":["string","null"]},"filters":{"type":"object","additionalProperties":true,"description":"Any list_mentions query parameters."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_view","tags":["Views"],"summary":"Delete a saved view","parameters":[{"name":"view","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/runs":{"get":{"operationId":"list_runs","tags":["Scans"],"summary":"Recent scans","description":"Per project: what each source returned, how much was new, and any source errors.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (default 25, max 100).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/webhooks":{"get":{"operationId":"list_webhooks","tags":["Webhooks"],"summary":"List webhooks","description":"Every webhook endpoint in the workspace. Secrets are never returned here; secret_hint is the last 4 characters.","responses":{"200":{"description":"Webhook[]","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_webhook","tags":["Webhooks"],"summary":"Create a webhook","description":"Events are POSTed as JSON and signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature headers). The signing secret is in this response only, so store it now.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Where to POST events. Must be a public https:// URL.","minLength":8,"maxLength":2048},"events":{"type":"array","items":{"type":"string"},"description":"Event types to send, or [\"*\"] for all (the default). GET /v1/webhook-events lists them.","maxItems":50},"project_id":{"type":["string","null"],"description":"Only events from this project; null for the whole workspace."},"description":{"type":["string","null"],"maxLength":500,"description":"A note for yourself, e.g. what receives it."}},"required":["url"]}}}},"responses":{"201":{"description":"Webhook & { secret }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/webhooks/{webhook}":{"get":{"operationId":"get_webhook","tags":["Webhooks"],"summary":"Get a webhook","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_webhook","tags":["Webhooks"],"summary":"Update a webhook","description":"Turning a webhook back on (enabled: true) clears its failure count and the reason it was turned off.","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Where to POST events. Must be a public https:// URL.","minLength":8,"maxLength":2048},"events":{"type":"array","items":{"type":"string"},"description":"Event types to send, or [\"*\"] for all (the default). GET /v1/webhook-events lists them.","maxItems":50},"project_id":{"type":["string","null"],"description":"Only events from this project; null for the whole workspace."},"description":{"type":["string","null"],"maxLength":500,"description":"A note for yourself, e.g. what receives it."},"enabled":{"type":"boolean","description":"false stops deliveries; true resumes them."}}}}}},"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_webhook","tags":["Webhooks"],"summary":"Delete a webhook","description":"Stops deliveries and deletes its delivery log.","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/webhooks/{webhook}/rotate-secret":{"post":{"operationId":"rotate_webhook_secret","tags":["Webhooks"],"summary":"Rotate a webhook's signing secret","description":"The old secret stops working immediately. The new one is in this response only.","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ id, secret }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/webhooks/{webhook}/test":{"post":{"operationId":"test_webhook","tags":["Webhooks"],"summary":"Send a test event","description":"Queues a signed \"test.ping\" event to this endpoint right away, even if the webhook is turned off. Check list_webhook_deliveries for the result.","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"{ delivery_id }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/webhooks/{webhook}/deliveries":{"get":{"operationId":"list_webhook_deliveries","tags":["Webhooks"],"summary":"List a webhook's deliveries","description":"Newest first. Deliveries are kept for 30 days.","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (default 25, max 100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","minimum":0}},{"name":"status","in":"query","required":false,"description":"Only deliveries in this state.","schema":{"type":"string","enum":["pending","delivered","failed"]}}],"responses":{"200":{"description":"{ data: Delivery[], total }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/webhook-deliveries/{delivery}/replay":{"post":{"operationId":"replay_webhook_delivery","tags":["Webhooks"],"summary":"Replay a delivery","description":"Queues the same event again (same payload and webhook-id, so receivers can dedupe) as a new delivery.","parameters":[{"name":"delivery","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"{ delivery_id }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/webhook-events":{"get":{"operationId":"list_webhook_events","tags":["Webhooks"],"summary":"List webhook event types","description":"Every event type a webhook can subscribe to. test_webhook also sends a \"test.ping\" to any endpoint.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/workspace":{"get":{"operationId":"get_workspace","tags":["Workspace"],"summary":"The current workspace","description":"Name, plan and timezone of the workspace this credential belongs to.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_workspace","tags":["Workspace"],"summary":"Rename the workspace or change its timezone / default scan cadence","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name.","minLength":1,"maxLength":80},"timezone":{"type":"string","description":"IANA timezone."},"scan_every":{"type":"string","description":"Default scan cadence for projects that don't set one, e.g. 24h.","pattern":"^\\s*\\d+(\\.\\d+)?\\s*[smhdSMHD]\\s*$","x-pattern-hint":"must be a duration with a unit, like 30m, 6h or 1d"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/members":{"get":{"operationId":"list_members","tags":["Workspace"],"summary":"List members","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/members/{user}":{"patch":{"operationId":"update_member","tags":["Workspace"],"summary":"Change a member's role","parameters":[{"name":"user","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["owner","editor","viewer"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"},"delete":{"operationId":"remove_member","tags":["Workspace"],"summary":"Remove a member","parameters":[{"name":"user","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/invites":{"get":{"operationId":"list_invites","tags":["Workspace"],"summary":"List invites","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"},"post":{"operationId":"create_invite","tags":["Workspace"],"summary":"Invite someone","description":"Returns an invite link, valid for 7 days. It's emailed too.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","role"],"properties":{"email":{"type":"string","description":"Their email."},"role":{"type":"string","enum":["owner","editor","viewer"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/invites/{invite}":{"delete":{"operationId":"revoke_invite","tags":["Workspace"],"summary":"Revoke an invite","parameters":[{"name":"invite","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/api-keys":{"get":{"operationId":"list_api_keys","tags":["API keys"],"summary":"List API keys","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"},"post":{"operationId":"create_api_key","tags":["API keys"],"summary":"Create an API key","description":"The key is shown once. Read-only keys can't change anything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"What it's for.","minLength":1,"maxLength":60},"scope":{"type":"string","enum":["full","read"]},"expires_in_days":{"type":"integer","minimum":1,"maximum":3650}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/api-keys/{key}":{"delete":{"operationId":"revoke_api_key","tags":["API keys"],"summary":"Revoke an API key","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/scans/status":{"get":{"operationId":"get_scan_status","tags":["Scans"],"summary":"Scan status","description":"What's scanning now, what's queued, and when each project is next due.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/scans":{"post":{"operationId":"scan_now","tags":["Scans"],"summary":"Scan every project now","responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/usage":{"get":{"operationId":"get_usage","tags":["Workspace"],"summary":"Usage this month","description":"Mentions collected and judged, metered source calls and LLM tokens, against the plan's limits.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"}},"/api/v1/oauth/connections":{"get":{"operationId":"list_oauth_connections","tags":["API keys"],"summary":"List connected apps","description":"Apps (Claude, ChatGPT, Codex and other MCP clients) that members connected over OAuth, with their access and when their sign-in lapses.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/oauth/connections/{client}":{"delete":{"operationId":"revoke_oauth_connection","tags":["API keys"],"summary":"Disconnect an app","description":"Revokes every token the app holds for this workspace. It has to be approved again to reconnect.","parameters":[{"name":"client","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"admin"}},"/api/v1/alerts":{"get":{"operationId":"list_alerts","tags":["Alerts"],"summary":"List alerts","description":"Digests and rule alerts. With project, that project's alerts plus the ones that cover every project.","parameters":[{"name":"project","in":"query","required":false,"description":"Project id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Alert[]","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"post":{"operationId":"create_alert","tags":["Alerts"],"summary":"Create an alert","description":"Email, Slack or Discord. Each workspace can send 30 alert emails and 200 Slack or Discord messages a day (self-hosted installs set the email cap with SCOUT_ALERT_EMAILS_PER_DAY).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["digest","rule"],"description":"digest: one message a day at `hour`. rule: a message the moment a matching mention arrives."},"name":{"type":"string","description":"Shown in the app and in each message.","minLength":1,"maxLength":80},"enabled":{"type":"boolean"},"project_id":{"type":["string","null"],"description":"The project to watch; null for every project."},"channel":{"type":"string","enum":["email","slack","discord"]},"target":{"type":"string","description":"email: an address. slack: a channel ID or #name. discord: a webhook URL (https://discord.com/api/webhooks/…).","maxLength":500},"hour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Digest: the local hour to send, 0–23."},"timezone":{"type":["string","null"],"description":"IANA timezone for `hour`, e.g. America/New_York. Defaults to the workspace's."},"filters":{"type":"object","description":"Only mentions matching every filter set here. Leave a filter out to match everything.","properties":{"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Only these sources."},"sentiment":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]},"description":"Only these sentiments."},"categories":{"type":"array","items":{"type":"integer"},"description":"Only these category ids."},"groups":{"type":"array","items":{"type":"integer"},"description":"Only these keyword group ids."},"keywords":{"type":"array","items":{"type":"integer"},"description":"Only these keyword ids."},"authors":{"type":"array","items":{"type":"string"},"description":"Only these authors: exact handles, any case, e.g. @someone or u/someone.","maxItems":50},"min_engagement":{"type":"integer","minimum":0,"description":"Only posts with at least this much engagement."}}},"min_urgency":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Only mentions at or above this urgency (0–100)."}},"required":["kind","name","channel","target"]}}}},"responses":{"201":{"description":"Alert","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/alerts/{alert}":{"get":{"operationId":"get_alert","tags":["Alerts"],"summary":"Get an alert","parameters":[{"name":"alert","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alert","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"read"},"patch":{"operationId":"update_alert","tags":["Alerts"],"summary":"Update an alert","description":"Send only what changes. filters replaces the whole filter set.","parameters":[{"name":"alert","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["digest","rule"],"description":"digest: one message a day at `hour`. rule: a message the moment a matching mention arrives."},"name":{"type":"string","description":"Shown in the app and in each message.","minLength":1,"maxLength":80},"enabled":{"type":"boolean"},"project_id":{"type":["string","null"],"description":"The project to watch; null for every project."},"channel":{"type":"string","enum":["email","slack","discord"]},"target":{"type":"string","description":"email: an address. slack: a channel ID or #name. discord: a webhook URL (https://discord.com/api/webhooks/…).","maxLength":500},"hour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Digest: the local hour to send, 0–23."},"timezone":{"type":["string","null"],"description":"IANA timezone for `hour`, e.g. America/New_York. Defaults to the workspace's."},"filters":{"type":"object","description":"Only mentions matching every filter set here. Leave a filter out to match everything.","properties":{"sources":{"type":"array","items":{"type":"string","enum":["reddit","linkedin","x","hn","instagram","github","stackoverflow","devto","bluesky","news","youtube","tiktok","threads"]},"description":"Only these sources."},"sentiment":{"type":"array","items":{"type":"string","enum":["positive","negative","neutral"]},"description":"Only these sentiments."},"categories":{"type":"array","items":{"type":"integer"},"description":"Only these category ids."},"groups":{"type":"array","items":{"type":"integer"},"description":"Only these keyword group ids."},"keywords":{"type":"array","items":{"type":"integer"},"description":"Only these keyword ids."},"authors":{"type":"array","items":{"type":"string"},"description":"Only these authors: exact handles, any case, e.g. @someone or u/someone.","maxItems":50},"min_engagement":{"type":"integer","minimum":0,"description":"Only posts with at least this much engagement."}}},"min_urgency":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Only mentions at or above this urgency (0–100)."}}}}}},"responses":{"200":{"description":"Alert","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"},"delete":{"operationId":"delete_alert","tags":["Alerts"],"summary":"Delete an alert","parameters":[{"name":"alert","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}},"/api/v1/alerts/{alert}/test":{"post":{"operationId":"test_alert","tags":["Alerts"],"summary":"Send a test now","description":"Sends a real message: a digest of the last 24 hours, or for a rule the latest matching mention. With nothing to show, it sends a clearly marked sample. Counts toward the daily cap.","parameters":[{"name":"alert","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ sent, channel, detail }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-access":"write"}}}}