Static API Reference
SiberMate API Reference.
Generated from the same OpenAPI contract as the interactive docs, but readable without JavaScript.
How to authenticate
Send a tenant API key as Authorization: Bearer <API_KEY>. All business endpoints are scoped to the organization associated with that key.
System
Operational checks and machine-readable API metadata.
GET /health
Check API availability.
Returns a lightweight status response that can be used by uptime checks and deployment monitors.
GET /openapi.json
Retrieve the OpenAPI document.
Returns this OpenAPI document for tooling, SDK generation, and documentation workflows.
GET /ready
Check deployment readiness.
Returns whether the API is configured for serving traffic. This check does not validate tenant API keys, organization data access, or external service connectivity.
Company
Organization profile, plan summary, and enabled SiberMate modules.
GET /companies
List child tenant companies (MSP/Distributor only).
Returns the child tenant companies managed by the authenticated MSP or Distributor account. Non-MSP API keys receive 403. Use the returned company id as the companyId query parameter on other read endpoints to access a specific tenant's data. This endpoint returns data for the organization associated with the authenticated API key.
GET /company
Retrieve organization profile.
Returns the authenticated organization profile, plan summary, and enabled SiberMate modules. This endpoint returns data for the organization associated with the authenticated API key.
GET /company/features
Retrieve enabled SiberMate modules.
Returns enabled SiberMate modules and Breach Pro monitored-domain settings. This endpoint returns data for the organization associated with the authenticated API key.
Learners
Learner records, lifecycle actions, group membership, and learner-level outcomes.
GET /learners
List learners.
Returns learner records for the authenticated organization. Use this endpoint to sync learner rosters, status, group membership, and risk-level indicators into client systems. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
POST /learners
Create a learner.
Creates one learner in the authenticated organization. Email is required, free-email providers are rejected, and when domain lock is enabled the email must be on the company domain. Include group IDs when the learner should be added to existing learner groups during creation. Email-less ("User ID") learners — for people without an email who use the User ID Access Portal — cannot be created through this API and must be added via the dashboard. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| yes | string | |
| firstName | yes | string |
| lastName | yes | string |
| groupIds | no | array<string> |
| externalLearnerId | no | string |
| locale | no | string |
| excludedFromAutoEnrol | no | boolean |
DELETE /learners/{learnerId}
Delete a learner.
Deletes a learner from the authenticated organization. Use this only when the learner should be permanently removed from SiberMate workflows. This endpoint changes organization data and should be called only from trusted server-side systems.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
GET /learners/{learnerId}
Retrieve learner details.
Returns a single learner record, including profile fields, active status, locale, group membership, and available risk-level indicators. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
PATCH /learners/{learnerId}
Update a learner.
Updates learner profile fields and optional group membership. Use this endpoint for HRIS or identity-driven learner profile synchronization. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| no | string | |
| firstName | yes | string |
| lastName | yes | string |
| groupIds | no | array<string> |
| externalLearnerId | no | string |
| locale | no | string |
| excludedFromAutoEnrol | no | boolean |
GET /learners/{learnerId}/breaches
Retrieve learner breach exposure.
Returns breach exposure linked to a single learner when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
GET /learners/{learnerId}/course-results
Retrieve learner course results.
Returns course-level training results for a learner, including enrolment, start, completion, score, and grade fields when available. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
GET /learners/{learnerId}/gap-analysis-results
Retrieve learner gap analysis results.
Returns gap analysis results for a learner so client systems can inspect assessment progress and outcomes. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
PUT /learners/{learnerId}/groups
Replace learner group membership.
Replaces the full set of groups assigned to a learner. Send the complete desired group list, not only the groups being added. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| groupIds | yes | array<string> |
GET /learners/{learnerId}/policy-results
Retrieve learner policy results.
Returns policy acknowledgement results for a learner. Optionally filter by policyId for a single policy. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| policyId | query | no | string |
| companyId | query | no | string |
GET /learners/{learnerId}/simulation-queue
Retrieve learner simulation queue.
Returns pending or queued phishing simulation activity for a learner when available. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
GET /learners/{learnerId}/simulation-results
Retrieve learner simulation results.
Returns phishing simulation activity for a learner, suitable for learner-level security awareness reporting. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | path | yes | string |
| companyId | query | no | string |
POST /learners/activate
Activate learners.
Reactivates learners so they can receive training, policy, phishing simulation, and reporting workflows again. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
DELETE /learners/bulk
Delete learners in bulk.
Deletes multiple learners in a single request. Use this only for controlled offboarding or organization cleanup workflows. This endpoint changes organization data and should be called only from trusted server-side systems.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
POST /learners/bulk
Create learners in bulk.
Creates one or more learners in a single request for roster import or bulk synchronization. Email is required for every learner (same rules as POST /learners). externalLearnerId is an optional HRIS/source identifier for emailed learners. Email-less ("User ID") learners cannot be created through this API — add them via the dashboard. This endpoint changes organization data and should be called only from trusted server-side systems.
Request body
| Field | Required | Type |
|---|---|---|
| learners | yes | array<object> |
| learners[].email | yes | string |
| learners[].firstName | yes | string |
| learners[].lastName | yes | string |
| learners[].groupIds | no | array<string> |
| learners[].externalLearnerId | no | string |
POST /learners/deactivate
Deactivate learners.
Deactivates learners without deleting their historical results. Use this for temporary leave, offboarding holds, or staged cleanup workflows. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
Groups
Learner groups and group manager assignments.
POST /group-membership/move
Move learners from one group to another.
Move learners from one group to another. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| fromGroupId | yes | string |
| toGroupId | yes | string |
| learnerIds | no | array<string> |
| preserveManagerRole | no | boolean |
GET /groups
List learner groups.
List learner groups. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
POST /groups
Create a learner group.
Creates a learner group and optionally assigns group managers. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| name | yes | string |
| managerIds | no | array<string> |
DELETE /groups/{groupId}
Delete a learner group.
Deletes a learner group from the organization. Confirm downstream automations no longer depend on the group before deletion. This endpoint changes organization data and should be called only from trusted server-side systems.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| groupId | path | yes | string |
GET /groups/{groupId}
Retrieve group details.
Retrieve group details. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| groupId | path | yes | string |
| companyId | query | no | string |
POST /groups/{groupId}/learners/add
Add learners to a group, keeping their existing groups.
Add learners to a group, keeping their existing groups. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| groupId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
POST /groups/{groupId}/learners/remove
Remove learners from a group, keeping their other groups.
Remove learners from a group, keeping their other groups. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| groupId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
PUT /groups/{groupId}/managers
Replace group managers.
Replaces the manager list for a learner group. Send the complete desired manager list. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| groupId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| managerIds | yes | array<string> |
Courses
Training catalog, course assignments, reminders, unenrollments, and gap analysis actions.
POST /course-enrollments
Assign courses to learners.
Assigns one or more courses to one or more learners. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| courseIds | yes | array<string> |
| learnerIds | yes | array<string> |
POST /course-reminders
Send course reminders.
Sends reminders to learners with outstanding course work. This is exposed separately from course assignment for clearer client automation. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| courseIds | yes | array<string> |
| learnerIds | yes | array<string> |
POST /course-unenrollments
Remove course assignments.
Removes course assignments from learners when they should no longer complete those courses. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| courseIds | yes | array<string> |
| learnerIds | yes | array<string> |
GET /courses
List training courses.
Returns managed catalog courses and courses owned by the authenticated organization. Courses owned by other tenants are filtered out even if the upstream catalog endpoint returns them. Use source to separate managed catalog courses from organization-created courses, and type to separate standard training from gap analysis courses. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| type | query | no | "all" | "training" | "gap_analysis" |
| source | query | no | "all" | "managed" | "custom" |
| excludeGapAnalysis | query | no | boolean |
GET /courses/{courseId}
Retrieve course details.
Returns a global catalog course or a course owned by the authenticated organization. Courses owned by another tenant return 404. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| courseId | path | yes | string |
POST /gap-analysis/enrollments
Assign gap analysis to learners.
Assigns gap analysis to learners. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
POST /gap-analysis/reminders
Send gap analysis reminders.
Sends reminders to learners with outstanding gap analysis work. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
POST /gap-analysis/unenrollments
Remove gap analysis assignments.
Removes gap analysis assignments from learners. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| learnerIds | yes | array<string> |
Reports
Organization-level learning, participation, risk score, course result, and gap analysis reports.
GET /reports/course-participation
Retrieve course participation report.
Retrieve course participation report. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
GET /reports/course-results
Retrieve course results report.
Retrieve course results report. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
GET /reports/gap-analysis-results
Retrieve gap analysis results report.
Retrieve gap analysis results report. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
GET /reports/learning
Retrieve learning report.
Returns organization-level learning report data for executive dashboards, periodic exports, or internal compliance reporting. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| learnerId | query | no | string |
| courseId | query | no | string |
| companyId | query | no | string |
GET /reports/risk-score-history
Retrieve risk score history.
Returns historical risk score data for the requested date range. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| fromDate | query | no | string:date |
| toDate | query | no | string:date |
| companyId | query | no | string |
Policies
Policy library, PDF upload, draft publishing, assignments, reminders, removals, and templates.
GET /policies
List policies.
List policies. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| publishedOnly | query | no | boolean |
| pdfOnly | query | no | boolean |
| companyId | query | no | string |
POST /policies
Create a policy.
Creates a policy as a draft or live policy, depending on the submitted action. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| name | yes | string |
| pdfFile | yes | string |
| action | yes | string |
| majorVersion | no | integer |
| minorVersion | no | integer |
| category | no | string |
| ownerName | no | string |
| ownerEmail | no | string |
| isPublic | no | boolean |
| signatureSettings | no | object |
| signatureSettings.type | yes | "fixed" | "lastSignature" | "newUsers" | "none" |
| signatureSettings.startDate | no | string:date |
| signatureSettings.intervalLength | no | integer |
| signatureSettings.intervalUnit | no | "months" | "years" |
| signatureSettings.useDefault | no | boolean |
| signatureSettings.setDefault | no | boolean |
GET /policies/{policyId}
Retrieve policy details.
Retrieve policy details. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| policyId | path | yes | string |
| companyId | query | no | string |
PATCH /policies/{policyId}
Update a policy.
Updates an existing policy. Use draft and publish endpoints when you need a controlled policy review workflow. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| policyId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| name | no | string |
| pdfFile | no | string |
| action | yes | string |
| major | no | boolean |
| category | no | string |
| ownerName | no | string |
| ownerEmail | no | string |
| isPublic | no | boolean |
| resend | no | boolean |
| signatureSettings | no | object |
| signatureSettings.type | yes | "fixed" | "lastSignature" | "newUsers" | "none" |
| signatureSettings.startDate | no | string:date |
| signatureSettings.intervalLength | no | integer |
| signatureSettings.intervalUnit | no | "months" | "years" |
| signatureSettings.useDefault | no | boolean |
| signatureSettings.setDefault | no | boolean |
POST /policies/{policyId}/discard-draft
Discard a policy draft.
Discards the current draft version and keeps the existing live policy unchanged. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| policyId | path | yes | string |
POST /policies/{policyId}/publish-draft
Publish a policy draft.
Publishes the current draft version of a policy. This endpoint changes organization data and requires an authorized bearer token.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| policyId | path | yes | string |
Request body
| Field | Required | Type |
|---|---|---|
| major | no | boolean |
| resend | no | boolean |
DELETE /policies/bulk
Delete policies in bulk.
Delete policies in bulk. This endpoint changes organization data and should be called only from trusted server-side systems.
Request body
| Field | Required | Type |
|---|---|---|
| policyIds | yes | array<string> |
POST /policies/from-template
Create a policy from a template.
Creates an organization policy from a SiberMate policy template. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| policyTemplateId | yes | string |
| name | no | string |
| action | yes | string |
| majorVersion | no | integer |
| minorVersion | no | integer |
| category | no | string |
| ownerName | no | string |
| ownerEmail | no | string |
| isPublic | no | boolean |
| signatureSettings | no | object |
| signatureSettings.type | yes | "fixed" | "lastSignature" | "newUsers" | "none" |
| signatureSettings.startDate | no | string:date |
| signatureSettings.intervalLength | no | integer |
| signatureSettings.intervalUnit | no | "months" | "years" |
| signatureSettings.useDefault | no | boolean |
| signatureSettings.setDefault | no | boolean |
POST /policies/upload
Upload a policy PDF.
Uploads a policy PDF and returns the file reference used when creating or updating policy records. This endpoint changes organization data and should be called only from trusted server-side systems.
Request body
| Field | Required | Type |
|---|---|---|
| file | yes | string:binary |
POST /policy-assignments
Assign policies to learners.
Assigns one or more policies to one or more learners. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| policyIds | yes | array<string> |
| learnerIds | yes | array<string> |
POST /policy-reminders
Send policy reminders.
Sends reminders to learners with outstanding policy acknowledgements. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| policyIds | yes | array<string> |
| learnerIds | yes | array<string> |
POST /policy-removals
Remove policy assignments.
Removes learners from one or more policy assignments. This endpoint changes organization data and requires an authorized bearer token.
Request body
| Field | Required | Type |
|---|---|---|
| policyIds | yes | array<string> |
| learnerIds | yes | array<string> |
GET /policy-templates
List policy templates.
Returns available policy templates that can be used to create organization policies. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| restrictToOwn | query | no | boolean |
| publishedOnly | query | no | boolean |
| pdfOnly | query | no | boolean |
| companyId | query | no | string |
GET /policy-templates/{policyTemplateId}
Retrieve policy template details.
Retrieve policy template details. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| policyTemplateId | path | yes | string |
| companyId | query | no | string |
Simulations
Phishing simulation campaigns, metrics, and learner-level simulation activity.
GET /simulations
List phishing simulations.
List phishing simulations. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
GET /simulations/{simulationId}
Retrieve phishing simulation details.
Retrieve phishing simulation details. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| simulationId | path | yes | string |
| companyId | query | no | string |
GET /simulations/metrics
Retrieve phishing simulation metrics.
Returns aggregate phishing simulation metrics for organization-level reporting. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| companyId | query | no | string |
Breaches
Breach exposure insights for monitored accounts and affected services.
GET /breaches/accounts
List exposed accounts.
Returns exposed account data when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| accountType | query | no | "activeLearner" | "inactiveLearner" | "nonLearner" | "employee" |
| companyId | query | no | string |
GET /breaches/services
List breached services.
Returns breached services and affected-account counts when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.
Parameters
| Name | Location | Required | Type |
|---|---|---|---|
| hasAffectedAccounts | query | no | boolean |
| accountType | query | no | "activeLearner" | "inactiveLearner" | "nonLearner" | "employee" |
| companyId | query | no | string |
Markdown mirror
The crawler-friendly Markdown version is available at /api-reference.md.
Markdown length: 81,551 characters.