openapi: 3.1.0
info:
  description: "Adaptive API for external integrations.\n\n## \uD83D\uDCCA API Overview\n\nThe Adaptive API enables organizations to build comprehensive reporting and analytics around their security awareness training programs. This RESTful API provides programmatic access to track employee training progress, monitor compliance, and generate insights about your organization's security training effectiveness.\n\n### Purpose & Use Cases\n\nThis API is designed for:\n- **Compliance Reporting**: Track training completion rates and identify employees with overdue trainings\n- **Progress Monitoring**: Get real-time visibility into individual and team training progress\n- **Data Integration**: Sync training data with your HRIS, BI tools, or custom dashboards\n- **Automated Workflows**: Build alerts and notifications for training milestones or compliance deadlines\n\n### Technical Design\n\nThe API follows REST principles with:\n- Resource-oriented URLs that clearly represent your data\n- Standard HTTP methods (GET for reading data)\n- JSON responses for easy parsing and integration\n- Consistent error handling with detailed error messages\n- Token-based authentication for secure access\n\n### Available Resources\n\n| Resource | Purpose | Common Use Cases |\n|----------|---------|------------------|\n| **Users** | Access employee directory data | • Export user lists for reporting<br>• Track user status changes<br>• Map users to departments |\n| **Training** | Monitor training campaigns and progress | • Track campaign completion rates<br>• Identify at-risk employees<br>• Generate compliance reports |\n\n## \uD83D\uDE80 Quick Start Guide\n\nGet started with the Adaptive API in just 3 steps:\n\n### Step 1: Get Your API Token\nSee [Authentication](#section/Authentication) for more details on how to generate and use API tokens.\n\n### Step 2: Make Your First API Call\n```bash\ncurl -X GET https://api.adaptivesecurity.com/v2/users \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n### Step 3: Handle the Response\n```json\n{\n  \"users\": [\n    {\n      \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n      \"email\": \"john.smith@example.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\",\n      \"status\": \"ACTIVE\"\n    }\n  ],\n  \"page_after\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n## \uD83D\uDD10 Authentication\n\nAll API endpoints require authentication using an API token:\n\n```http\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n**Token Management:**\n- Tokens are generated in the Admin portal under **Settings → API**\n- Tokens have a user-set expiration but can be revoked at any time\n- Store tokens securely - treat them like passwords\n## \uD83C\uDF10 Base URL\n\nAll API endpoints are relative to:\n```\nhttps://api.adaptivesecurity.com\n```\n\n## \uD83D\uDEA8 Error Handling\n\nAll API errors follow a consistent JSON structure:\n\n### Standard Error Response\n```json\n{\n  \"error_code\": \"RESOURCE_NOT_FOUND\",\n  \"message\": \"The requested user was not found\",\n  \"status_code\": 404,\n  \"request_id\": \"3e502c09-4fd3-42d3-8b3a-4e2f08de0bbf\"\n}\n```\n\n### Validation Error Response\n```json\n{\n  \"error_code\": \"VALIDATION_ERROR\",\n  \"message\": \"Request validation failed\",\n  \"status_code\": 400,\n  \"request_id\": \"1d7c1712-2b8e-43f4-90c6-1185e249bdf0\",\n  \"details\": [\n    {\n      \"field\": \"page\",\n      \"message\": \"Page must be a non-negative integer\"\n    }\n  ]\n}\n```\n\n### Error Code Reference\n| Code | Status | Description | Action |\n|------|--------|-------------|--------|\n| `INVALID_TOKEN` | 401 | Token is invalid or expired | Check token validity |\n| `RESOURCE_NOT_FOUND` | 404 | Resource doesn't exist | Verify resource ID |\n| `VALIDATION_ERROR` | 400 | Request validation failed | Check field errors |\n| `INTERNAL_SERVER_ERROR` | 500 | Server error | Contact support |\n\n## \uD83D\uDCCB Request & Response Headers\n\n### Required Request Headers\n```http\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n### Optional Request Headers\n```http\nAccept: application/json\nContent-Type: application/json  # Required for POST/PUT\n```\n\n### Response Headers\n```http\nX-Request-ID: 6acb3ce1-672a-4a49-8fa1-f1a994eef9fd\nContent-Type: application/json\n```\n\n## \uD83D\uDCC4 Pagination\n\nList endpoints return paginated results for optimal performance:\n\n- **Page cursor**: `page_after` field in the response to get the next page\n- **Default sorting**: By creation date (newest first)\n\n### Pagination Example\n```bash\n# Get the next page of users\ncurl -X GET \"https://api.adaptivesecurity.com/v2/users?page_after=5a6dce1e-8d0f-46b1-b263-50b6adca62da\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n### Pagination Response\n```json\n{\n  \"users\": [...],\n  \"page_after\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n## \uD83D\uDD50 Timestamps\n\nAll timestamps use ISO 8601 format in UTC:\n```\n2024-12-10T15:30:45.402Z\n```"
  title: Adaptive Audit Logs API
  version: v2
servers:
- url: https://api.adaptivesecurity.com
  description: Production API
security:
- bearer-token: []
tags:
- description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Admin audit log endpoints'
  name: Audit Logs
