{"openapi":"3.1.0","info":{"title":"Nightwatch (BYOK) API","version":"0.1.0","description":"Nightwatch (BYOK) lets an AI assistant read your own Nightwatch data through the Nightwatch API with a key you supply (Nightwatch API access token). Read-only: 11 tools (get_user, list_url_groups, list_urls, get_url, list_keywords, list_keyword_results, list_competitors, list_keyword_views, get_url_series, get_keyword_stats, get_serp). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-nightwatch.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-nightwatch/docs"},"termsOfService":"https://connectorbay.com/byok-nightwatch/terms"},"servers":[{"url":"https://byok-nightwatch.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-nightwatch/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_user":{"post":{"operationId":"get_user","summary":"Get the account behind the token: name, plan, status, renewal date, timezone and keyword/URL limits and usage. Invoice d","description":"Get the account behind the token: name, plan, status, renewal date, timezone and keyword/URL limits and usage. Invoice details and login IPs are left out. Use for \"How many keywords have I used in Nightwatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_userArguments","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_url_groups":{"post":{"operationId":"list_url_groups","summary":"List the URL groups (top-level containers) of the account with URL counts. Use for \"Which URL groups do I have in Nightw","description":"List the URL groups (top-level containers) of the account with URL counts. Use for \"Which URL groups do I have in Nightwatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_url_groupsArguments","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_urls":{"post":{"operationId":"list_urls","summary":"List the tracked sites (URLs) with keyword counts, domain authority, Google indexed pages and keyword movement; optional","description":"List the tracked sites (URLs) with keyword counts, domain authority, Google indexed pages and keyword movement; optionally for one group. Use for \"Which sites do I track in Nightwatch and how many keywords each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"anyOf":[{"maximum":999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only URLs in this group id.","title":"Group Id"}},"title":"list_urlsArguments","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_url":{"post":{"operationId":"get_url","summary":"Get one tracked site with its keyword count, domain authority, indexed pages, competitors and country and language setti","description":"Get one tracked site with its keyword count, domain authority, indexed pages, competitors and country and language settings. Use for \"Show Nightwatch tracked site 31234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"description":"Tracked URL id from list_urls.","maximum":999999999,"minimum":1,"title":"Url Id","type":"integer"}},"required":["url_id"],"title":"get_urlArguments","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_keywords":{"post":{"operationId":"list_keywords","summary":"List a tracked site's keywords with current position, previous and best position, changes over a day, week and month, ra","description":"List a tracked site's keywords with current position, previous and best position, changes over a day, week and month, ranking URL, tags and search volume. Sort and page with the parameters. Use for \"Which Nightwatch keywords for site 31234 dropped this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"description":"Tracked URL id from list_urls.","maximum":999999999,"minimum":1,"title":"Url Id","type":"integer"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"position","description":"Field to sort by, for example position, query, position_changed_during_last_week or best_position.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction.","title":"Direction"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by keyword term, tag, ranking URL or location.","title":"Search"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Keywords per page.","title":"Limit"}},"required":["url_id"],"title":"list_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/list_keyword_results":{"post":{"operationId":"list_keyword_results","summary":"List the daily ranking results of one keyword between two dates: position, ranking URL and result id (usable with get_se","description":"List the daily ranking results of one keyword between two dates: position, ranking URL and result id (usable with get_serp). Use for \"How did Nightwatch keyword 1 rank over January\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"description":"Tracked URL id from list_urls.","maximum":999999999,"minimum":1,"title":"Url Id","type":"integer"},"keyword_id":{"description":"Keyword id from list_keywords.","maximum":99999999999,"minimum":1,"title":"Keyword Id","type":"integer"},"time_start":{"description":"Start date, YYYY-MM-DD.","maxLength":10,"title":"Time Start","type":"string"},"time_end":{"description":"End date, YYYY-MM-DD.","maxLength":10,"title":"Time End","type":"string"}},"required":["url_id","keyword_id","time_start","time_end"],"title":"list_keyword_resultsArguments","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_competitors":{"post":{"operationId":"list_competitors","summary":"List the competitor sites tracked alongside a site. Use for \"Which competitors does Nightwatch track for site 31234\".","description":"List the competitor sites tracked alongside a site. Use for \"Which competitors does Nightwatch track for site 31234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"description":"Tracked URL id from list_urls.","maximum":999999999,"minimum":1,"title":"Url Id","type":"integer"}},"required":["url_id"],"title":"list_competitorsArguments","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_views":{"post":{"operationId":"list_keyword_views","summary":"List saved keyword views (filtered keyword lists); filter by site or group. Use for \"Which keyword views exist for Night","description":"List saved keyword views (filtered keyword lists); filter by site or group. Use for \"Which keyword views exist for Nightwatch site 31234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"anyOf":[{"maximum":999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only views of this URL id.","title":"Url Id"},"group_id":{"anyOf":[{"maximum":999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only views of this group id.","title":"Group Id"},"without_counts":{"anyOf":[{"const":"true","type":"string"},{"type":"null"}],"default":null,"description":"Pass true to skip keyword and report counts (faster).","title":"Without Counts"}},"title":"list_keyword_viewsArguments","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_url_series":{"post":{"operationId":"get_url_series","summary":"Get daily time series (average position, visibility, keyword distribution, indexed pages, clicks) for one tracked site o","description":"Get daily time series (average position, visibility, keyword distribution, indexed pages, clicks) for one tracked site over a date range, optionally with competitors. Use for \"How did average position for Nightwatch site 31234 change in January\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url_id":{"description":"Tracked URL id from list_urls.","maximum":999999999,"minimum":1,"title":"Url Id","type":"integer"},"date_from":{"description":"Start date, YYYY-MM-DD.","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"End date, YYYY-MM-DD.","maxLength":10,"title":"Date To","type":"string"},"with_competitors":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":"false","description":"Include competitor series.","title":"With Competitors"}},"required":["url_id","date_from","date_to"],"title":"get_url_seriesArguments","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_stats":{"post":{"operationId":"get_keyword_stats","summary":"Get summary statistics for a site or keyword view over a date range: average position, visibility, top 3/10/100 counts, ","description":"Get summary statistics for a site or keyword view over a date range: average position, visibility, top 3/10/100 counts, movers and indexed pages with their changes. Use for \"What is the Nightwatch visibility and top 10 count for site 31234 in January\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"Start date, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"End date, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"url_id":{"anyOf":[{"maximum":999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Tracked URL id; give this or dynamic_view_id.","title":"Url Id"},"dynamic_view_id":{"anyOf":[{"maximum":999999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Keyword view id; give this or url_id.","title":"Dynamic View Id"}},"required":["start_date","end_date"],"title":"get_keyword_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}},"/v1/tools/get_serp":{"post":{"operationId":"get_serp","summary":"Get the stored search results page behind one keyword result: top organic results with title, URL and position, plus loc","description":"Get the stored search results page behind one keyword result: top organic results with title, URL and position, plus local pack and other features. Use for \"What did the Google results look like for Nightwatch result 24771\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"result_id":{"description":"Result id from list_keyword_results.","maximum":99999999999,"minimum":1,"title":"Result Id","type":"integer"}},"required":["result_id"],"title":"get_serpArguments","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}}}}