{"openapi":"3.1.0","info":{"title":"HelpDocs (BYOK) API","version":"0.1.0","description":"HelpDocs (BYOK) lets an AI assistant read your own HelpDocs data through the HelpDocs API with a key you supply (HelpDocs API key (Read scope or higher)). Read-only: 9 tools (list_articles, get_article, get_article_versions, search_articles, list_categories, get_category, get_top_articles, get_search_terms, get_article_feedback). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-helpdocs.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-helpdocs/docs"},"termsOfService":"https://connectorbay.com/byok-helpdocs/terms"},"servers":[{"url":"https://byok-helpdocs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-helpdocs/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/list_articles":{"post":{"operationId":"list_articles","summary":"List knowledge base articles with title, category, tags, publish state and dates. Article bodies are left out unless ask","description":"List knowledge base articles with title, category, tags, publish state and dates. Article bodies are left out unless asked for. Use for \"Which articles are in my HelpDocs knowledge base\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles in this category id (comma-separate several).","title":"Category Id"},"tag":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles with this tag (comma-separate several).","title":"Tag"},"status":{"anyOf":[{"enum":["published","draft","private"],"type":"string"},{"type":"null"}],"default":null,"description":"Only articles with this status: published, draft or private.","title":"Status"},"updated_at_after":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles updated after this date, for example 2026-01-31.","title":"Updated At After"},"updated_at_before":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles updated before this date, for example 2026-06-30.","title":"Updated At Before"},"lite":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True (default) leaves the article body out of the answer.","title":"Lite"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum number of articles to return.","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many articles to skip, for paging.","title":"Skip"}},"title":"list_articlesArguments","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_article":{"post":{"operationId":"get_article","summary":"Get one article with its title, HTML body, tags, category, publish state and URL. Use for \"Show the HelpDocs article abo","description":"Get one article with its title, HTML body, tags, category, publish state and URL. Use for \"Show the HelpDocs article about logging in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"article_id":{"description":"Article id (10 characters), as returned by list_articles.","maxLength":200,"title":"Article Id","type":"string"}},"required":["article_id"],"title":"get_articleArguments","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_article_versions":{"post":{"operationId":"get_article_versions","summary":"List the saved versions of one article (language, version number, whether it is current, author id, body and time). Use ","description":"List the saved versions of one article (language, version number, whether it is current, author id, body and time). Use for \"What older versions exist of a HelpDocs article\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"article_id":{"description":"Article id (10 characters), as returned by list_articles.","maxLength":200,"title":"Article Id","type":"string"},"language_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only versions in this language, for example en.","title":"Language Code"}},"required":["article_id"],"title":"get_article_versionsArguments","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_articles":{"post":{"operationId":"search_articles","summary":"Search the knowledge base for a phrase and return the top matching articles. Use for \"Search my HelpDocs knowledge base ","description":"Search the knowledge base for a phrase and return the top matching articles. Use for \"Search my HelpDocs knowledge base for 'refund'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search phrase.","maxLength":200,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (default 10, maximum 100).","title":"Limit"},"include_private":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include private articles.","title":"Include Private"},"include_draft":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include draft articles.","title":"Include Draft"}},"required":["query"],"title":"search_articlesArguments","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 knowledge base categories with title, description and parent category. Use for \"What categories does my HelpDoc","description":"List the knowledge base categories with title, description and parent category. Use for \"What categories does my HelpDocs knowledge base have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/get_category":{"post":{"operationId":"get_category","summary":"Get one category's title, description and parent. Use for \"Show the HelpDocs category with a given id\".","description":"Get one category's title, description and parent. Use for \"Show the HelpDocs category with a given id\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"description":"Category id (10 characters), as returned by list_categories.","maxLength":200,"title":"Category Id","type":"string"}},"required":["category_id"],"title":"get_categoryArguments","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_articles":{"post":{"operationId":"get_top_articles","summary":"Show how many views each article received in a period, most viewed first. Use for \"Which HelpDocs articles were viewed m","description":"Show how many views each article received in a period, most viewed first. Use for \"Which HelpDocs articles were viewed most last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity after this RFC 3339 time, for example 2026-01-01T00:00:00Z.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity before this RFC 3339 time.","title":"End"},"article_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to this article id.","title":"Article Id"},"category_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to articles in this category id.","title":"Category Id"}},"title":"get_top_articlesArguments","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_search_terms":{"post":{"operationId":"get_search_terms","summary":"Show the phrases visitors searched for in a period with how often and how many results they returned on average. Use for","description":"Show the phrases visitors searched for in a period with how often and how many results they returned on average. Use for \"What are visitors searching for in my HelpDocs site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity after this RFC 3339 time, for example 2026-01-01T00:00:00Z.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity before this RFC 3339 time.","title":"End"},"article_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to this article id.","title":"Article Id"},"category_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to articles in this category id.","title":"Category Id"}},"title":"get_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_article_feedback":{"post":{"operationId":"get_article_feedback","summary":"Show visitor feedback on articles in a period: overall positive, neutral and negative counts, a happiness score and per-","description":"Show visitor feedback on articles in a period: overall positive, neutral and negative counts, a happiness score and per-article results. Use for \"How happy are readers with my HelpDocs articles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity after this RFC 3339 time, for example 2026-01-01T00:00:00Z.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only count activity before this RFC 3339 time.","title":"End"},"article_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to this article id.","title":"Article Id"},"category_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only traffic to articles in this category id.","title":"Category Id"}},"title":"get_article_feedbackArguments","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}}}}