Adaptive Security Training API

openapi: 3.2.0
info:
  description: 'Adaptive API for external integrations. ## 📊 API Overview


    The Adaptive API gives your organization programmatic access to its Adaptive data. Use this RESTful API to report on security awareness training and phishing simulations, sync users and groups with your other systems, review admin activity, and act on email security detections. ### Purpose & Use Cases


    This API is designed for:

    - **Compliance Reporting**: Track training completion rates and identify employees with overdue trainings

    - **Progress Monitoring**: Get real-time visibility into individual and team training progress

    - **Data Integration**: Sync training data with your HRIS, BI tools, or custom dashboards

    - **Automated Workflows**: Build alerts and notifications for training milestones or compliance deadlines


    ### Technical Design


    The API follows REST principles with:

    - Resource-oriented URLs that clearly represent your data

    - Standard HTTP methods

    - JSON responses for easy parsing and integration

    - Consistent error handling with detailed error messages

    - Token-based authentication for secure access


    ### Available Resources


    | Resource | Purpose | Common Use Cases |

    |----------|---------|------------------|

    | **Users** | Access employee directory data | • Export user lists for reporting

    • Track user status changes

    • Map users to departments |

    | **Groups** | Access user groups and their members | • Map users to the groups campaigns target

    • Sync group membership with your directory or HRIS |

    | **Training** | Monitor training campaigns and progress | • Track campaign completion rates

    • Identify at-risk employees

    • Generate compliance reports |

    | **Phishing** | Monitor phishing campaigns, simulations, and per-user results | • Track click, report, and failure rates

    • Identify users who failed a simulation

    • Report on campaign outcomes |

    | **Audit Logs** | Review admin actions taken in Adaptive | • Send admin activity to your SIEM

    • Review configuration changes for compliance |

    | **Email Security** | Act on detected security events and manage sender rules | • Pull detection details into an investigation

    • Remediate, or undo the remediation of, a malicious email from a SOAR playbook

    • Manage sender allow and deny lists |

    | **Webhooks** | Receive events as they happen instead of polling | • Trigger SIEM detections and SOAR playbooks

    • React to failed simulations, completed or overdue training, and new security events |


    ## 🚀 Quick Start Guide


    Get started with the Adaptive API in just 3 steps:


    ### Step 1: Get Your API Token

    See Authentication for more details on how to generate and use API tokens. ### Step 2: Make Your First API Call

    ```bash

    curl -X GET https://api.adaptivesecurity.com/v2/users \

    -H "Authorization: Bearer YOUR_API_TOKEN"

    ```


    ### Step 3: Handle the Response

    ```json

    {

    "users": [

    {

    "id": "123e4567-e89b-12d3-a456-426614174000",

    "email": "john.smith@example.com",

    "first_name": "John",

    "last_name": "Smith",

    "status": "ACTIVE"

    }

    ],

    "page_after": "123e4567-e89b-12d3-a456-426614174000"

    }

    ```


    ## 🔐 Authentication


    All API endpoints require authentication using an API token:


    ```http

    Authorization: Bearer YOUR_API_TOKEN

    ```


    **Token Management:**

    - Tokens are generated in the Admin portal under **Settings → API**

    - Tokens have a user-set expiration but can be revoked at any time

    - Store tokens securely - treat them like passwords


    **Permissions:**


    Tokens are assigned permissions that limit the scope of the actions they can be used to take. You can choose the permissions a token is assigned when it''s created and edit them after creation. Each endpoint''s documentation lists which permissions are required to use it. As a best practice, only grant tokens the permissions they need and nothing more. For example, if only using the API to read data, don''t grant your token `:write`-level permissions.'
  title: Adaptive Training API
  version: v2
servers:
- url: https://api.adaptivesecurity.com
  description: Production API
security:
- bearer-token: []
tags:
- description: Training campaign and activity endpoints
  name: Training
