Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: SnoopScan Mentions API
description: 'Turn any public web page into clean markdown or structured JSON: scrape, crawl, map, search and extract. One bearer key for every endpoint.'
version: 0.1.0
servers:
- url: https://api.snoopscan.com
tags:
- name: Mentions
paths:
/v1/mentions/watches:
post:
tags:
- Mentions
summary: Create Watch
operationId: create_watch_v1_mentions_watches_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Create Watch V1 Mentions Watches Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Mentions
summary: List Watches
operationId: list_watches_v1_mentions_watches_get
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response List Watches V1 Mentions Watches Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/mentions/watches/{watch_id}:
get:
tags:
- Mentions
summary: Get Watch
operationId: get_watch_v1_mentions_watches__watch_id__get
parameters:
- name: watch_id
in: path
required: true
schema:
type: string
title: Watch Id
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Watch V1 Mentions Watches Watch Id Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Mentions
summary: Update Watch
operationId: update_watch_v1_mentions_watches__watch_id__patch
parameters:
- name: watch_id
in: path
required: true
schema:
type: string
title: Watch Id
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Update Watch V1 Mentions Watches Watch Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Mentions
summary: Delete Watch
operationId: delete_watch_v1_mentions_watches__watch_id__delete
parameters:
- name: watch_id
in: path
required: true
schema:
type: string
title: Watch Id
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Delete Watch V1 Mentions Watches Watch Id Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/mentions/watches/{watch_id}/test:
post:
tags:
- Mentions
summary: Test Saved Watch
description: 'Run a saved watch against its sources now and show what it finds from the
last 7 days, where a source allows. Nothing is stored or sent.'
operationId: test_saved_watch_v1_mentions_watches__watch_id__test_post
parameters:
- name: watch_id
in: path
required: true
schema:
type: string
title: Watch Id
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Test Saved Watch V1 Mentions Watches Watch Id Test Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/mentions/test:
post:
tags:
- Mentions
summary: Test Keywords
description: Try a watch before saving it. Same answer as testing a saved one.
operationId: test_keywords_v1_mentions_test_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchFields'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Test Keywords V1 Mentions Test Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/mentions:
get:
tags:
- Mentions
summary: List Mentions
operationId: list_mentions_v1_mentions_get
parameters:
- name: watch_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Only this watch's mentions.
title: Watch Id
description: Only this watch's mentions.
- name: category
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'One of: bug_report, complaint, question, buying_intent, praise, competitor, other.'
title: Category
description: 'One of: bug_report, complaint, question, buying_intent, praise, competitor, other.'
- name: platform
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'One of: reddit, hackernews, bluesky, youtube, threads, web, github, feeds.'
title: Platform
description: 'One of: reddit, hackernews, bluesky, youtube, threads, web, github, feeds.'
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: new, seen, irrelevant or done.
title: Status
description: new, seen, irrelevant or done.
- name: since
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only mentions found at or after this time.
title: Since
description: Only mentions found at or after this time.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The `next` cursor of the previous page.
title: Cursor
description: The `next` cursor of the previous page.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 50
title: Limit
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response List Mentions V1 Mentions Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/mentions/{mention_id}:
patch:
tags:
- Mentions
summary: Mark Mention
operationId: mark_mention_v1_mentions__mention_id__patch
parameters:
- name: mention_id
in: path
required: true
schema:
type: string
title: Mention Id
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StatusUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Mark Mention V1 Mentions Mention Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
StatusUpdate:
properties:
status:
type: string
title: Status
description: new, seen, irrelevant or done.
additionalProperties: false
type: object
required:
- status
title: StatusUpdate
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
WatchUpdate:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: A new name.
keywords:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Keywords
description: Replaces the keywords.
competitors:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Competitors
description: Replaces the competitor keywords.
exclude:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Exclude
description: Replaces the excluded words.
platforms:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Platforms
description: Replaces the platforms.
feeds:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Feeds
description: Replaces the feed addresses.
categories:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Categories
description: Replaces the categories kept.
customWords:
anyOf:
- additionalProperties:
items:
type: string
type: array
type: object
- type: 'null'
title: Customwords
description: Replaces your own category words.
intervalMinutes:
anyOf:
- type: integer
- type: 'null'
title: Intervalminutes
description: Minutes between checks.
webhook:
anyOf:
- type: string
- type: 'null'
title: Webhook
description: A new webhook URL; empty removes it.
active:
anyOf:
- type: boolean
- type: 'null'
title: Active
description: Pause (false) or resume (true) the watch.
additionalProperties: false
type: object
title: WatchUpdate
WatchRequest:
properties:
keywords:
items:
type: string
type: array
title: Keywords
description: Words or phrases to look for, up to 20 with `competitors`. Whole words, any case.
competitors:
items:
type: string
type: array
title: Competitors
description: Keywords for a competitor. A post that matches one of these and none of `keywords` is sorted as `competitor`.
exclude:
items:
type: string
type: array
title: Exclude
description: Words that remove a post from the results when it contains any of them.
platforms:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Platforms
description: 'Where to look: reddit, hackernews, bluesky, youtube, threads, web, github, feeds. Default is all of them.'
feeds:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Feeds
description: RSS or Atom feed addresses to read (a Substack, a blog, a forum), up to 10. Read when `platforms` includes feeds; new entries that name a keyword as a whole word become mentions.
categories:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Categories
description: 'Categories to keep: bug_report, complaint, question, buying_intent, praise, competitor, other. Posts sorted elsewhere are dropped. Default is all.'
customWords:
anyOf:
- additionalProperties:
items:
type: string
type: array
type: object
- type: 'null'
title: Customwords
description: 'Your own words for a category, added to the built-in ones. Example: {"buying_intent": ["any tips"]}.'
intervalMinutes:
anyOf:
- type: integer
- type: 'null'
title: Intervalminutes
description: 'How often to check, in minutes: 5 to 10,080. Default 15.'
name:
type: string
maxLength: 120
minLength: 1
title: Name
description: A name for the watch.
webhook:
anyOf:
- type: string
- type: 'null'
title: Webhook
description: A URL to POST to with `mention.created` for each new mention. Signed with your key's webhook secret.
additionalProperties: false
type: object
required:
- name
title: WatchRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
WatchFields:
properties:
keywords:
items:
type: string
type: array
title: Keywords
description: Words or phrases to look for, up to 20 with `competitors`. Whole words, any case.
competitors:
items:
type: string
type: array
title: Competitors
description: Keywords for a competitor. A post that matches one of these and none of `keywords` is sorted as `competitor`.
exclude:
items:
type: string
type: array
title: Exclude
description: Words that remove a post from the results when it contains any of them.
platforms:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Platforms
description: 'Where to look: reddit, hackernews, bluesky, youtube, threads, web, github, feeds. Default is all of them.'
feeds:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Feeds
description: RSS or Atom feed addresses to read (a Substack, a blog, a forum), up to 10. Read when `platforms` includes feeds; new entries that name a keyword as a whole word become mentions.
categories:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Categories
description: 'Categories to keep: bug_report, complaint, question, buying_intent, praise, competitor, other. Posts sorted elsewhere are dropped. Default is all.'
customWords:
anyOf:
- additionalProperties:
items:
type: string
type: array
type: object
- type: 'null'
title: Customwords
description: 'Your own words for a category, added to the built-in ones. Example: {"buying_intent": ["any tips"]}.'
intervalMinutes:
anyOf:
- type: integer
- type: 'null'
title: Intervalminutes
description: 'How often to check, in minutes: 5 to 10,080. Default 15.'
additionalProperties: false
type: object
title: WatchFields