openapi: 3.0.3
info:
  title: ModernPentest API
  description: |
    REST API for ModernPentest - AI-Powered Automated Penetration Testing Platform.

    This API allows you to programmatically access your security data, trigger pentests,
    and integrate ModernPentest with your CI/CD pipelines and security workflows.

    ## Authentication

    All API requests require an API key passed in the `X-API-Key` header:

    ```
    X-API-Key: mpt_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
    ```

    API keys are scoped to your organization and can be created in Settings > API Keys.
    Each key has specific permissions that control which endpoints it can access.

    ## Rate Limiting

    API requests are rate limited based on your subscription tier:

    | Tier | Per Minute | Per Hour | Per Day |
    |------|------------|----------|---------|
    | Starter | 100 | 1,000 | 10,000 |
    | Professional | 500 | 5,000 | 50,000 |
    | Enterprise | 2,000 | 20,000 | 200,000 |

    Rate limit information is included in response headers:
    - `X-RateLimit-Limit`: Requests allowed per minute
    - `X-RateLimit-Remaining`: Requests remaining in current window
    - `X-RateLimit-Reset`: Unix timestamp when the limit resets

    ## Pagination

    List endpoints support pagination via query parameters:
    - `limit`: Maximum items to return (default: 20, max: 100)
    - `offset`: Number of items to skip (default: 0)

    Responses include pagination metadata in the `pagination` object.

  version: 1.0.0
  contact:
    name: ModernPentest Support
    url: https://modernpentest.com/support
    email: support@modernpentest.com
  license:
    name: Proprietary
    url: https://modernpentest.com/terms

servers:
  - url: https://api.modernpentest.com
    description: Production API

tags:
  - name: Applications
    description: Manage and view your applications
  - name: Pentests
    description: View pentest results and trigger new pentests
  - name: Vulnerabilities
    description: View and manage vulnerabilities

security:
  - ApiKeyAuth: []

