@threnn/acap-sdk 0.2.0

package/docs/openapi-acap.yaml

@@ -0,0 +1,1319 @@
+openapi: 3.1.0
+info:
+  title: ACAP — Agent Capability Attestation Protocol API
+  version: 0.1.0
+  description: |
+    The ACAP API enables attesting, certifying, and monitoring AI agent capabilities.
+    All endpoints require Bearer token authentication via an API key.
+  license:
+    name: MIT
+  contact:
+    url: https://threnn.ai
+
+servers:
+  - url: https://app.threnn.ai/api/v1/acap
+    description: Production
+
+security:
+  - bearerAuth: []
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+          description: Human-readable error message
+        code:
+          type: string
+          enum: [UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR, INVALID_JSON]
+          description: Machine-readable error code
+        details:
+          type: array
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+              message:
+                type: string
+          description: Validation error details (only for VALIDATION_ERROR)
+
+    AttestationRun:
+      type: object
+      properties:
+        id:
+          type: string
+          example: RUN-LQZP3K7MABCD1234
+        api_key_id:
+          type: string
+        agent_id:
+          type: string
+          example: my-agent-001
+        benchmark_suite_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [pending, running, completed, failed, cancelled]
+        started_at:
+          type: string
+          format: date-time
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+        task_progress:
+          type: object
+          properties:
+            totalTasks:
+              type: integer
+            completedTasks:
+              type: integer
+            passedTasks:
+              type: integer
+            failedTasks:
+              type: integer
+            estimatedRemainingMs:
+              type: integer
+            elapsedMs:
+              type: integer
+            taskOrder:
+              type: array
+              items:
+                type: integer
+              description: Randomized task execution order (anti-gaming)
+        certificate_id:
+          type: string
+          nullable: true
+        warning:
+          type: string
+          description: Present when another run is already in progress for this agent
+
+    Certificate:
+      type: object
+      properties:
+        id:
+          type: string
+        agent_id:
+          type: string
+        organization_id:
+          type: string
+          nullable: true
+        benchmark_suite_id:
+          type: string
+          format: uuid
+        benchmark_suite_version:
+          type: string
+        benchmark_domain:
+          type: string
+        overall_score:
+          type: number
+          minimum: 0
+          maximum: 1
+        dimension_scores:
+          type: array
+          items:
+            type: object
+            properties:
+              dimension:
+                type: string
+              score:
+                type: number
+              confidence_interval:
+                type: object
+                properties:
+                  lower:
+                    type: number
+                  upper:
+                    type: number
+                nullable: true
+        task_results:
+          type: array
+          items:
+            type: object
+        attestation_context:
+          type: object
+          properties:
+            modelProvider:
+              type: string
+            modelVersion:
+              type: string
+            testEnvironment:
+              type: string
+            executionDuration_ms:
+              type: integer
+        capability_tier:
+          type: string
+          enum: [basic, intermediate, advanced, expert]
+        limitations:
+          type: array
+          items:
+            type: object
+            properties:
+              dimension:
+                type: string
+              severity:
+                type: string
+              description:
+                type: string
+        conditions:
+          type: array
+          items:
+            type: string
+        content_hash:
+          type: string
+          description: SHA-256 content hash for integrity verification
+        signature:
+          type: string
+        protocol_version:
+          type: string
+        issued_at:
+          type: string
+          format: date-time
+        expires_at:
+          type: string
+          format: date-time
+        status:
+          type: string
+          enum: [active, revoked, expired, superseded]
+        is_public:
+          type: boolean
+        tags:
+          type: array
+          items:
+            type: string
+        integrity_warning:
+          type: string
+          description: Present if content hash mismatch detected on read
+
+    VerificationResult:
+      type: object
+      properties:
+        valid:
+          type: boolean
+        checks:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                enum: [content_hash, signature, not_expired, status, score_range, issued_date]
+              passed:
+                type: boolean
+              message:
+                type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    NutritionLabel:
+      type: object
+      properties:
+        agentId:
+          type: string
+        certifiedAt:
+          type: string
+          format: date-time
+        expiresAt:
+          type: string
+          format: date-time
+        attestationType:
+          type: string
+        protocolVersion:
+          type: string
+        tier:
+          type: string
+        overallScore:
+          type: number
+        dimensions:
+          type: array
+          items:
+            type: object
+            properties:
+              dimension:
+                type: string
+              score:
+                type: number
+        strengths:
+          type: array
+          items:
+            type: object
+            properties:
+              dimension:
+                type: string
+              score:
+                type: number
+              description:
+                type: string
+        limitations:
+          type: array
+          items:
+            type: string
+        testConditions:
+          type: object
+          properties:
+            modelProvider:
+              type: string
+            modelVersion:
+              type: string
+            testEnvironment:
+              type: string
+            benchmarkSuite:
+              type: string
+            benchmarkVersion:
+              type: string
+            taskCount:
+              type: integer
+            executionDuration_ms:
+              type: integer
+
+    BenchmarkSuite:
+      type: object
+      properties:
+        id:
+          type: string
+          example: BS-LQZP3K7MABCD1234
+        api_key_id:
+          type: string
+          nullable: true
+        name:
+          type: string
+        domain:
+          type: string
+        version:
+          type: string
+        description:
+          type: string
+        tasks:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              category:
+                type: string
+              difficulty:
+                type: integer
+                minimum: 1
+                maximum: 5
+              dimension:
+                type: string
+              weight:
+                type: number
+              evaluationMethod:
+                type: string
+              timeout_ms:
+                type: integer
+              description:
+                type: string
+        dimensions:
+          type: array
+          items:
+            type: string
+        difficulty:
+          type: string
+        estimated_duration_ms:
+          type: integer
+        is_public:
+          type: boolean
+        nist_alignment:
+          type: string
+          nullable: true
+        task_count:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+
+    RegistryListing:
+      type: object
+      properties:
+        id:
+          type: string
+        certificate_id:
+          type: string
+        api_key_id:
+          type: string
+        agent_name:
+          type: string
+        agent_description:
+          type: string
+        domain:
+          type: string
+        overall_score:
+          type: number
+        capability_tier:
+          type: string
+        listed_at:
+          type: string
+          format: date-time
+        delisted_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    DriftEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        api_key_id:
+          type: string
+        agent_id:
+          type: string
+        drift_type:
+          type: string
+          enum: [degradation, improvement, tier_change, dimension_shift, stable]
+        severity:
+          type: string
+          enum: [info, warning, critical]
+        previous_certificate_id:
+          type: string
+        current_certificate_id:
+          type: string
+        overall_score_delta:
+          type: number
+        acknowledged:
+          type: boolean
+        acknowledged_at:
+          type: string
+          format: date-time
+          nullable: true
+        acknowledged_note:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    ComparisonResult:
+      type: object
+      properties:
+        certificates:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              agentId:
+                type: string
+              domain:
+                type: string
+              overallScore:
+                type: number
+              tier:
+                type: string
+              issuedAt:
+                type: string
+        dimensionComparisons:
+          type: array
+          items:
+            type: object
+            properties:
+              dimension:
+                type: string
+              scores:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    certificateId:
+                      type: string
+                    agentId:
+                      type: string
+                    score:
+                      type: number
+              maxDelta:
+                type: number
+        overallRanking:
+          type: array
+          items:
+            type: object
+            properties:
+              certificateId:
+                type: string
+              agentId:
+                type: string
+              overallScore:
+                type: number
+              tier:
+                type: string
+
+    PaginatedResponse:
+      type: object
+      properties:
+        data:
+          type: array
+          items: {}
+        total:
+          type: integer
+        page:
+          type: integer
+        pageSize:
+          type: integer
+
+    HealthStats:
+      type: object
+      properties:
+        activeCertificates:
+          type: integer
+        avgScore:
+          type: number
+        expiringSoon:
+          type: integer
+        driftAlerts:
+          type: integer
+
+paths:
+  /attest:
+    post:
+      summary: Start an attestation run
+      description: |
+        Creates a new attestation run for an agent against a benchmark suite.
+        Tasks are served in randomized order (Fisher-Yates shuffle) for anti-gaming.
+        Rate limit: 10 requests/minute.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [agentId, suiteId]
+              properties:
+                agentId:
+                  type: string
+                  minLength: 1
+                  maxLength: 256
+                suiteId:
+                  type: string
+                  format: uuid
+            example:
+              agentId: my-customer-service-agent
+              suiteId: 550e8400-e29b-41d4-a716-446655440000
+      responses:
+        '201':
+          description: Attestation run created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AttestationRun'
+              example:
+                id: RUN-LQZP3K7MABCD1234
+                agent_id: my-customer-service-agent
+                status: pending
+                warning: Another attestation run is already in progress for this agent
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: Validation failed
+                code: VALIDATION_ERROR
+                details:
+                  - path: suiteId
+                    message: Invalid uuid
+        '401':
+          description: Unauthorized
+        '404':
+          description: Benchmark suite not found
+        '429':
+          description: Rate limited
+          headers:
+            Retry-After:
+              schema:
+                type: integer
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+            X-RateLimit-Reset:
+              schema:
+                type: integer
+
+  /attest/{runId}:
+    parameters:
+      - name: runId
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get attestation run status
+      description: Poll this endpoint to track attestation progress.
+      responses:
+        '200':
+          description: Run status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AttestationRun'
+        '403':
+          description: Not your run
+        '404':
+          description: Run not found
+    delete:
+      summary: Cancel an attestation run
+      description: Cancels a pending or running attestation. Cannot cancel completed or already cancelled runs.
+      responses:
+        '200':
+          description: Run cancelled
+          content:
+            application/json:
+              example:
+                success: true
+                id: RUN-LQZP3K7MABCD1234
+                status: cancelled
+        '409':
+          description: Cannot cancel a completed/cancelled run
+
+  /certificates:
+    get:
+      summary: List certificates
+      description: Returns paginated certificates owned by the authenticated user.
+      parameters:
+        - name: agentId
+          in: query
+          schema:
+            type: string
+        - name: domain
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, revoked, expired, superseded]
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Paginated certificate list
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Certificate'
+
+  /certificates/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get a certificate
+      description: |
+        Fetches a single certificate. Accessible if you own it or if it's public.
+        Performs content hash integrity verification on read — if the hash doesn't match,
+        an `integrity_warning` field is included in the response.
+      responses:
+        '200':
+          description: Certificate data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Certificate'
+        '403':
+          description: Certificate is private and not owned by you
+        '404':
+          description: Certificate not found
+
+  /certificates/{id}/verify:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Verify certificate integrity
+      description: |
+        Runs integrity and validity checks on a certificate:
+        content hash (cryptographic), signature, expiration (with 7-day grace period),
+        status, score range, and issue date.
+      responses:
+        '200':
+          description: Verification result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VerificationResult'
+              example:
+                valid: true
+                checks:
+                  - name: content_hash
+                    passed: true
+                    message: Content hash matches certificate data
+                  - name: not_expired
+                    passed: true
+                    message: Expired at 2026-03-01T00:00:00Z — within 7-day grace period
+                warnings:
+                  - Certificate expired 3 days ago — within 7-day grace period
+        '404':
+          description: Certificate not found
+
+  /certificates/{id}/revoke:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    post:
+      summary: Revoke a certificate
+      description: Revokes an active certificate. Also delists from registry if published.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+            example:
+              reason: Model updated, re-attestation in progress
+      responses:
+        '200':
+          description: Certificate revoked
+          content:
+            application/json:
+              example:
+                success: true
+                id: CERT-ID
+                status: revoked
+        '403':
+          description: Not your certificate
+        '409':
+          description: Already revoked
+
+  /certificates/{id}/label:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get nutrition label
+      description: Returns a human-readable nutrition label with strengths, test conditions, and limitations.
+      responses:
+        '200':
+          description: Nutrition label
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NutritionLabel'
+        '403':
+          description: Certificate is private and not owned by you
+        '404':
+          description: Certificate not found
+
+  /certificates/{id}/badge:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get certificate badge (SVG)
+      description: |
+        Returns a shields.io-style SVG badge showing "ACAP | Tier Score%".
+        Public certificates are served without authentication.
+        Private certificates require Bearer token auth.
+      security: []
+      responses:
+        '200':
+          description: SVG badge image
+          content:
+            image/svg+xml:
+              schema:
+                type: string
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+                example: public, max-age=3600
+
+  /agents/{agentId}/certificates:
+    parameters:
+      - name: agentId
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: List certificates for an agent
+      description: Returns paginated certificates for a specific agent.
+      parameters:
+        - name: domain
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            type: string
+            default: active
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Paginated certificate list
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Certificate'
+
+  /registry/publish:
+    post:
+      summary: Publish certificate to registry
+      description: |
+        Publishes a certificate to the public registry. Requirements:
+        - Certificate must be active
+        - Certificate must have at least 3 task results
+        - Certificate must not already be listed
+        Rate limit: 20 requests/minute.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [certificateId, agentName, agentDescription]
+              properties:
+                certificateId:
+                  type: string
+                  format: uuid
+                agentName:
+                  type: string
+                  minLength: 1
+                  maxLength: 100
+                agentDescription:
+                  type: string
+                  minLength: 1
+                  maxLength: 2000
+            example:
+              certificateId: 550e8400-e29b-41d4-a716-446655440000
+              agentName: My Customer Service Agent
+              agentDescription: Specialized agent for tier-1 support workflows
+      responses:
+        '201':
+          description: Listing created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RegistryListing'
+        '400':
+          description: Validation error or insufficient task results
+        '403':
+          description: Not your certificate
+        '409':
+          description: Certificate already listed
+        '429':
+          description: Rate limited
+
+  /registry/search:
+    get:
+      summary: Search the public registry
+      parameters:
+        - name: domain
+          in: query
+          schema:
+            type: string
+        - name: minScore
+          in: query
+          schema:
+            type: number
+        - name: maxScore
+          in: query
+          schema:
+            type: number
+        - name: tier
+          in: query
+          schema:
+            type: string
+            enum: [basic, intermediate, advanced, expert]
+        - name: query
+          in: query
+          description: Search agent name and description
+          schema:
+            type: string
+        - name: sortBy
+          in: query
+          schema:
+            type: string
+            enum: [score, recent, name]
+            default: score
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Paginated registry listings
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/RegistryListing'
+
+  /registry/leaderboard/{domain}:
+    parameters:
+      - name: domain
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get domain leaderboard
+      description: Returns top agents for a domain, sorted by score descending.
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 25
+            maximum: 100
+      responses:
+        '200':
+          description: Leaderboard entries
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  domain:
+                    type: string
+                  entries:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        rank:
+                          type: integer
+                        id:
+                          type: string
+                        certificate_id:
+                          type: string
+                        agent_name:
+                          type: string
+                        agent_description:
+                          type: string
+                        overall_score:
+                          type: number
+                        capability_tier:
+                          type: string
+                        listed_at:
+                          type: string
+                          format: date-time
+
+  /suites:
+    get:
+      summary: List benchmark suites
+      description: Returns public/system suites plus the authenticated user's own suites.
+      parameters:
+        - name: domain
+          in: query
+          schema:
+            type: string
+        - name: isPublic
+          in: query
+          schema:
+            type: string
+            enum: ['true', 'false']
+      responses:
+        '200':
+          description: Array of benchmark suites
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/BenchmarkSuite'
+    post:
+      summary: Create a benchmark suite
+      description: |
+        Creates a custom benchmark suite with 1-100 tasks.
+        Rate limit: 30 requests/minute.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name, domain, tasks]
+              properties:
+                name:
+                  type: string
+                  minLength: 1
+                  maxLength: 256
+                domain:
+                  type: string
+                  minLength: 1
+                version:
+                  type: string
+                  maxLength: 50
+                  default: '1.0'
+                description:
+                  type: string
+                  maxLength: 2000
+                tasks:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items:
+                    type: object
+                    required: [name]
+                    properties:
+                      name:
+                        type: string
+                        minLength: 1
+                        maxLength: 256
+                      category:
+                        type: string
+                      difficulty:
+                        type: integer
+                        minimum: 1
+                        maximum: 5
+                      dimension:
+                        type: string
+                      weight:
+                        type: number
+                        minimum: 0
+                        maximum: 10
+                      evaluationMethod:
+                        type: string
+                      timeout_ms:
+                        type: integer
+                        minimum: 0
+                      description:
+                        type: string
+                        maxLength: 2000
+                dimensions:
+                  type: array
+                  items:
+                    type: string
+                difficulty:
+                  type: string
+                estimatedDuration_ms:
+                  type: integer
+                  minimum: 0
+                isPublic:
+                  type: boolean
+                  default: false
+                nistAlignment:
+                  type: string
+                  nullable: true
+      responses:
+        '201':
+          description: Suite created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BenchmarkSuite'
+        '400':
+          description: Validation error
+        '429':
+          description: Rate limited
+
+  /suites/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get a benchmark suite
+      description: Accessible if public, system-owned, or owned by you.
+      responses:
+        '200':
+          description: Benchmark suite
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BenchmarkSuite'
+        '403':
+          description: Private suite not owned by you
+        '404':
+          description: Suite not found
+    put:
+      summary: Update a benchmark suite
+      description: Only the owner can update a suite. All fields are optional.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  minLength: 1
+                  maxLength: 256
+                description:
+                  type: string
+                  maxLength: 2000
+                version:
+                  type: string
+                  maxLength: 50
+                tasks:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                dimensions:
+                  type: array
+                  items:
+                    type: string
+                difficulty:
+                  type: string
+                estimatedDuration_ms:
+                  type: integer
+                isPublic:
+                  type: boolean
+                nistAlignment:
+                  type: string
+                  nullable: true
+      responses:
+        '200':
+          description: Suite updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BenchmarkSuite'
+        '400':
+          description: Validation error or no fields to update
+        '403':
+          description: Can only update your own suites
+        '404':
+          description: Suite not found
+    delete:
+      summary: Delete a benchmark suite
+      description: Only the owner can delete a suite.
+      responses:
+        '200':
+          description: Suite deleted
+          content:
+            application/json:
+              example:
+                success: true
+        '403':
+          description: Can only delete your own suites
+        '404':
+          description: Suite not found
+
+  /compare:
+    get:
+      summary: Compare certificates
+      description: Compare 2-10 certificates side-by-side on all capability dimensions.
+      parameters:
+        - name: ids
+          in: query
+          required: true
+          description: Comma-separated certificate IDs (2-10)
+          schema:
+            type: string
+          example: cert-id-1,cert-id-2,cert-id-3
+      responses:
+        '200':
+          description: Comparison result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ComparisonResult'
+        '400':
+          description: Less than 2 or more than 10 IDs
+        '403':
+          description: One or more certificates are private and not owned by you
+        '404':
+          description: Could not find enough certificates
+
+  /drift:
+    get:
+      summary: List drift events
+      description: Returns paginated capability drift events for the authenticated user.
+      parameters:
+        - name: agentId
+          in: query
+          schema:
+            type: string
+        - name: severity
+          in: query
+          schema:
+            type: string
+            enum: [info, warning, critical]
+        - name: acknowledged
+          in: query
+          schema:
+            type: string
+            enum: ['true', 'false']
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 50
+            maximum: 100
+      responses:
+        '200':
+          description: Paginated drift events
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/DriftEvent'
+    patch:
+      summary: Acknowledge drift events
+      description: |
+        Acknowledge one or more drift events. Two request body shapes are supported.
+        Maximum 100 events per request.
+        Rate limit: 30 requests/minute.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - type: object
+                  required: [eventIds]
+                  properties:
+                    eventIds:
+                      type: array
+                      items:
+                        type: string
+                      minItems: 1
+                      maxItems: 100
+                      description: Bulk acknowledge with shared note
+                    note:
+                      type: string
+                      maxLength: 1000
+                - type: object
+                  required: [events]
+                  properties:
+                    events:
+                      type: array
+                      items:
+                        type: object
+                        required: [id]
+                        properties:
+                          id:
+                            type: string
+                          note:
+                            type: string
+                            maxLength: 1000
+                      minItems: 1
+                      maxItems: 100
+                      description: Per-event acknowledge with individual notes
+            examples:
+              bulk:
+                summary: Bulk acknowledge
+                value:
+                  eventIds: [event-1, event-2, event-3]
+                  note: Acknowledged after review
+              per-event:
+                summary: Per-event notes
+                value:
+                  events:
+                    - id: event-1
+                      note: Expected degradation after model swap
+                    - id: event-2
+                      note: Will re-attest next week
+      responses:
+        '200':
+          description: Events acknowledged
+          content:
+            application/json:
+              example:
+                success: true
+                acknowledged: 3
+        '400':
+          description: Validation error
+        '429':
+          description: Rate limited
+
+  /health:
+    get:
+      summary: Get ACAP health stats
+      description: Lightweight dashboard stats for the overview page.
+      responses:
+        '200':
+          description: Health stats
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthStats'
+              example:
+                activeCertificates: 12
+                avgScore: 0.73
+                expiringSoon: 2
+                driftAlerts: 1