paths:
  /v2/training/campaigns:
    get:
      description: 'Retrieve a paginated list of training campaigns


        **Required permission:** `training:read`'
      operationId: listTrainingCampaigns
      parameters:
      - description: Page cursor
        example: 6e8e3c89-1122-4db2-ae91-f2c6bc0d5639
        in: query
        name: page_after
        required: false
        schema:
          type: string
      - description: Page size
        example: 100
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 100
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    campaigns:
                    - id: 2db2730a-3a9d-4b3d-87b4-1d16e1e66a88
                      name: Engineering Annual Training
                      employee_title: 2024 Security Awareness Training
                      audience_type: GROUPS
                      groups:
                      - id: f95d3d85-284b-4f94-98fe-23914c805b88
                        name: Engineering Team
                      mode: SCHEDULED
                      status: IN_PROGRESS
                      created_at: '2025-01-01T13:19:13.402Z'
                      start_date: '2025-01-10T13:19:13.402Z'
                      end_date: '2025-04-10T13:19:13.402Z'
                    - id: 6e8e3c89-1122-4db2-ae91-f2c6bc0d5639
                      name: New Employee Onboarding
                      audience_type: ALL_USERS
                      groups: []
                      mode: TRIGGERED
                      status: IN_PROGRESS
                      created_at: '2025-06-15T08:00:00Z'
                      start_date: '2025-06-15T08:00:00Z'
                    page_after: 6e8e3c89-1122-4db2-ae91-f2c6bc0d5639
              schema:
                $ref: '#/components/schemas/TrainingCampaignListResponseDto'
          description: Successfully retrieved training campaigns
        '400':
          content:
            application/json:
              examples:
                Validation Error:
                  description: Validation Error
                  value:
                    error_code: VALIDATION_ERROR
                    message: Request validation failed
                    status_code: 400
                    request_id: 2f6f683d-c3e3-44c3-8ee2-b06b5687f255
                    details:
                    - field: page_after
                      message: page_after must be a string
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Bad request - Invalid parameters
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: 74fc4c18-2c80-4394-b2e2-2f137b237b92
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '429':
          content:
            application/json:
              examples:
                Rate Limit Error:
                  description: Rate Limit Error
                  value:
                    error_code: RATE_LIMIT_EXCEEDED
                    message: API rate limit exceeded. Please retry after some time
                    status_code: 429
                    request_id: 0d47b5d3-884b-42c5-a20a-04e47011ebf4
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Too many requests - Rate limit exceeded
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: f7e20a42-3c64-4f45-8a87-76113a1ce2f0
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: List training campaigns
      tags:
      - Training
  /v2/training/campaigns/enrollments:
    get:
      description: 'Retrieve details about training enrollments with campaign and user filters


        **Required permission:** `training:read`'
      operationId: getTrainingCampaignEnrollments
      parameters:
      - description: User ID
        example: 123e4567-e89b-12d3-a456-426614174000
        in: query
        name: user_id
        required: false
        schema:
          type:
          - string
          - 'null'
      - description: Training campaign ID
        example: c143c964-d39b-4f0f-b3d3-07bb3aaae71e
        in: query
        name: campaign_id
        required: false
        schema:
          type:
          - string
          - 'null'
      - description: Page cursor
        example: f248c6c3-9c93-4d62-a41b-9843de18f56b
        in: query
        name: page_after
        required: false
        schema:
          type:
          - string
          - 'null'
      - description: Number of enrollments to return per page (max 1000)
        example: 100
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 100
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    enrollments:
                    - id: 5a6dce1e-8d0f-46b1-b263-50b6adca62da
                      user:
                        id: 123e4567-e89b-12d3-a456-426614174000
                        email: john.smith@example.com
                      campaign:
                        id: e7f89a36-4b8f-4865-b11a-b0f280ae6a34
                        name: Q4 Security Training
                        employee_title: 2024 Security Awareness Training
                      status: IN_PROGRESS
                      enrolled_at: '2024-10-05T09:15:00Z'
                      due_at: '2024-10-12T09:20:00Z'
                      started_at: '2024-10-05T09:20:00Z'
                      has_acknowledged_policy: true
                      acknowledged_policies:
                      - policy_id: 0c1f6a4e-7d2b-4f8a-9b3e-2a6d5c8e1f47
                        policy_version_id: 8d3b2e91-5c4a-4e6f-a7b8-9c0d1e2f3a4b
                        title: Acceptable Use Policy
                        version_number: 3
                        acknowledged_at: '2024-10-05T09:32:00Z'
                    page_after: 5a6dce1e-8d0f-46b1-b263-50b6adca62da
              schema:
                $ref: '#/components/schemas/UserTrainingCampaignEnrollmentListDto'
          description: Successfully retrieved campaign enrollment details
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: 5a7384c9-b5de-4aa1-a144-faa0de243ab0
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '429':
          content:
            application/json:
              examples:
                Rate Limit Error:
                  description: Rate Limit Error
                  value:
                    error_code: RATE_LIMIT_EXCEEDED
                    message: API rate limit exceeded. Please retry after some time
                    status_code: 429
                    request_id: 6e9d2fb1-95e2-49e2-ae36-9de6e6f51c25
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Too many requests - Rate limit exceeded
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: a0a7b8e0-fc0b-46b1-8dbb-0d04872f9678
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get training campaign enrollments details
      tags:
      - Training
  /v2/training/campaigns/{campaignId}:
    get:
      description: 'Retrieve detailed information about a specific training campaign


        **Required permission:** `training:read`'
      operationId: getTrainingCampaign
      parameters:
      - description: Campaign ID
        example: e7f89a36-4b8f-4865-b11a-b0f280ae6a34
        in: path
        name: campaignId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    id: 88479a0e-6ef4-4bc9-9af1-d57bae0f1234
                    name: Engineering Annual Training
                    employee_title: 2024 Security Awareness Training
                    audience_type: GROUPS
                    groups:
                    - id: 12345654-4321-1234-9abc-def012345678
                      name: Engineers
                    mode: SCHEDULED
                    status: IN_PROGRESS
                    created_at: '2025-06-01T13:19:13.402Z'
                    start_date: '2025-06-10T13:19:13.402Z'
                    end_date: '2025-08-10T13:19:13.402Z'
              schema:
                $ref: '#/components/schemas/TrainingCampaignDto'
          description: Successfully retrieved training campaign details
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: dcaf9f7e-6c47-4c93-bb41-0e2d8d9bb0de
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '404':
          content:
            application/json:
              examples:
                Not Found Error:
                  description: Not Found Error
                  value:
                    error_code: RESOURCE_NOT_FOUND
                    message: The requested training campaign was not found
                    status_code: 404
                    request_id: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Training campaign not found
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: f351ac3c-cd5e-4ec7-89dc-191fc40a83f2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get training campaign details
      tags:
      - Training
