{"openapi":"3.1.0","info":{"title":"Help Scout Docs (BYOK) API","version":"0.1.0","description":"Help Scout Docs (BYOK) lets an AI assistant read your own Help Scout Docs data through the Help Scout Docs API with a key you supply (Docs API key). Read-only: 6 tools (list_collections, list_categories, list_collection_articles, list_category_articles, search_articles, get_article). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-helpscout.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-helpscout/docs"},"termsOfService":"https://connectorbay.com/byok-helpscout/terms"},"servers":[{"url":"https://byok-helpscout.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-helpscout/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_collections":{"post":{"operationId":"list_collections","summary":"List your Docs collections (groups of articles) with visibility, article counts and public URL. Use the ids with the oth","description":"List your Docs collections (groups of articles) with visibility, article counts and public URL. Use the ids with the other tools. Use for \"What collections does my Help Scout knowledge base have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only collections of this Docs site id.","title":"Site Id"},"visibility":{"anyOf":[{"enum":["all","public","private"],"type":"string"},{"type":"null"}],"default":"all","description":"Which collections: all, public or private.","title":"Visibility"},"sort":{"anyOf":[{"enum":["number","visibility","order","name","createdAt","updatedAt"],"type":"string"},{"type":"null"}],"default":"order","description":"Sort field: number, visibility, order, name, createdAt or updatedAt.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Order"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer reports the total number of pages.","title":"Page"}},"title":"list_collectionsArguments","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 inside one Docs collection with article counts. Use for \"What categories are in my Help Scout 'Getti","description":"List the categories inside one Docs collection with article counts. Use for \"What categories are in my Help Scout 'Getting started' collection\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection_id":{"description":"Collection id, as returned by list_collections.","maxLength":40,"title":"Collection Id","type":"string"},"sort":{"anyOf":[{"enum":["number","order","name","articleCount","createdAt","updatedAt"],"type":"string"},{"type":"null"}],"default":"order","description":"Sort field: number, order, name, articleCount, createdAt or updatedAt.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Order"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer reports the total number of pages.","title":"Page"}},"required":["collection_id"],"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_collection_articles":{"post":{"operationId":"list_collection_articles","summary":"List the articles of one collection (name, number, status, public URL, view count, dates) without their body text. Use f","description":"List the articles of one collection (name, number, status, public URL, view count, dates) without their body text. Use for \"Which articles are published in my Help Scout 'Getting started' collection\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection_id":{"description":"Collection id, as returned by list_collections.","maxLength":40,"title":"Collection Id","type":"string"},"status":{"anyOf":[{"enum":["all","published","notPublished"],"type":"string"},{"type":"null"}],"default":"all","description":"Which articles: all, published or notPublished.","title":"Status"},"sort":{"anyOf":[{"enum":["number","status","name","popularity","createdAt","updatedAt","order"],"type":"string"},{"type":"null"}],"default":"order","description":"Sort field: number, status, name, popularity, createdAt or updatedAt (default order).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction: asc or desc.","title":"Order"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many articles per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer reports the total number of pages.","title":"Page"}},"required":["collection_id"],"title":"list_collection_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_category_articles":{"post":{"operationId":"list_category_articles","summary":"List the articles of one category (name, number, status, public URL, view count, dates) without their body text. Use for","description":"List the articles of one category (name, number, status, public URL, view count, dates) without their body text. Use for \"Which articles are in my Help Scout 'Accounts' category\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"description":"Category id, as returned by list_categories.","maxLength":40,"title":"Category Id","type":"string"},"status":{"anyOf":[{"enum":["all","published","notPublished"],"type":"string"},{"type":"null"}],"default":"all","description":"Which articles: all, published or notPublished.","title":"Status"},"sort":{"anyOf":[{"enum":["number","status","name","popularity","createdAt","updatedAt","order"],"type":"string"},{"type":"null"}],"default":"order","description":"Sort field: number, status, name, popularity, createdAt or updatedAt (default order).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction: asc or desc.","title":"Order"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many articles per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer reports the total number of pages.","title":"Page"}},"required":["category_id"],"title":"list_category_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/search_articles":{"post":{"operationId":"search_articles","summary":"Search Docs articles by text; returns matching articles with a short preview, URL, status and visibility. Use for \"Searc","description":"Search Docs articles by text; returns matching articles with a short preview, URL, status and visibility. Use for \"Search my Help Scout docs for articles about resetting a password\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to search for.","maxLength":200,"title":"Query","type":"string"},"collection_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only search this collection id.","title":"Collection Id"},"site_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only search this Docs site id.","title":"Site Id"},"status":{"anyOf":[{"enum":["all","published","notPublished"],"type":"string"},{"type":"null"}],"default":"all","description":"Which articles: all, published or notPublished.","title":"Status"},"visibility":{"anyOf":[{"enum":["all","public","private"],"type":"string"},{"type":"null"}],"default":"all","description":"Visibility of the article's collection: all, public or private.","title":"Visibility"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer reports the total number of pages.","title":"Page"}},"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/get_article":{"post":{"operationId":"get_article","summary":"Get one article with its full body text (HTML), collection, categories, related articles, view count and dates. Use for ","description":"Get one article with its full body text (HTML), collection, categories, related articles, view count and dates. Use for \"Show me Help Scout article 12 in full\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"article_id":{"description":"Article id or article number, as returned by the list or search tools.","maxLength":40,"title":"Article Id","type":"string"},"draft":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return the unpublished draft when one exists.","title":"Draft"}},"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}}}}