{"openapi":"3.1.0","info":{"title":"ReadMe Metrics (BYOK) API","version":"0.1.0","description":"ReadMe Metrics (BYOK) lets an AI assistant read your own ReadMe Metrics data through the ReadMe Metrics API with a key you supply (ReadMe project API key (sent as the basic auth username)). Read-only: 9 tools (get_total_pageviews, get_unique_pageviews, get_pageview_change, get_pageviews_per_day, get_top_pages, get_top_search_terms, get_average_page_quality, get_best_pages, get_worst_pages). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-readme-metrics.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-readme-metrics/docs"},"termsOfService":"https://connectorbay.com/byok-readme-metrics/terms"},"servers":[{"url":"https://byok-readme-metrics.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-readme-metrics/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_total_pageviews":{"post":{"operationId":"get_total_pageviews","summary":"Enterprise plan feature of ReadMe. Get the total number of page views in a time window. Use for \"How many page views did","description":"Enterprise plan feature of ReadMe. Get the total number of page views in a time window. Use for \"How many page views did my ReadMe docs get this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"}},"title":"get_total_pageviewsArguments","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_unique_pageviews":{"post":{"operationId":"get_unique_pageviews","summary":"Enterprise plan feature of ReadMe. Get the number of unique page views in a time window. Use for \"How many unique page v","description":"Enterprise plan feature of ReadMe. Get the number of unique page views in a time window. Use for \"How many unique page views did my ReadMe docs get recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"}},"title":"get_unique_pageviewsArguments","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_pageview_change":{"post":{"operationId":"get_pageview_change","summary":"Enterprise plan feature of ReadMe. Get how total and unique page views changed compared with the previous window. Use fo","description":"Enterprise plan feature of ReadMe. Get how total and unique page views changed compared with the previous window. Use for \"Are my ReadMe docs getting more page views than before\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"}},"title":"get_pageview_changeArguments","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_pageviews_per_day":{"post":{"operationId":"get_pageviews_per_day","summary":"Enterprise plan feature of ReadMe. Get page views per time bucket (per day by default) over a window. The API's answer i","description":"Enterprise plan feature of ReadMe. Get page views per time bucket (per day by default) over a window. The API's answer is returned as is. Use for \"How do my ReadMe page views trend day by day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"}},"title":"get_pageviews_per_dayArguments","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_top_pages":{"post":{"operationId":"get_top_pages","summary":"Enterprise plan feature of ReadMe. List the most viewed documentation pages in a window. The API's answer is returned as","description":"Enterprise plan feature of ReadMe. List the most viewed documentation pages in a window. The API's answer is returned as is. Use for \"Which ReadMe docs pages are viewed the most\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Number of results to retrieve (default 30).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page of the result list, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Items per page (default 30).","title":"Page Size"}},"title":"get_top_pagesArguments","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_top_search_terms":{"post":{"operationId":"get_top_search_terms","summary":"Enterprise plan feature of ReadMe. List the phrases readers search for most in the docs in a window. The API's answer is","description":"Enterprise plan feature of ReadMe. List the phrases readers search for most in the docs in a window. The API's answer is returned as is. Use for \"What do readers search for in my ReadMe docs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Number of results to retrieve (default 30).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page of the result list, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Items per page (default 30).","title":"Page Size"}},"title":"get_top_search_termsArguments","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_average_page_quality":{"post":{"operationId":"get_average_page_quality","summary":"Enterprise plan feature of ReadMe. Get helpful and total votes per time bucket, optionally for one page path. Use for \"H","description":"Enterprise plan feature of ReadMe. Get helpful and total votes per time bucket, optionally for one page path. Use for \"How have readers rated my ReadMe docs over time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this documentation or API URL path, for example '/docs/getting-started'.","title":"Path"}},"title":"get_average_page_qualityArguments","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_best_pages":{"post":{"operationId":"get_best_pages","summary":"Enterprise plan feature of ReadMe. List the pages with the most positive votes: path, total votes, positive votes, diffe","description":"Enterprise plan feature of ReadMe. List the pages with the most positive votes: path, total votes, positive votes, difference and average. Use for \"Which ReadMe docs pages do readers like best\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this documentation or API URL path, for example '/docs/getting-started'.","title":"Path"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Number of results to retrieve (default 30).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page of the result list, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Items per page (default 30).","title":"Page Size"}},"title":"get_best_pagesArguments","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_worst_pages":{"post":{"operationId":"get_worst_pages","summary":"Enterprise plan feature of ReadMe. List the pages with the lowest ratings: path, total votes, positive votes, difference","description":"Enterprise plan feature of ReadMe. List the pages with the lowest ratings: path, total votes, positive votes, difference and average. Use for \"Which ReadMe docs pages do readers rate worst\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Length of the window in the chosen resolution units (default 30).","title":"Range Length"},"resolution":{"anyOf":[{"enum":["hour","day","week","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Time bucket: hour, day, week, month or year (default day).","title":"Resolution"},"range_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date of the window, for example 2026-01-01 (otherwise counted back from now).","title":"Range Start"},"range_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End date of the window, for example 2026-01-31.","title":"Range End"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this documentation or API URL path, for example '/docs/getting-started'.","title":"Path"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Number of results to retrieve (default 30).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page of the result list, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Items per page (default 30).","title":"Page Size"}},"title":"get_worst_pagesArguments","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}}}}