compuute-se Scan API

openapi: 3.2.0
info:
  title: compuute--api Scan API
  description: 'HTTP + MCP wrapper around compuute-scan, the MCP-specific static security scanner. Designed for agent-callable consumption: idempotent retries, cache headers, OpenAPI spec, MCP tool exposure.'
  contact:
    name: Compuute AB
    url: https://compuute.se/
    email: daniel@compuute.se
  license:
    name: MIT
    url: https://github.com/Compuute/compuute-scan-api/blob/main/LICENSE
  version: 0.5.0
tags:
- name: Scan
paths:
  /v1/scan:
    post:
      tags:
      - Scan
      summary: Scan a public GitHub MCP-server repo with compuute-scan
      description: 'Clones a public GitHub repository and runs compuute-scan''s L0+L1 static analysis (38 MCP-specific rules across 8 languages: TS/JS, Python, Go, Rust, C#, Java, Kotlin). Returns a structured summary with severity counts, a coarse 0-100 score, recommendation, and the 10 most severe findings inline.


        **Idempotency:** supply `Idempotency-Key` header (UUIDv4 recommended). Identical key returns the cached scan for 24h with no re-execution.


        **Caching:** responses are `Cache-Control: public, max-age=1800` with an `ETag`. Send `If-None-Match` on revisit for a 304 Not Modified.


        **Limits:** repo must be public, <200 MB, clone <60s, scan <120s.


        **When NOT to use:** for exploitability assessment of a specific code path (this is pattern matching — book a manual audit at compuute.se/audit for that). For private repos, use the on-prem CLI: `npx compuute-scan ./repo`.'
      operationId: scan_endpoint_v1_scan_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: If-None-Match
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
      responses:
        '200':
          description: Scan completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '304':
          description: Not Modified — caller's ETag is current.
        '413':
          description: Repo exceeds 200 MB size limit.
        '422':
          description: Invalid GitHub URL or repo not found.
        '502':
          description: Scanner failure (compuute-scan returned no/bad JSON).
        '504':
          description: Clone or scan timeout.
  /v1/scan/info:
    get:
      tags:
      - Scan
      summary: Scanner version + capabilities (for agents deciding whether to call /v1/scan)
      description: Reports the bundled compuute-scan version, supported languages, layers covered, and rate limits. Use this to decide whether the scanner meets your freshness/coverage criteria before calling /v1/scan.
      operationId: scan_info_v1_scan_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    Performance:
      properties:
        clone_seconds:
          type: number
          title: Clone Seconds
        scan_seconds:
          type: number
          title: Scan Seconds
        repo_size_bytes:
          type: integer
          title: Repo Size Bytes
      type: object
      required:
      - clone_seconds
      - scan_seconds
      - repo_size_bytes
      title: Performance
    FindingSummary:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        severity:
          anyOf:
          - type: string
          - type: 'null'
          title: Severity
        file:
          anyOf:
          - type: string
          - type: 'null'
          title: File
        line:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line
        owasp:
          anyOf:
          - type: string
          - type: 'null'
          title: Owasp
        cwe:
          anyOf:
          - type: string
          - type: 'null'
          title: Cwe
      type: object
      title: FindingSummary
    ScanRequest:
      properties:
        repo_url:
          type: string
          maxLength: 256
          minLength: 20
          title: Repo Url
          description: 'Public GitHub HTTPS URL. Only github.com is accepted in this version. Repo must be public and < 200 MB. Example: https://github.com/org/repo'
      additionalProperties: false
      type: object
      required:
      - repo_url
      title: ScanRequest
      description: POST /v1/scan input.
      examples:
      - repo_url: https://github.com/Compuute/compuute-scan
      - repo_url: https://github.com/modelcontextprotocol/servers
    ScannerInfo:
      properties:
        name:
          type: string
          title: Name
        version:
          type: string
          title: Version
        layers_covered:
          items:
            type: string
          type: array
          title: Layers Covered
      type: object
      required:
      - name
      - version
      title: ScannerInfo
    ScanResponse:
      properties:
        repo_url:
          type: string
          title: Repo Url
        scanned_at:
          type: string
          title: Scanned At
          description: UTC timestamp when the scan started.
        scanner:
          $ref: '#/components/schemas/ScannerInfo'
        summary:
          $ref: '#/components/schemas/SeveritySummary'
        score:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Score
          description: 0-100, higher safer.
        recommendation:
          type: string
          title: Recommendation
        findings_count:
          type: integer
          title: Findings Count
        top_findings:
          items:
            $ref: '#/components/schemas/FindingSummary'
          type: array
          title: Top Findings
        l0_discovery:
          additionalProperties: true
          type: object
          title: L0 Discovery
        performance:
          $ref: '#/components/schemas/Performance'
        _disclaimer:
          type: string
          title: Disclaimer
          description: 'Mandatory disclaimer: compuute-scan is a static analyzer. Findings indicate vulnerable patterns are *present*; exploitability requires manual dataflow review.'
      type: object
      required:
      - repo_url
      - scanned_at
      - scanner
      - summary
      - score
      - recommendation
      - findings_count
      - performance
      - _disclaimer
      title: ScanResponse
      description: 'POST /v1/scan response.


        Stable schema. Agents may rely on field names. Top-level fields cover

        summary + score + recommendation; `top_findings` is bounded to 10 for

        payload size — full findings list is a v2 enhancement.'
      examples:
      - _disclaimer: PATTERN MATCH — compuute-scan is a static analyzer...
        findings_count: 5
        l0_discovery: {}
        performance:
          clone_seconds: 1.2
          repo_size_bytes: 41234
          scan_seconds: 0.5
        recommendation: REVIEW — 3 high finding(s). Triage individually.
        repo_url: https://github.com/org/example-mcp
        scanned_at: '2026-05-23T08:00:00+00:00'
        scanner:
          layers_covered:
          - L0
          - L1
          name: compuute-scan
          version: 0.6.2
        score: 82
        summary:
          critical: 0
          files_scanned: 44
          high: 3
          info: 0
          low: 0
          medium: 2
        top_findings: []
    SeveritySummary:
      properties:
        critical:
          type: integer
          title: Critical
          default: 0
        high:
          type: integer
          title: High
          default: 0
        medium:
          type: integer
          title: Medium
          default: 0
        low:
          type: integer
          title: Low
          default: 0
        info:
          type: integer
          title: Info
          default: 0
        files_scanned:
          type: integer
          title: Files Scanned
          default: 0
      type: object
      title: SeveritySummary