paths:
  /api/v1/applications:
    get:
      tags:
        - Applications
      summary: List applications
      description: |
        Returns a paginated list of all active applications in your organization.

        **Required permission:** `applications:read`
      operationId: listApplications
      parameters:
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/OffsetParam'
        - name: environment
          in: query
          description: Filter by environment
          schema:
            type: string
            enum: [production, staging, development, testing]
        - name: criticality
          in: query
          description: Filter by criticality level
          schema:
            type: string
            enum: [critical, high, medium, low]
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - applications
                  - pagination
                properties:
                  applications:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                applications:
                  - id: "k57abc123def456"
                    name: "Production API"
                    url: "https://api.example.com"
                    description: "Main production API server"
                    environment: "production"
                    criticality: "critical"
                    tags: ["api", "backend"]
                    created_at: 1734567890000
                    updated_at: 1734571490000
                    is_active: true
                    security_metrics:
                      overall_score: 85
                      risk_score: 25
                      compliance_score: 90
                      last_scan_at: 1734567890000
                      vulnerability_counts:
                        critical: 0
                        high: 2
                        medium: 5
                        low: 3
                        info: 10
                    health_check:
                      status: "healthy"
                      last_check: 1734571490000
                      response_time: 245
                pagination:
                  total: 5
                  limit: 20
                  offset: 0
                  has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/v1/applications/{applicationId}:
    get:
      tags:
        - Applications
      summary: Get application details
      description: |
        Returns detailed information about a specific application, including recent pentests.

        **Required permission:** `applications:read`
      operationId: getApplication
      parameters:
        - name: applicationId
          in: path
          required: true
          description: The application ID
          schema:
            type: string
          example: "k57abc123def456"
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Application'
                  - type: object
                    properties:
                      recent_pentests:
                        type: array
                        items:
                          $ref: '#/components/schemas/PentestSummary'
                      total_open_vulnerabilities:
                        type: integer
                        description: Total count of open vulnerabilities
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/v1/pentests:
    get:
      tags:
        - Pentests
      summary: List pentests
      description: |
        Returns a paginated list of all pentests (security scans) in your organization.

        **Required permission:** `pentests:read`
      operationId: listPentests
      parameters:
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/OffsetParam'
        - name: application_id
          in: query
          description: Filter by application ID
          schema:
            type: string
        - name: status
          in: query
          description: Filter by status (comma-separated for multiple)
          schema:
            type: string
          example: "completed,running"
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - pentests
                  - pagination
                properties:
                  pentests:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pentest'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      tags:
        - Pentests
      summary: Trigger a new pentest
      description: |
        Triggers a new pentest (security scan) for the specified application.

        The pentest will be queued and executed asynchronously. You can monitor
        its progress by polling the `GET /api/v1/pentests/:pentestId` endpoint.

        **Required permission:** `pentests:create`

        **Limits:**
        - Only one pentest can run per application at a time
        - Organization must be in approved status
      operationId: triggerPentest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - application_id
              properties:
                application_id:
                  type: string
                  description: The ID of the application to scan
            example:
              application_id: "k57abc123def456"
      responses:
        '200':
          description: Pentest triggered successfully
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  pentest_id:
                    type: string
                    description: ID of the created pentest
                  estimated_duration:
                    type: integer
                    description: Estimated duration in seconds
              example:
                success: true
                pentest_id: "k57xyz789ghi012"
                estimated_duration: 1800
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: "VALIDATION_ERROR"
                  message: "A pentest is already running for this application"
                  timestamp: 1734567890000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/v1/pentests/{pentestId}:
    get:
      tags:
        - Pentests
      summary: Get pentest details
      description: |
        Returns detailed information about a specific pentest, including
        vulnerabilities discovered during the scan.

        **Required permission:** `pentests:read`
      operationId: getPentest
      parameters:
        - name: pentestId
          in: path
          required: true
          description: The pentest ID
          schema:
            type: string
          example: "k57xyz789ghi012"
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Pentest'
                  - type: object
                    properties:
                      vulnerabilities:
                        type: array
                        description: Vulnerabilities found in this pentest
                        items:
                          $ref: '#/components/schemas/VulnerabilitySummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/v1/vulnerabilities:
    get:
      tags:
        - Vulnerabilities
      summary: List vulnerabilities
      description: |
        Returns a paginated list of vulnerabilities across all applications,
        with aggregation statistics.

        **Required permission:** `vulnerabilities:read`
      operationId: listVulnerabilities
      parameters:
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/OffsetParam'
        - name: application_id
          in: query
          description: Filter by application ID
          schema:
            type: string
        - name: severity
          in: query
          description: Filter by severity (comma-separated for multiple)
          schema:
            type: string
          example: "critical,high"
        - name: status
          in: query
          description: Filter by status (comma-separated for multiple)
          schema:
            type: string
          example: "open,in_remediation"
        - name: owasp_category
          in: query
          description: Filter by OWASP category (comma-separated for multiple)
          schema:
            type: string
          example: "A01,A03"
        - name: sort_by
          in: query
          description: Field to sort by
          schema:
            type: string
            enum: [severity, status, first_detected_at, last_detected_at]
        - name: sort_order
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - vulnerabilities
                  - aggregations
                  - pagination
                properties:
                  vulnerabilities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vulnerability'
                  aggregations:
                    $ref: '#/components/schemas/VulnerabilityAggregations'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/v1/vulnerabilities/{vulnerabilityId}:
    get:
      tags:
        - Vulnerabilities
      summary: Get vulnerability details
      description: |
        Returns detailed information about a specific vulnerability, including
        detection history, status transitions, and remediation guidance.

        **Required permission:** `vulnerabilities:read`
      operationId: getVulnerability
      parameters:
        - name: vulnerabilityId
          in: path
          required: true
          description: The vulnerability ID
          schema:
            type: string
          example: "k57vuln123abc456"
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Vulnerability'
                  - type: object
                    properties:
                      assigned_user:
                        $ref: '#/components/schemas/AssignedUser'
                      detection_history:
                        type: array
                        items:
                          $ref: '#/components/schemas/DetectionRecord'
                      status_history:
                        type: array
                        items:
                          $ref: '#/components/schemas/StatusTransition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for authentication. Create API keys in Settings > API Keys.
        Format: `mpt_<32 hex characters>`

  parameters:
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip for pagination
      schema:
        type: integer
        minimum: 0
        default: 0

  headers:
    X-RateLimit-Limit:
      description: The maximum number of requests allowed per minute
      schema:
        type: integer
      example: 100
    X-RateLimit-Remaining:
      description: The number of requests remaining in the current window
      schema:
        type: integer
      example: 95
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the rate limit resets
      schema:
        type: integer
      example: 1734567890

  schemas:
    Pagination:
      type: object
      required:
        - total
        - limit
        - offset
        - has_more
      properties:
        total:
          type: integer
          description: Total number of items
        limit:
          type: integer
          description: Maximum items per page
        offset:
          type: integer
          description: Current offset
        has_more:
          type: boolean
          description: Whether more items exist

    Application:
      type: object
      required:
        - id
        - name
        - environment
        - criticality
        - is_active
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique application identifier
        name:
          type: string
          description: Application name
        url:
          type: string
          nullable: true
          description: Primary URL of the application
        description:
          type: string
          nullable: true
          description: Application description
        environment:
          type: string
          enum: [production, staging, development, testing]
          description: Deployment environment
        criticality:
          type: string
          enum: [critical, high, medium, low]
          description: Business criticality level
        tags:
          type: array
          items:
            type: string
          description: Custom tags
        created_at:
          type: integer
          format: int64
          description: Creation timestamp (Unix milliseconds)
        updated_at:
          type: integer
          format: int64
          description: Last update timestamp (Unix milliseconds)
        is_active:
          type: boolean
          description: Whether the application is active
        security_metrics:
          $ref: '#/components/schemas/SecurityMetrics'
        health_check:
          $ref: '#/components/schemas/HealthCheck'

    SecurityMetrics:
      type: object
      properties:
        overall_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Overall security score (0-100)
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Risk score (0-100, lower is better)
        compliance_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Compliance score (0-100)
        last_scan_at:
          type: integer
          format: int64
          nullable: true
          description: Last scan timestamp (Unix milliseconds)
        vulnerability_counts:
          $ref: '#/components/schemas/SeverityCounts'

    SeverityCounts:
      type: object
      properties:
        critical:
          type: integer
        high:
          type: integer
        medium:
          type: integer
        low:
          type: integer
        info:
          type: integer

    HealthCheck:
      type: object
      nullable: true
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy, unknown]
        last_check:
          type: integer
          format: int64
          description: Last health check timestamp
        response_time:
          type: integer
          nullable: true
          description: Response time in milliseconds

    Pentest:
      type: object
      required:
        - id
        - application_id
        - status
        - created_at
      properties:
        id:
          type: string
          description: Unique pentest identifier
        application_id:
          type: string
          description: Associated application ID
        application_name:
          type: string
          nullable: true
          description: Application name
        status:
          type: string
          enum: [pending, running, processing, completed, failed, cancelled, timeout]
          description: Current pentest status
        scan_type:
          type: string
          enum: [manual, scheduled, triggered, continuous]
          nullable: true
          description: How the pentest was initiated
        queued_at:
          type: integer
          format: int64
          description: When the pentest was queued
        started_at:
          type: integer
          format: int64
          nullable: true
          description: When the pentest started
        completed_at:
          type: integer
          format: int64
          nullable: true
          description: When the pentest completed
        duration:
          type: integer
          nullable: true
          description: Duration in milliseconds
        progress_percentage:
          type: integer
          minimum: 0
          maximum: 100
          description: Progress percentage (0-100)
        risk_level:
          type: string
          enum: [critical, high, medium, low, minimal]
          nullable: true
          description: Overall risk level from findings
        risk_score:
          type: integer
          nullable: true
          description: Calculated risk score (0-100)
        vulnerabilities_found:
          type: integer
          description: Total vulnerabilities discovered
        severity_breakdown:
          $ref: '#/components/schemas/SeverityCounts'
        configuration:
          $ref: '#/components/schemas/PentestConfiguration'
        error:
          type: object
          nullable: true
          description: Error details if the pentest failed
          properties:
            code:
              type: string
            message:
              type: string
        created_at:
          type: integer
          format: int64
          description: Creation timestamp (Unix milliseconds)

    PentestConfiguration:
      type: object
      nullable: true
      properties:
        owasp_tests:
          type: array
          items:
            type: string
          description: OWASP tests included
        depth:
          type: string
          enum: [shallow, medium, deep]
          description: Scan depth
        max_duration:
          type: integer
          nullable: true
          description: Maximum duration in minutes

    PentestSummary:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, running, processing, completed, failed, cancelled, timeout]
        started_at:
          type: integer
          format: int64
          nullable: true
        completed_at:
          type: integer
          format: int64
          nullable: true
        vulnerabilities_found:
          type: integer

    Vulnerability:
      type: object
      required:
        - id
        - title
        - severity
        - status
        - owasp_category
        - first_detected_at
      properties:
        id:
          type: string
          description: Unique vulnerability identifier
        title:
          type: string
          description: Vulnerability title
        description:
          type: string
          nullable: true
          description: Detailed description
        severity:
          type: string
          enum: [critical, high, medium, low, info]
          description: Severity level
        status:
          type: string
          enum: [open, in_remediation, remediated, fixed, accepted_risk, false_positive]
          description: Current status
        owasp_category:
          type: string
          description: OWASP Top 10 category (e.g., A01, A02)
        cwe_id:
          type: string
          nullable: true
          description: CWE identifier
        vulnerability_type:
          type: string
          nullable: true
          description: Type of vulnerability
        application_id:
          type: string
          description: Associated application ID
        application_name:
          type: string
          nullable: true
          description: Application name
        first_detected_at:
          type: integer
          format: int64
          description: First detection timestamp
        last_detected_at:
          type: integer
          format: int64
          description: Most recent detection timestamp
        fixed_at:
          type: integer
          format: int64
          nullable: true
          description: When the vulnerability was fixed
        remediated_at:
          type: integer
          format: int64
          nullable: true
          description: When remediation was applied
        detection_count:
          type: integer
          description: Number of times detected
        technical_context:
          $ref: '#/components/schemas/TechnicalContext'
        evidence:
          $ref: '#/components/schemas/Evidence'
        business_impact:
          type: string
          nullable: true
          description: Business impact description
        remediation:
          $ref: '#/components/schemas/Remediation'
        remediation_effort:
          $ref: '#/components/schemas/RemediationEffort'
        assigned_to:
          type: string
          nullable: true
          description: Assigned user ID
        due_date:
          type: integer
          format: int64
          nullable: true
          description: Remediation due date
        priority:
          type: string
          nullable: true
          description: Priority level
        exploit_available:
          type: boolean
          description: Whether a known exploit exists
        created_at:
          type: integer
          format: int64
          description: Creation timestamp

    VulnerabilitySummary:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        severity:
          type: string
          enum: [critical, high, medium, low, info]
        status:
          type: string
          enum: [open, in_remediation, remediated, fixed, accepted_risk, false_positive]
        owasp_category:
          type: string

    TechnicalContext:
      type: object
      nullable: true
      properties:
        endpoint:
          type: string
          description: Affected endpoint/URL
        method:
          type: string
          nullable: true
          description: HTTP method
        parameter:
          type: string
          nullable: true
          description: Affected parameter
        affected_component:
          type: string
          nullable: true
          description: Affected component

    Evidence:
      type: object
      nullable: true
      properties:
        proof_of_concept:
          type: string
          nullable: true
          description: Proof of concept details
        observed_behavior:
          type: string
          nullable: true
          description: Observed behavior description
        vulnerable_endpoint:
          type: string
          nullable: true
          description: Vulnerable endpoint
        vulnerable_parameter:
          type: string
          nullable: true
          description: Vulnerable parameter

    Remediation:
      type: object
      nullable: true
      properties:
        immediate_action:
          type: string
          nullable: true
          description: Immediate action to take
        steps:
          type: array
          items:
            type: string
          description: Step-by-step remediation instructions
        references:
          type: array
          items:
            type: string
          description: Reference URLs

    RemediationEffort:
      type: object
      nullable: true
      properties:
        estimated_hours:
          type: number
          nullable: true
          description: Estimated hours to remediate
        effort_level:
          type: string
          nullable: true
          description: Effort level (e.g., low, medium, high)
        complexity:
          type: string
          nullable: true
          description: Complexity level

    VulnerabilityAggregations:
      type: object
      properties:
        by_severity:
          $ref: '#/components/schemas/SeverityCounts'
        by_status:
          type: object
          properties:
            open:
              type: integer
            in_remediation:
              type: integer
            remediated:
              type: integer
            fixed:
              type: integer
            accepted_risk:
              type: integer
            false_positive:
              type: integer
        by_owasp_category:
          type: object
          additionalProperties:
            type: integer
          description: Count by OWASP category

    AssignedUser:
      type: object
      nullable: true
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

    DetectionRecord:
      type: object
      properties:
        id:
          type: string
        scan_id:
          type: string
        scan_completed_at:
          type: integer
          format: int64
          nullable: true
        detection_state:
          type: string
        matching_confidence:
          type: number
        detected_at:
          type: integer
          format: int64

    StatusTransition:
      type: object
      properties:
        from_status:
          type: string
        to_status:
          type: string
        reason:
          type: string
          nullable: true
        triggered_at:
          type: integer
          format: int64

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - timestamp
          properties:
            code:
              type: string
              description: Error code
              enum:
                - UNAUTHENTICATED
                - API_KEY_EXPIRED
                - FORBIDDEN
                - NOT_FOUND
                - RATE_LIMIT_EXCEEDED
                - VALIDATION_ERROR
                - INTERNAL_ERROR
            message:
              type: string
              description: Human-readable error message
            timestamp:
              type: integer
              format: int64
              description: Error timestamp (Unix milliseconds)

  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "UNAUTHENTICATED"
              message: "Invalid or missing API key"
              timestamp: 1734567890000

    Forbidden:
      description: API key lacks required permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "FORBIDDEN"
              message: "Missing required permission: applications:read"
              timestamp: 1734567890000

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "NOT_FOUND"
              message: "Application not found"
              timestamp: 1734567890000

    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "RATE_LIMIT_EXCEEDED"
              message: "Rate limit exceeded. Try again in 45 seconds."
              timestamp: 1734567890000

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "INTERNAL_ERROR"
              message: "An unexpected error occurred"
              timestamp: 1734567890000