Comp AI Security Penetration Tests API

openapi: 3.2.0
info:
  title: Comp AI Security Penetration Tests API
  description: Compliance automation API for SOC 2, ISO 27001, HIPAA, GDPR, evidence collection, policy workflows, Trust Access, security questionnaires, integrations, cloud checks, and device compliance.
  version: '1.0'
  contact: {}
servers:
- url: https://api.trycomp.ai
  description: Production API Server
tags:
- name: Security Penetration Tests
  description: Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
paths:
  /v1/security-penetration-tests:
    get:
      description: List penetration test runs in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
      operationId: SecurityPenetrationTestsController_list_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Penetration tests returned
      security:
      - apikey: []
      summary: List penetration test runs
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: List penetration test runs | Comp AI API
          sidebarTitle: List penetration test runs
          description: List penetration test runs in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
          og:title: List penetration test runs | Comp AI API
          og:description: List penetration test runs in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
      x-speakeasy-mcp:
        name: list
    post:
      description: Create an AI-powered penetration test run for an approved target and track the resulting findings and report artifacts.
      operationId: SecurityPenetrationTestsController_create_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePenetrationTestDto'
      responses:
        '201':
          description: Penetration test created
        '400':
          description: Invalid request payload
      security:
      - apikey: []
      summary: Create penetration test
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Create penetration test | Comp AI API
          sidebarTitle: Create penetration test
          description: Create an AI-powered penetration test run for an approved target and track the resulting findings and report artifacts.
          og:title: Create penetration test | Comp AI API
          og:description: Create an AI-powered penetration test run for an approved target and track the resulting findings and report artifacts.
      x-speakeasy-mcp:
        name: security-penetration-tests-create
  /v1/security-penetration-tests/{id}:
    get:
      description: Get penetration test status in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
      operationId: SecurityPenetrationTestsController_getById_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Penetration test returned
        '404':
          description: Penetration test not found
      security:
      - apikey: []
      summary: Get penetration test status
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test status | Comp AI API
          sidebarTitle: Get penetration test status
          description: Get penetration test status in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
          og:title: Get penetration test status | Comp AI API
          og:description: Get penetration test status in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
      x-speakeasy-mcp:
        name: get-by-id
  /v1/security-penetration-tests/{id}/progress:
    get:
      description: Get penetration test progress in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
      operationId: SecurityPenetrationTestsController_getProgress_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Progress returned
      security:
      - apikey: []
      summary: Get penetration test progress
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test progress | Comp AI API
          sidebarTitle: Get penetration test progress
          description: Get penetration test progress in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
          og:title: Get penetration test progress | Comp AI API
          og:description: Get penetration test progress in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
      x-speakeasy-mcp:
        name: get-progress
  /v1/security-penetration-tests/{id}/issues:
    get:
      description: Returns the structured findings discovered during the run. Grows over time during a live scan as agents discover more issues.
      operationId: SecurityPenetrationTestsController_getIssues_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Issues returned
      security:
      - apikey: []
      summary: Get penetration test issues
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test issues | Comp AI API
          sidebarTitle: Get penetration test issues
          description: Returns the structured findings discovered during the run. Grows over time during a live scan as agents discover more issues.
          og:title: Get penetration test issues | Comp AI API
          og:description: Returns the structured findings discovered during the run. Grows over time during a live scan as agents discover more issues.
      x-speakeasy-mcp:
        name: get-issues
  /v1/security-penetration-tests/{id}/events:
    get:
      description: Returns the real-time agent activity log emitted during a run (tool calls, observations, etc.). Noisy — meant for activity feeds and debugging.
      operationId: SecurityPenetrationTestsController_getEvents_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Events returned
      security:
      - apikey: []
      summary: Get penetration test agent events
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test agent events | Comp AI API
          sidebarTitle: Get penetration test agent events
          description: Returns the real-time agent activity log emitted during a run (tool calls, observations, etc.). Noisy — meant for activity feeds and debugging.
          og:title: Get penetration test agent events | Comp AI API
          og:description: Returns the real-time agent activity log emitted during a run (tool calls, observations, etc.). Noisy — meant for activity feeds and debugging.
      x-speakeasy-mcp:
        name: get-events
  /v1/security-penetration-tests/{id}/report:
    get:
      description: Get penetration test output in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
      operationId: SecurityPenetrationTestsController_getReport_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Markdown report output
      security:
      - apikey: []
      summary: Get penetration test output
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test output | Comp AI API
          sidebarTitle: Get penetration test output
          description: Get penetration test output in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
          og:title: Get penetration test output | Comp AI API
          og:description: Get penetration test output in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
      x-speakeasy-mcp:
        name: get-report
  /v1/security-penetration-tests/{id}/pdf:
    get:
      description: Get penetration test PDF in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF reports.
      operationId: SecurityPenetrationTestsController_getPdf_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: PDF report artifact
      security:
      - apikey: []
      summary: Get penetration test PDF
      tags:
      - Security Penetration Tests
      x-mint:
        metadata:
          title: Get penetration test PDF | Comp AI API
          sidebarTitle: Get penetration test PDF
          description: Get penetration test PDF in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
          og:title: Get penetration test PDF | Comp AI API
          og:description: Get penetration test PDF in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.
      x-speakeasy-mcp:
        name: get-pdf
  /v1/pentest-finding-contexts:
    get:
      description: Returns the customer-written context notes attached to pentest findings for a target URL. These notes are shared with the testing agent on future scans of the same target so retests are informed, not blind.
      operationId: PentestFindingContextsController_list_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: targetUrl
        required: true
        in: query
        description: Target URL the notes are attached to
        schema:
          type: string
      responses:
        '200':
          description: Context notes returned
      security:
      - apikey: []
      summary: List pentest finding context notes
      tags:
      - Security Penetration Tests
      x-speakeasy-mcp:
        name: list-pentest-finding-contexts
      x-mint:
        metadata:
          title: List pentest finding context notes | Comp AI API
          sidebarTitle: List pentest finding context notes
          description: Returns the customer-written context notes attached to pentest findings for a target URL. These notes are shared with the testing agent on future scans of.
          og:title: List pentest finding context notes | Comp AI API
          og:description: Returns the customer-written context notes attached to pentest findings for a target URL. These notes are shared with the testing agent on future scans of.
  /v1/pentest-finding-contexts/{issueId}:
    put:
      description: Saves a customer context note on a pentest finding, e.g. an accepted-by-design rationale or remediation details. Future scans of the same target pass the note to the testing agent so the issue is retested with that context.
      operationId: PentestFindingContextsController_upsert_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: issueId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertFindingContextDto'
      responses:
        '200':
          description: Context note saved
        '404':
          description: Run or finding not found
      security:
      - apikey: []
      summary: Add context to a pentest finding
      tags:
      - Security Penetration Tests
      x-speakeasy-mcp:
        name: set-pentest-finding-context
      x-mint:
        metadata:
          title: Add context to a pentest finding | Comp AI API
          sidebarTitle: Add context to a pentest finding
          description: Saves a customer context note on a pentest finding, e.g. an accepted-by-design rationale or remediation details. Future scans of the same target pass the.
          og:title: Add context to a pentest finding | Comp AI API
          og:description: Saves a customer context note on a pentest finding, e.g. an accepted-by-design rationale or remediation details. Future scans of the same target pass the.
    delete:
      description: Deletes the customer context note attached to a pentest finding so future scans of the target no longer receive it from the testing agent briefing.
      operationId: PentestFindingContextsController_remove_v1
      parameters:
      - name: X-Organization-Id
        in: header
        description: Organization ID (required for session auth, optional for API key auth)
        required: false
        schema:
          type: string
      - name: issueId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Context note deleted
        '404':
          description: No context found for finding
      security:
      - apikey: []
      summary: Remove context from a pentest finding
      tags:
      - Security Penetration Tests
      x-speakeasy-mcp:
        name: delete-pentest-finding-context
      x-mint:
        metadata:
          title: Remove context from a pentest finding | Comp AI API
          sidebarTitle: Remove context from a pentest finding
          description: Deletes the customer context note attached to a pentest finding so future scans of the target no longer receive it from the testing agent briefing.
          og:title: Remove context from a pentest finding | Comp AI API
          og:description: Deletes the customer context note attached to a pentest finding so future scans of the target no longer receive it from the testing agent briefing.
components:
  schemas:
    UpsertFindingContextDto:
      type: object
      properties:
        runId:
          type: string
          description: Penetration test run ID the finding belongs to
          example: pentest-abc123
        context:
          type: string
          description: Context for the finding, e.g. an accepted-by-design rationale or remediation details. Shared with the testing agent on future scans of the same target. Max 2000 characters.
          example: 'Read access to appConfiguration is accepted by design: the collection only holds non-secret bootstrap configuration and write access is restricted to privileged users.'
          maxLength: 2000
      required:
      - runId
      - context
    CreatePenetrationTestDto:
      type: object
      properties:
        targetUrl:
          type: string
          description: Target URL for the penetration test scan
          example: https://app.example.com
        repoUrl:
          type: string
          description: Repository URL containing the target application code
          example: https://github.com/org/repo
        additionalContext:
          type: string
          description: Free-text context shared with the testing agent, e.g. remediation notes or accepted-by-design explanations from a previous run. Saved per-finding context notes for the same target are appended automatically. Max 4000 characters.
          maxLength: 4000
      required:
      - targetUrl
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
x-speakeasy-timeout: 120000