components:
  schemas:
    UserSummaryDto:
      type: object
      description: User summary information
      properties:
        email:
          type: string
          description: User's email address
          example: john.smith@example.com
        id:
          type: string
          description: Unique identifier for the user
          example: 123e4567-e89b-12d3-a456-426614174000
    ErrorResponseDto:
      type: object
      description: Standard error response format for all API errors
      properties:
        error_code:
          type: string
          description: Machine-readable error code
          example: RESOURCE_NOT_FOUND
        message:
          type: string
          description: Human-readable error message
          example: The requested user was not found
        request_id:
          type: string
          description: Unique request ID for debugging
          example: 8f03bdf9-ac45-4279-8dbe-f28839c2fed3
        status_code:
          type: integer
          format: int32
          description: HTTP status code
          example: 404
      required:
      - error_code
      - message
      - request_id
      - status_code
    ValidationErrorResponseDto:
      type: object
      description: Error response for validation failures with field-level details
      properties:
        details:
          type: array
          description: List of field-level validation error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
        error_code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Request validation failed
        request_id:
          type: string
          description: Unique request ID for debugging
          example: 8f03bdf9-ac45-4279-8dbe-f28839c2fed3
        status_code:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
      required:
      - details
      - error_code
      - message
      - request_id
      - status_code
    TrainingCampaignListResponseDto:
      type: object
      description: Paginated list of training campaigns
      properties:
        campaigns:
          type: array
          items:
            $ref: '#/components/schemas/TrainingCampaignDto'
        page_after:
          type:
          - string
          - 'null'
          example: 123e4567-e89b-12d3-a456-426614174000
    TrainingCampaignDto:
      type: object
      description: Training campaign information
      properties:
        audience_type:
          type: string
          description: Target audience type for the campaign
          enum:
          - GROUPS
          - ALL_USERS
          example: GROUPS
        created_at:
          type: string
          format: date-time
          description: Campaign's created date
          example: '2025-01-01T13:19:13.402Z'
        employee_title:
          type:
          - string
          - 'null'
          description: Employee-facing title for the campaign. Null if no employee-facing title is set.
          example: 2024 Annual Security Training
        end_date:
          type:
          - string
          - 'null'
          format: date-time
          description: End date for the campaign (null for TRIGGERED mode)
          example: '2025-01-01T13:19:13.402Z'
        groups:
          type: array
          description: Groups associated with the campaign
          items:
            $ref: '#/components/schemas/CampaignGroupDto'
        id:
          type: string
          description: Unique identifier for the campaign
          example: e7f89a36-4b8f-4865-b11a-b0f280ae6a34
        mode:
          type: string
          description: Campaign mode
          enum:
          - SCHEDULED
          - TRIGGERED
          example: SCHEDULED
        name:
          type: string
          description: Name of the training campaign
          example: Engineering Annual Training
        start_date:
          type: string
          format: date-time
          description: Start date for the campaign
          example: '2025-01-01T13:19:13.402Z'
        status:
          type: string
          description: Current status of the campaign
          enum:
          - DRAFT
          - SCHEDULED
          - IN_PROGRESS
          - COMPLETED
          - OVERDUE
          example: IN_PROGRESS
    CampaignGroupDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the group
          example: e7f89a36-4b8f-4865-b11a-b0f280ae6a34
        name:
          type: string
          description: The name of the group
          example: Finance Team
    UserTrainingCampaignEnrollmentListDto:
      type: object
      properties:
        enrollments:
          type: array
          items:
            $ref: '#/components/schemas/UserTrainingCampaignEnrollmentDto'
        page_after:
          type:
          - string
          - 'null'
          example: 3b495a63-23f2-4284-82d0-3aa5b5c0c753
    UserTrainingCampaignEnrollmentDto:
      type: object
      description: User's enrollment details for a training campaign
      properties:
        acknowledged_policies:
          type: array
          description: Policies the user acknowledged in this enrollment, most recent first. Each policy appears once, with its latest acknowledgment.
          items:
            $ref: '#/components/schemas/AcknowledgedPolicyDto'
        campaign:
          $ref: '#/components/schemas/TrainingCampaignSummaryDto'
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2025-01-01T13:19:13.402Z'
        due_at:
          type: string
          format: date-time
          description: Date when the user's training completion is due
          example: '2025-01-08T13:19:13.402Z'
        enrolled_at:
          type: string
          format: date-time
          example: '2025-01-01T13:19:13.402Z'
        has_acknowledged_policy:
          type:
          - boolean
          - 'null'
          example: false
        id:
          type: string
          description: Unique identifier for the enrollment
          example: 6a10d54c-f1bf-4d1d-8864-64bfac9a0c13
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Date when user started the training
          example: '2025-01-01T13:19:13.402Z'
        status:
          type: string
          description: User's enrollment status in the training campaign
          enum:
          - IN_PROGRESS
          - COMPLETED
          - INCOMPLETE
          - OVERDUE
          - UNENROLLED
          example: IN_PROGRESS
        unenrolled_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2025-01-02T13:19:13.402Z'
        user:
          $ref: '#/components/schemas/UserSummaryDto'
    AcknowledgedPolicyDto:
      type: object
      description: A policy the user acknowledged as part of a training campaign enrollment
      properties:
        acknowledged_at:
          type: string
          format: date-time
          description: Date when the user acknowledged the policy
          example: '2025-01-03T10:42:17.120Z'
        policy_id:
          type: string
          description: Unique identifier for the policy
          example: 0c1f6a4e-7d2b-4f8a-9b3e-2a6d5c8e1f47
        policy_version_id:
          type: string
          description: Unique identifier for the policy version the user acknowledged
          example: 8d3b2e91-5c4a-4e6f-a7b8-9c0d1e2f3a4b
        title:
          type: string
          description: Title of the acknowledged policy version
          example: Acceptable Use Policy
        version_number:
          type: integer
          format: int64
          description: Version number of the acknowledged policy version
          example: 3
    ErrorDetail:
      type: object
      description: Field-level validation error details
      properties:
        field:
          type: string
          description: Field name that failed validation
          example: email
        message:
          type: string
          description: Validation error message for this field
          example: Email address is not valid
      required:
      - field
      - message
    TrainingCampaignSummaryDto:
      type: object
      description: Training campaign information
      properties:
        employee_title:
          type:
          - string
          - 'null'
          description: Employee-facing title for the campaign. Null if no employee-facing title is set.
          example: 2024 Annual Security Training
        id:
          type: string
          description: Unique identifier for the campaign
          example: e7f89a36-4b8f-4865-b11a-b0f280ae6a34
        name:
          type: string
          description: Name of the training campaign
          example: Engineering Annual Training
  securitySchemes:
    bearer-token:
      description: 'API authentication token obtained from the Adaptive Admin portal (Settings → API Tokens). Include the token in the Authorization header as: Bearer YOUR_TOKEN'
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Adaptive Security
  source: https://developer.adaptivesecurity.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)