> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codethreat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scans

> Get a paginated list of security scans

# Scans API

Trigger and manage security scans via API.

## Trigger Scan

```http theme={null}
POST /v1/scans
```

**Request**:

```json theme={null}
{
  "repository_id": "repo_123",
  "branch": "main"
}
```

**Response**:

```json theme={null}
{
  "scan_id": "scan_456",
  "status": "PENDING",
  "repository_id": "repo_123",
  "branch": "main",
  "created_at": "2024-03-15T14:32:18Z"
}
```

## Get Scan Status

```http theme={null}
GET /v1/scans/:scan_id
```

**Response**:

```json theme={null}
{
  "scan_id": "scan_456",
  "status": "COMPLETED",
  "repository_id": "repo_123",
  "branch": "main",
  "violations": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "low": 8,
    "info": 0
  },
  "started_at": "2024-03-15T14:32:20Z",
  "completed_at": "2024-03-15T14:35:42Z"
}
```

## List Scans

```http theme={null}
GET /v1/scans?repository_id=repo_123&limit=10
```

**Response**:

```json theme={null}
{
  "scans": [
    {
      "scan_id": "scan_456",
      "status": "COMPLETED",
      "created_at": "2024-03-15T14:32:18Z"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 42
  }
}
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Violations API" icon="bug" href="/api-reference/violations">
    Get violation data
  </Card>

  <Card title="Repositories API" icon="folder" href="/api-reference/repositories">
    Manage repositories
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /scans
openapi: 3.0.3
info:
  title: CodeThreat API
  version: 1.0.0
  description: >-
    Autonomous AppSec Engineering Platform - Comprehensive REST API for security
    scanning, vulnerability management, and DevSecOps automation. Integrate
    CodeThreat's powerful security analysis into your CI/CD pipeline, CLI tools,
    and third-party applications.
  contact:
    name: CodeThreat Support
    url: https://codethreat.com/support
    email: support@codethreat.com
  license:
    name: Proprietary
    url: https://codethreat.com/terms
  termsOfService: https://codethreat.com/terms
servers:
  - url: https://app.codethreat.com/api/v1
    description: Production Server
  - url: http://localhost:3000/api/v1
    description: Development Server
security:
  - ApiKeyAuth: []
tags:
  - name: Organizations
    description: Organization management and configuration
  - name: Repositories
    description: Repository management and status tracking
  - name: Scans
    description: Security scan execution, monitoring, and results
  - name: Violations
    description: Security violation tracking and management
  - name: CLI
    description: CLI-specific endpoints for authentication and configuration
  - name: System
    description: Health checks and system status
paths:
  /scans:
    get:
      tags:
        - Scans
      summary: List scans
      description: Get a paginated list of security scans
      operationId: listScans
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: repositoryId
          in: query
          description: Filter by repository
          schema:
            type: string
        - name: status
          in: query
          description: Filter by status
          schema:
            type: string
            enum:
              - PENDING
              - SCANNING
              - COMPLETED
              - FAILED
        - name: scanType
          in: query
          description: Filter by scan type
          schema:
            type: string
            enum:
              - sast
              - sca
              - secrets
              - iac
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - startedAt
              - completedAt
              - status
            default: startedAt
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanListResponse'
components:
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      description: Items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  schemas:
    ScanListResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Scan'
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    Scan:
      type: object
      properties:
        id:
          type: string
        repositoryId:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - SCANNING
            - COMPLETED
            - FAILED
        scanTypes:
          type: array
          items:
            type: string
            enum:
              - sast
              - sca
              - secrets
              - iac
        branch:
          type: string
        commit:
          type: string
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        duration:
          type: integer
        violationCount:
          type: object
          properties:
            critical:
              type: integer
            high:
              type: integer
            medium:
              type: integer
            low:
              type: integer
            info:
              type: integer
    Pagination:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
        hasNext:
          type: boolean
        hasPrev:
          type: boolean
    ResponseMeta:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        version:
          type: string
        requestId:
          type: string
        organizationId:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication. Generate from your organization settings.

````