paths:
  /v2/audit-logs:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve a paginated list of admin audit logs. Supports filtering by date range and action types.'
      operationId: listAuditLogs
      parameters:
      - description: Page cursor for pagination
        example: 456e7890-f12b-34c5-d678-901234567890
        in: query
        name: page_after
        required: false
        schema:
          type: string
      - description: Number of results per page (max 1000)
        example: 100
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 100
      - description: Filter audit logs from this date (inclusive, ISO 8601 format)
        example: '2024-01-01T00:00:00Z'
        in: query
        name: start_date
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter audit logs until this date (inclusive, ISO 8601 format)
        example: '2024-12-31T23:59:59Z'
        in: query
        name: end_date
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter by specific action types (e.g., CREATED_TRAINING_CAMPAIGN, SCHEDULED_TRAINING_CAMPAIGN, ADDED_ADMIN)
        example:
        - CREATED_TRAINING_CAMPAIGN
        - SCHEDULED_TRAINING_CAMPAIGN
        in: query
        name: actions
        required: false
        schema:
          type: array
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    audit_logs:
                    - id: 123e4567-e89b-12d3-a456-426614174000
                      actor:
                        id: a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6
                        email: admin@example.com
                        role: ACCOUNT_OWNER
                      action: CREATED_TRAINING_CAMPAIGN
                      category: SAT_PROGRAM
                      subcategory: TRAINING
                      occurred_at: '2024-12-01T14:30:00Z'
                      message: Created training campaign.
                      success: true
                    - id: 456e7890-f12b-34c5-d678-901234567890
                      actor:
                        id: b2c3d4e5-f6a7-8b9c-0d1e-f2a3b4c5d6e7
                        email: security@example.com
                        role: TEAM_ADMIN
                      action: SCHEDULED_TRAINING_CAMPAIGN
                      category: SAT_PROGRAM
                      subcategory: TRAINING
                      occurred_at: '2024-11-28T09:15:00Z'
                      message: Scheduled training campaign.
                      success: true
                    page_after: 456e7890-f12b-34c5-d678-901234567890
              schema:
                $ref: '#/components/schemas/AuditLogListResponseDto'
          description: Successfully retrieved audit logs
        '400':
          content:
            application/json:
              examples:
                Validation Error:
                  description: Validation Error
                  value:
                    error_code: VALIDATION_ERROR
                    message: Request validation failed
                    status_code: 400
                    request_id: 5f8e9a7b-1c2d-3e4f-5a6b-7c8d9e0f1a2b
                    details:
                    - field: actions
                      message: 'Invalid action value: INVALID_ACTION'
              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: dcaf9f7e-6c47-4c93-bb41-0e2d8d9bb0de
              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: b7c1196e-2c6e-4d17-8f3c-fcb62d6d27a2
              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: f351ac3c-cd5e-4ec7-89dc-191fc40a83f2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: List audit logs
      tags:
      - Audit Logs
  /v2/audit-logs/{auditLogId}:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve detailed information about a specific audit log entry'
      operationId: getAuditLog
      parameters:
      - description: Audit log ID
        example: 123e4567-e89b-12d3-a456-426614174000
        in: path
        name: auditLogId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    id: 123e4567-e89b-12d3-a456-426614174000
                    actor:
                      id: a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6
                      email: admin@example.com
                      role: ACCOUNT_OWNER
                    action: CREATED_TRAINING_CAMPAIGN
                    category: SAT_PROGRAM
                    subcategory: TRAINING
                    occurred_at: '2024-12-01T14:30:00Z'
                    message: Created training campaign.
                    success: true
              schema:
                $ref: '#/components/schemas/AuditLogDto'
          description: Successfully retrieved audit log details
        '400':
          content:
            application/json:
              examples:
                Validation Error:
                  description: Validation Error
                  value:
                    error_code: VALIDATION_ERROR
                    message: Request validation failed
                    status_code: 400
                    request_id: 5f8e9a7b-1c2d-3e4f-5a6b-7c8d9e0f1a2b
                    details:
                    - field: auditLogId
                      message: Invalid UUID format
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Bad request - Invalid audit log ID format
        '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 audit log was not found
                    status_code: 404
                    request_id: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Audit log not found
        '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: b7c1196e-2c6e-4d17-8f3c-fcb62d6d27a2
              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: f351ac3c-cd5e-4ec7-89dc-191fc40a83f2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get audit log details
      tags:
      - Audit Logs
components:
  schemas:
    AuditLogListResponseDto:
      type: object
      description: Paginated list of admin audit logs
      properties:
        audit_logs:
          type: array
          description: List of audit log entries
          items:
            $ref: '#/components/schemas/AuditLogDto'
        page_after:
          type: string
          description: Cursor for the next page of results. Null if this is the last page
          example: 456e7890-f12b-34c5-d678-901234567890
    AuditLogDto:
      type: object
      description: Admin audit log entry
      properties:
        action:
          type: string
          description: The action that was performed
          example: CREATED_TRAINING_CAMPAIGN
        actor:
          $ref: '#/components/schemas/AuditLogActingAdminDto'
          description: The admin who performed the action
        category:
          type: string
          description: Category of the action
          example: SAT_PROGRAM
        id:
          type: string
          description: Unique identifier for the audit log entry
          example: 123e4567-e89b-12d3-a456-426614174000
        message:
          type: string
          description: Human-readable description of the action
          example: Created training campaign.
        occurred_at:
          type: string
          format: date-time
          description: When the action occurred (ISO 8601 format)
          example: '2024-12-01T14:30:00Z'
        subcategory:
          type: string
          description: Subcategory of the action
          example: TRAINING
        success:
          type: boolean
          description: Whether the action was successful
          example: true
    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
    AuditLogActingAdminDto:
      type: object
      description: Information about the admin who performed the action
      properties:
        email:
          type: string
          description: Email address of the admin
          example: admin@example.com
        id:
          type: string
          description: Unique identifier for the admin
          example: a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6
        role:
          type: string
          description: Role of the admin
          example: ACCOUNT_OWNER
    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
    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
  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