compuute-se Scan X402 API

openapi: 3.2.0
info:
  title: compuute-scan-api Scan X402 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-x402
paths:
  /v1/scan/pay:
    post:
      tags:
      - scan-x402
      summary: Pay-per-scan via x402 (no API key required)
      description: 'Agent-callable scan endpoint billed per-call via x402 micropayments on Base L2 USDC. Current price: $0.10 per scan.


        **Flow (x402 v2):**

        1. POST without `X-Payment` header → 402 with x402 payment requirements.

        2. Agent signs the payment (EIP-3009 USDC transfer) per the `accepts` entry.

        3. POST with `X-Payment: ` header → server verifies via the facilitator, runs the scan, settles, and returns the result with a `PAYMENT-RESPONSE` header containing the settlement receipt.


        **When NOT to use:** if the free tier suffices, use `/v1/scan` instead. This endpoint is for agents paying autonomously.'
      operationId: scan_with_x402_v1_scan_pay_post
      parameters:
      - name: X-Payment
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      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'
        '402':
          description: Payment required. Body is an x402 v2 PaymentRequired object.
        '413':
          description: Repo exceeds size limit.
        '422':
          description: Invalid GitHub URL or repo not found.
        '503':
          description: x402 not configured on this server.
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