{"openapi":"3.1.0","info":{"title":"Mention (BYOK) API","version":"0.1.0","description":"Mention (BYOK) lets an AI assistant read your own Mention data through the Mention API with a key you supply (Mention access token). Read-only: 10 tools (get_my_account, list_alerts, get_alert, list_mentions, get_mention, list_mention_children, list_tags, list_authors, list_alert_tasks, get_stats). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mention.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mention/docs"},"termsOfService":"https://connectorbay.com/byok-mention/terms"},"servers":[{"url":"https://byok-mention.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mention/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_my_account":{"post":{"operationId":"get_my_account","summary":"Get the account the access token belongs to: id (needed by other tools), name, language, creation date and permissions. ","description":"Get the account the access token belongs to: id (needed by other tools), name, language, creation date and permissions. Use for \"Which Mention account is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_my_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_alerts":{"post":{"operationId":"list_alerts","summary":"List the account's alerts (saved monitoring queries) with keywords, sources, languages and mention counts. Use for \"Whic","description":"List the account's alerts (saved monitoring queries) with keywords, sources, languages and mention counts. Use for \"Which Mention alerts do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of alerts to return; default returns all.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned by the API in a previous page.","title":"Cursor"}},"required":["account_id"],"title":"list_alertsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_alert":{"post":{"operationId":"get_alert","summary":"Get one alert with its query keywords, sources, languages, countries, blocked sites, folder counts and quota use. Team m","description":"Get one alert with its query keywords, sources, languages, countries, blocked sites, folder counts and quota use. Team member emails are left out. Use for \"Show the settings of Mention alert 112233\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"}},"required":["account_id","alert_id"],"title":"get_alertArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_mentions":{"post":{"operationId":"list_mentions","summary":"List mentions found by an alert (newest first) with title, snippet, source, tone, country, folder and author influence; ","description":"List mentions found by an alert (newest first) with title, snippet, source, tone, country, folder and author influence; filter by folder, tone, source or date. Keyword search needs a plan with search access. Use for \"Show negative Mention results for alert 112233\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Number of mentions to return (default 20).","title":"Limit"},"folder":{"anyOf":[{"enum":["inbox","archive","spam","trash"],"type":"string"},{"type":"null"}],"default":null,"description":"Only mentions in this folder.","title":"Folder"},"tone":{"anyOf":[{"enum":["-1","0","1"],"type":"string"},{"type":"null"}],"default":null,"description":"Only mentions with this tone: -1 negative, 0 neutral, 1 positive.","title":"Tone"},"source":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only mentions from this source such as web, news, twitter, blogs, forums, videos or images (plans with search access).","title":"Source"},"unread":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Set 1 to return only unread mentions.","title":"Unread"},"favorite":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Set 1 to return only favorite mentions.","title":"Favorite"},"before_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only mentions published before this ISO 8601 date.","title":"Before Date"},"not_before_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Ignore mentions older than this ISO 8601 date (requires before_date).","title":"Not Before Date"},"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword filter, for example 'nasa source:(news OR web)' (plans with search access).","title":"Q"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned by the API in a previous page.","title":"Cursor"}},"required":["account_id","alert_id"],"title":"list_mentionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_mention":{"post":{"operationId":"get_mention","summary":"Get one mention with its text, URL, source, tone, folder, tags and author influence. Use for \"Show Mention mention 52784","description":"Get one mention with its text, URL, source, tone, folder, tags and author influence. Use for \"Show Mention mention 527849933\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"mention_id":{"description":"Mention id from list_mentions.","maximum":99999999999999,"minimum":1,"title":"Mention Id","type":"integer"}},"required":["account_id","alert_id","mention_id"],"title":"get_mentionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_mention_children":{"post":{"operationId":"list_mention_children","summary":"List the child mentions grouped under one mention (duplicates and replies). Use for \"Which mentions are grouped under Me","description":"List the child mentions grouped under one mention (duplicates and replies). Use for \"Which mentions are grouped under Mention mention 527849933\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"mention_id":{"description":"Mention id from list_mentions.","maximum":99999999999999,"minimum":1,"title":"Mention Id","type":"integer"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Number of mentions to return (default 20).","title":"Limit"},"before_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only mentions older than this ISO 8601 date.","title":"Before Date"}},"required":["account_id","alert_id","mention_id"],"title":"list_mention_childrenArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List an alert's mention tags with mention counts and auto-tagging keywords. Use for \"Which tags does Mention alert 11223","description":"List an alert's mention tags with mention counts and auto-tagging keywords. Use for \"Which tags does Mention alert 112233 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"}},"required":["account_id","alert_id"],"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_authors":{"post":{"operationId":"list_authors","summary":"List the top authors (influencers) of an alert on a social network or the web with influence score and follower counts. ","description":"List the top authors (influencers) of an alert on a social network or the web with influence score and follower counts. Use for \"Who are the top Twitter authors for Mention alert 112233\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"kind":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Network to list authors of, for example twitter, web, instagram or facebook.","title":"Kind"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window start, ISO 8601 such as 2026-01-14T00:00:00.0.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window end, ISO 8601.","title":"End Date"},"sort":{"anyOf":[{"const":"score","type":"string"},{"type":"null"}],"default":"score","description":"Sort field.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order.","title":"Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Number of authors to return.","title":"Limit"}},"required":["account_id","alert_id"],"title":"list_authorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_alert_tasks":{"post":{"operationId":"list_alert_tasks","summary":"List the team tasks created on an alert's mentions; filter by completion. Use for \"Which Mention tasks are still open on","description":"List the team tasks created on an alert's mentions; filter by completion. Use for \"Which Mention tasks are still open on alert 112233\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id from list_alerts.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Number of tasks to return.","title":"Limit"},"done":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 for completed tasks, 0 for open tasks.","title":"Done"},"before_id":{"anyOf":[{"maximum":99999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only tasks with an id lower than this.","title":"Before Id"}},"required":["account_id","alert_id"],"title":"list_alert_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_stats":{"post":{"operationId":"get_stats","summary":"Get statistics of one alert over a window: mentions per interval, tones, reach, weekday distribution and top countries. ","description":"Get statistics of one alert over a window: mentions per interval, tones, reach, weekday distribution and top countries. Use for \"How many mentions did Mention alert 112233 get last week by day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Your Mention account id (from get_my_account).","maxLength":100,"title":"Account Id","type":"string"},"alert_id":{"description":"Alert id to get statistics for.","maximum":9999999999999,"minimum":1,"title":"Alert Id","type":"integer"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window start, ISO 8601 such as 2026-01-14T00:00:00.0.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window end, ISO 8601.","title":"End Date"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone of from and to, for example Europe/Berlin.","title":"Timezone"},"interval":{"anyOf":[{"enum":["P1D","P1W","P1M"],"type":"string"},{"type":"null"}],"default":"P1D","description":"Bucket size: P1D daily, P1W weekly or P1M monthly.","title":"Interval"},"country_stats":{"anyOf":[{"maximum":50,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many top countries to include (0 to 50).","title":"Country Stats"}},"required":["account_id","alert_id"],"title":"get_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}