{"openapi":"3.1.0","info":{"title":"ReadMe (BYOK) API","version":"0.1.0","description":"ReadMe (BYOK) lets an AI assistant read your own ReadMe data through the ReadMe API with a key you supply (ReadMe API key). Read-only: 10 tools (get_project, list_branches, list_categories, list_category_pages, get_guide_page, list_changelogs, get_changelog, list_api_definitions, list_recipes, search_docs). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-readme.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-readme/docs"},"termsOfService":"https://connectorbay.com/byok-readme/terms"},"servers":[{"url":"https://byok-readme.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-readme/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_project":{"post":{"operationId":"get_project","summary":"Show basic data about the ReadMe project the key belongs to: name, subdomain, description, home page, default version an","description":"Show basic data about the ReadMe project the key belongs to: name, subdomain, description, home page, default version and dates. Use for \"What is the subdomain and default version of my ReadMe project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_projectArguments","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_branches":{"post":{"operationId":"list_branches","summary":"List the versions and branches of the project with name, state and update time. Returns versions or branches depending o","description":"List the versions and branches of the project with name, state and update time. Returns versions or branches depending on the project. Only for projects on ReadMe Refactored. Use for \"Which versions of my ReadMe docs exist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort_by":{"anyOf":[{"enum":["created","review_status","semver","updated"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: created, review_status, semver (default) or updated.","title":"Sort By"},"prefix":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only versions starting with this prefix, for example 'v2.0'.","title":"Prefix"}},"title":"list_branchesArguments","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_categories":{"post":{"operationId":"list_categories","summary":"List the categories (sidebar headings) of a docs section in one version or branch. Only for projects on ReadMe Refactore","description":"List the categories (sidebar headings) of a docs section in one version or branch. Only for projects on ReadMe Refactored. Use for \"What categories do my ReadMe guides have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"branch":{"description":"Project version number, 'stable' for the stable version, or a branch name.","maxLength":100,"title":"Branch","type":"string"},"section":{"description":"Documentation section: 'guides', 'reference', or a guide section name.","maxLength":100,"title":"Section","type":"string"}},"required":["branch","section"],"title":"list_categoriesArguments","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_category_pages":{"post":{"operationId":"list_category_pages","summary":"List the pages inside one category with slug, title and update time. Only for projects on ReadMe Refactored. Use for \"Wh","description":"List the pages inside one category with slug, title and update time. Only for projects on ReadMe Refactored. Use for \"Which pages are in the Getting started category of my ReadMe guides\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"branch":{"description":"Project version number, 'stable' for the stable version, or a branch name.","maxLength":100,"title":"Branch","type":"string"},"section":{"description":"Documentation section: 'guides', 'reference', or a guide section name.","maxLength":100,"title":"Section","type":"string"},"title":{"description":"The category's title, for example 'Getting started'.","maxLength":200,"title":"Title","type":"string"}},"required":["branch","section","title"],"title":"list_category_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_guide_page":{"post":{"operationId":"get_guide_page","summary":"Get one guides page with its title, state, excerpt and Markdown body. Only for projects on ReadMe Refactored. Use for \"S","description":"Get one guides page with its title, state, excerpt and Markdown body. Only for projects on ReadMe Refactored. Use for \"Show the text of the intro page in my ReadMe guides\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"branch":{"description":"Project version number, 'stable' for the stable version, or a branch name.","maxLength":100,"title":"Branch","type":"string"},"slug":{"description":"The page's slug, for example 'intro'.","maxLength":200,"title":"Slug","type":"string"}},"required":["branch","slug"],"title":"get_guide_pageArguments","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_changelogs":{"post":{"operationId":"list_changelogs","summary":"List changelog entries with title, type (added, fixed, improved, etc.), slug and dates, 100 per page at most. Use for \"W","description":"List changelog entries with title, type (added, fixed, improved, etc.), slug and dates, 100 per page at most. Use for \"What is in my ReadMe changelog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"visibility":{"anyOf":[{"enum":["public","anyone_with_link","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Which entries: public, anyone_with_link or all (default).","title":"Visibility"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many entries to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_changelogsArguments","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_changelog":{"post":{"operationId":"get_changelog","summary":"Get one changelog entry with its type, author and text. Use for \"Show the changelog entry new-endpoint\".","description":"Get one changelog entry with its type, author and text. Use for \"Show the changelog entry new-endpoint\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"identifier":{"description":"The changelog entry's slug, for example 'new-endpoint'.","maxLength":200,"title":"Identifier","type":"string"}},"required":["identifier"],"title":"get_changelogArguments","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_api_definitions":{"post":{"operationId":"list_api_definitions","summary":"List the uploaded API definitions (OpenAPI, Swagger, Postman) that power the API reference with file name, type and upda","description":"List the uploaded API definitions (OpenAPI, Swagger, Postman) that power the API reference with file name, type and update time. Only for projects on ReadMe Refactored. Use for \"Which API definitions are uploaded to my ReadMe project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"branch":{"description":"Project version number, 'stable' for the stable version, or a branch name.","maxLength":100,"title":"Branch","type":"string"}},"required":["branch"],"title":"list_api_definitionsArguments","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_recipes":{"post":{"operationId":"list_recipes","summary":"List the recipes (step-by-step tutorials) of a version with slug, title and description. Only for projects on ReadMe Ref","description":"List the recipes (step-by-step tutorials) of a version with slug, title and description. Only for projects on ReadMe Refactored. Use for \"What recipes does my ReadMe project have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"branch":{"description":"Project version number, 'stable' for the stable version, or a branch name.","maxLength":100,"title":"Branch","type":"string"}},"required":["branch"],"title":"list_recipesArguments","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_docs":{"post":{"operationId":"search_docs","summary":"Search the project's documentation (guides, reference, recipes, custom pages, discussions, changelog) and return matchin","description":"Search the project's documentation (guides, reference, recipes, custom pages, discussions, changelog) and return matching pages with an excerpt. Use for \"Search my ReadMe docs for 'authentication'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Plain text to search for.","maxLength":200,"title":"Query","type":"string"},"section":{"anyOf":[{"enum":["guides","reference","recipes","custom_pages","discuss","changelog"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this section.","title":"Section"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many results to return (1 to 50).","title":"Per Page"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["query"],"title":"search_docsArguments","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}}}}