{"openapi":"3.1.0","info":{"title":"KnowBe4 (BYOK) API","version":"0.1.0","description":"KnowBe4 (BYOK) lets an AI assistant read your own KnowBe4 data through the KnowBe4 API with a key you supply (KnowBe4 Reporting API key). Read-only: 11 tools (get_account, get_account_risk_history, list_groups, list_users, get_user, list_phishing_campaigns, list_phishing_security_tests, list_training_campaigns, list_training_enrollments, list_training_store_purchases, list_training_policies). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-knowbe4.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-knowbe4/docs"},"termsOfService":"https://connectorbay.com/byok-knowbe4/terms"},"servers":[{"url":"https://byok-knowbe4.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-knowbe4/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_account":{"post":{"operationId":"get_account","summary":"Show the KnowBe4 account: name, subscription level and end date, seat count, current organisation risk score and admin c","description":"Show the KnowBe4 account: name, subscription level and end date, seat count, current organisation risk score and admin contacts. Use for \"What subscription level and risk score does our KnowBe4 account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"}},"required":["region"],"title":"get_accountArguments","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_account_risk_history":{"post":{"operationId":"get_account_risk_history","summary":"Show the organisation's risk score over time (six months by default, or the full history). Use for \"How has our KnowBe4 ","description":"Show the organisation's risk score over time (six months by default, or the full history). Use for \"How has our KnowBe4 risk score changed over time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"full":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Set true to return the whole history instead of the last six months.","title":"Full"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"get_account_risk_historyArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List KnowBe4 groups with type, member count, current risk score and status. Use for \"Which KnowBe4 groups do we have and","description":"List KnowBe4 groups with type, member count, current risk score and status. Use for \"Which KnowBe4 groups do we have and which has the highest risk score\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"status":{"anyOf":[{"enum":["active","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Only active or archived groups (default: all returned by the API).","title":"Status"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_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_users":{"post":{"operationId":"list_users","summary":"List KnowBe4 users with name, job title, department, location, risk score, phish-prone percentage and status. Contact nu","description":"List KnowBe4 users with name, job title, department, location, risk score, phish-prone percentage and status. Contact numbers are not returned. Use for \"Which active KnowBe4 users have the highest risk score\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"status":{"anyOf":[{"enum":["active","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Only active or archived users.","title":"Status"},"group_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only members of this group id.","title":"Group Id"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_usersArguments","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_user":{"post":{"operationId":"get_user","summary":"Get one KnowBe4 user's profile and risk score by user id (no contact numbers). Use for \"Show KnowBe4 user 1234\".","description":"Get one KnowBe4 user's profile and risk score by user id (no contact numbers). Use for \"Show KnowBe4 user 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"user_id":{"description":"KnowBe4 user id (integer).","title":"User Id","type":"integer"}},"required":["region","user_id"],"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_phishing_campaigns":{"post":{"operationId":"list_phishing_campaigns","summary":"List phishing simulation campaigns with status, frequency, last phish-prone percentage and the security tests each has r","description":"List phishing simulation campaigns with status, frequency, last phish-prone percentage and the security tests each has run. Use for \"What phishing campaigns have we run in KnowBe4 and how did they do\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_phishing_campaignsArguments","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_phishing_security_tests":{"post":{"operationId":"list_phishing_security_tests","summary":"List phishing security tests (individual simulation sends) with aggregate counts of delivered, opened, clicked, reported","description":"List phishing security tests (individual simulation sends) with aggregate counts of delivered, opened, clicked, reported and data-entered. Use for \"How many people clicked in our latest KnowBe4 phishing test\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_phishing_security_testsArguments","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_training_campaigns":{"post":{"operationId":"list_training_campaigns","summary":"List security awareness training campaigns with status, dates, groups, content modules and completion percentage. Use fo","description":"List security awareness training campaigns with status, dates, groups, content modules and completion percentage. Use for \"Which KnowBe4 training campaigns are running and how complete are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"exclude_percentages":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Set true to leave out completion percentages, which makes the call much faster.","title":"Exclude Percentages"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_training_campaignsArguments","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_training_enrollments":{"post":{"operationId":"list_training_enrollments","summary":"List training enrollments with module, campaign, status, dates and time spent, filtered by campaign, module or user id. ","description":"List training enrollments with module, campaign, status, dates and time spent, filtered by campaign, module or user id. Names and emails are not returned. Use for \"Who has not completed the annual security awareness training in KnowBe4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"campaign_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only enrollments of this training campaign id.","title":"Campaign Id"},"store_purchase_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only enrollments of this training module (store purchase) id.","title":"Store Purchase Id"},"user_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only enrollments of this user id.","title":"User Id"},"exclude_archived_users":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Set true to leave out archived users.","title":"Exclude Archived Users"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_training_enrollmentsArguments","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_training_store_purchases":{"post":{"operationId":"list_training_store_purchases","summary":"List training content (modules, videos, policies) the account has purchased or has access to, with type, duration and re","description":"List training content (modules, videos, policies) the account has purchased or has access to, with type, duration and retirement status. Use for \"Which training modules does our KnowBe4 account include\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_training_store_purchasesArguments","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_training_policies":{"post":{"operationId":"list_training_policies","summary":"List the policies available for acknowledgement training with minimum reading time, default language and status. Use for","description":"List the policies available for acknowledgement training with minimum reading time, default language and status. Use for \"Which policies can we assign in KnowBe4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"KnowBe4 data centre of the account: us, eu, ca, uk or de (the console address is training.knowbe4.com for us, otherwise <region>.knowbe4.com).","enum":["us","eu","ca","uk","de"],"title":"Region","type":"string"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 500, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the page parameter is being retired by the vendor in favour of per_page).","title":"Page"}},"required":["region"],"title":"list_training_policiesArguments","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}}}}