{"openapi":"3.1.0","info":{"title":"Mangools (BYOK) API","version":"0.1.0","description":"Mangools (BYOK) lets an AI assistant read your own Mangools data through the Mangools API with a key you supply (Mangools API token). Read-only: 12 tools (get_usage_limits, list_rank_trackings, get_rank_tracking, list_tracked_keywords, get_tracked_keyword, list_tracking_tags, list_keyword_lists, get_keyword_list, search_locations, list_ai_monitors, get_ai_monitor, list_ai_models). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mangools.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mangools/docs"},"termsOfService":"https://connectorbay.com/byok-mangools/terms"},"servers":[{"url":"https://byok-mangools.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mangools/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_usage_limits":{"post":{"operationId":"get_usage_limits","summary":"Show the plan, tracked keyword allowance, tracking count and the remaining quota of each Mangools resource pool (lookups","description":"Show the plan, tracked keyword allowance, tracking count and the remaining quota of each Mangools resource pool (lookups, backlink rows, tracked keywords, AI watcher prompts). Use for \"How much Mangools quota do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_usage_limitsArguments","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_rank_trackings":{"post":{"operationId":"list_rank_trackings","summary":"List your SERPWatcher rank trackings (one per domain, location and platform), newest first, with the keyword count. Use ","description":"List your SERPWatcher rank trackings (one per domain, location and platform), newest first, with the keyword count. Use for \"Which domains am I tracking rankings for in Mangools\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_with_deleted":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Set to true to include trackings that were deleted earlier.","title":"Is With Deleted"}},"title":"list_rank_trackingsArguments","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_rank_tracking":{"post":{"operationId":"get_rank_tracking","summary":"Get one rank tracking with its keyword list: domain, location, ranking URL per keyword, tags and last check time. Use fo","description":"Get one rank tracking with its keyword list: domain, location, ranking URL per keyword, tags and last check time. Use for \"Which keywords and ranking URLs does my Mangools tracking have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tracking_id":{"description":"Id of a SERPWatcher rank tracking (the _id from list_rank_trackings).","maxLength":200,"title":"Tracking Id","type":"string"},"is_with_deleted":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Set to true to include keywords that were removed earlier.","title":"Is With Deleted"}},"required":["tracking_id"],"title":"get_rank_trackingArguments","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_tracked_keywords":{"post":{"operationId":"list_tracked_keywords","summary":"List the keywords of a rank tracking. The fields parameter trims each item (for example kw,rank,sv); search volume and r","description":"List the keywords of a rank tracking. The fields parameter trims each item (for example kw,rank,sv); search volume and rank are included when requested. Use for \"What keywords are tracked in my Mangools tracking and what are their ranks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tracking_id":{"description":"Id of a SERPWatcher rank tracking (the _id from list_rank_trackings).","maxLength":200,"title":"Tracking Id","type":"string"},"fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"keyword_id,kw,rank,sv,location_id,platform_id","description":"Comma-separated attributes to return: tracking_id, keyword_id, kw, location_id, platform_id, rank, sv, active, history.","title":"Fields"}},"required":["tracking_id"],"title":"list_tracked_keywordsArguments","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_tracked_keyword":{"post":{"operationId":"get_tracked_keyword","summary":"Get the full rank detail of one tracked keyword: ranking URLs with daily ranks, search volume, SERP snapshot reference a","description":"Get the full rank detail of one tracked keyword: ranking URLs with daily ranks, search volume, SERP snapshot reference and tags, for a date range. Use for \"How has my keyword ranked in Mangools over the last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tracking_id":{"description":"Id of a SERPWatcher rank tracking (the _id from list_rank_trackings).","maxLength":200,"title":"Tracking Id","type":"string"},"tracked_keyword_id":{"description":"Id of the tracked keyword (keyword_id from list_tracked_keywords).","maxLength":200,"title":"Tracked Keyword Id","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the date range, YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the date range, YYYY-MM-DD.","title":"Date To"}},"required":["tracking_id","tracked_keyword_id"],"title":"get_tracked_keywordArguments","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_tracking_tags":{"post":{"operationId":"list_tracking_tags","summary":"List the keyword tags (name and colour) defined in one rank tracking. Use for \"Which keyword tags does my Mangools track","description":"List the keyword tags (name and colour) defined in one rank tracking. Use for \"Which keyword tags does my Mangools tracking use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tracking_id":{"description":"Id of a SERPWatcher rank tracking (the _id from list_rank_trackings).","maxLength":200,"title":"Tracking Id","type":"string"}},"required":["tracking_id"],"title":"list_tracking_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_keyword_lists":{"post":{"operationId":"list_keyword_lists","summary":"List your saved KWFinder keyword lists with the number of keywords in each (ids only, no volumes). Use for \"What keyword","description":"List your saved KWFinder keyword lists with the number of keywords in each (ids only, no volumes). Use for \"What keyword lists do I have saved in KWFinder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_keyword_listsArguments","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_keyword_list":{"post":{"operationId":"get_keyword_list","summary":"Get one saved KWFinder list with search volume, CPC and keyword difficulty for every keyword in it. Use for \"Show the ke","description":"Get one saved KWFinder list with search volume, CPC and keyword difficulty for every keyword in it. Use for \"Show the keywords and search volumes in my KWFinder list\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Id of the keyword list (the _id from list_keyword_lists).","maxLength":200,"title":"List Id","type":"string"}},"required":["list_id"],"title":"get_keyword_listArguments","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/search_locations":{"post":{"operationId":"search_locations","summary":"Search Mangools geotargeting locations (country, region, city) by name, up to 100 matches with ids to use in other Mango","description":"Search Mangools geotargeting locations (country, region, city) by name, up to 100 matches with ids to use in other Mangools calls. Use for \"What is the Mangools location id for New York\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Place name to search, for example 'New York'.","maxLength":100,"title":"Query","type":"string"}},"required":["query"],"title":"search_locationsArguments","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_ai_monitors":{"post":{"operationId":"list_ai_monitors","summary":"List your AI Search Watcher brand monitors with brand, domain, location and monitoring state. Use for \"Which brands do I","description":"List your AI Search Watcher brand monitors with brand, domain, location and monitoring state. Use for \"Which brands do I monitor in Mangools AI Search Watcher\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_ai_monitorsArguments","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_ai_monitor":{"post":{"operationId":"get_ai_monitor","summary":"Get one AI Search Watcher monitor: brand, score, visibility and position metrics with change, and the time series, for a","description":"Get one AI Search Watcher monitor: brand, score, visibility and position metrics with change, and the time series, for a date range. Use for \"How visible is my brand in AI answers according to Mangools\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitor_id":{"description":"Id of an AI Search Watcher monitor (the _id from list_ai_monitors).","maxLength":200,"title":"Monitor Id","type":"string"},"models":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":"0","description":"Comma-separated AI model ids to include, or 0 for an overview of all models (ids from list_ai_models).","title":"Models"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the date range, YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the date range, YYYY-MM-DD.","title":"Date To"}},"required":["monitor_id"],"title":"get_ai_monitorArguments","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_ai_models":{"post":{"operationId":"list_ai_models","summary":"List the AI answer engines that AI Search Watcher can monitor, with ids and whether they are active or deprecated. Use f","description":"List the AI answer engines that AI Search Watcher can monitor, with ids and whether they are active or deprecated. Use for \"Which AI models can Mangools monitor\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_ai_modelsArguments","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}}}}