Socket fixes API

openapi: 3.0.0
info:
  description: Specification of the Socket API endpoints
  title: API Endpoints alerts fixes API
  version: '0'
servers:
- url: https://api.socket.dev/v0
tags:
- name: fixes
paths:
  /orgs/{org_slug}/fixes:
    get:
      tags:
      - fixes
      summary: Fetch fixes for vulnerabilities in a repository, scan, or uploaded manifest
      operationId: fetch-fixes
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: repo_slug
        in: query
        required: false
        description: The slug of the repository to fetch fixes for (e.g. "my-repo" or "my-org/my-repo"). Use the full org/repo path to disambiguate when multiple GitHub orgs share the same repo name. Computes fixes based on the latest scan on the default branch
        schema:
          type: string
      - name: full_scan_id
        in: query
        required: false
        description: The ID of the scan to fetch fixes for
        schema:
          type: string
      - name: tar_hash
        in: query
        required: false
        description: A tarball hash from the upload-manifest-files endpoint. Mutually exclusive with repo_slug and full_scan_id.
        schema:
          type: string
      - name: vulnerability_ids
        in: query
        required: true
        description: Comma-separated list of GHSA or CVE IDs, or "*" for all vulnerabilities
        schema:
          type: string
      - name: allow_major_updates
        in: query
        required: true
        description: Whether to allow major version updates in fixes
        schema:
          type: boolean
          default: false
      - name: minimum_release_age
        in: query
        required: false
        description: Minimum release age for fixes packages (e.g., "1h", "2d", "1w"). Higher values reduces risk of installing recently released untested package versions.
        schema:
          type: string
          default: 0d
      - name: include_details
        in: query
        required: false
        description: Whether to include advisory details in the response
        schema:
          type: boolean
          default: false
      - name: include_responsible_direct_dependencies
        in: query
        required: false
        description: Set to include the direct dependencies responsible for introducing the dependency or dependencies with the vulnerability in the response
        schema:
          type: boolean
          default: false
      - name: include_all_detected_ghsas
        in: query
        required: false
        description: Set to include an allDetectedGhsas field listing every GHSA detected in the project, regardless of the vulnerability_ids filter. Useful for CLI clients that request a specific GHSA and want to show the user which GHSAs actually exist when the request has no overlap.
        schema:
          type: boolean
          default: false
      - name: include_stateful_alert_ids
        in: query
        required: false
        description: Set to include a statefulAlertIds map (GHSA ID → array of open stateful alert IDs detected in this organization) in the response. Lets callers correlate /fixes results back to the alert IDs surfaced by /v0/orgs/{org_slug}/alerts. Org-scoped only — multiple alerts across repos/branches may share a GHSA. Off by default to avoid an extra ClickHouse round-trip.
        schema:
          type: boolean
          default: false
      - name: autofix_run_id
        in: query
        required: false
        description: The id of an autofix-or-upgrade-cli-run record (created via /fixes/register-autofix-or-upgrade-cli-run) to associate this computation with. When set, the server records per-GHSA fix-computation telemetry into autofix_compute_vulnerability and updates the run's autofix_run row, mirroring the legacy /v0/fixes/compute-fixes endpoint. The caller must own the run's organization; foreign-org or unknown ids return 404.
        schema:
          type: string
      security:
      - bearerAuth:
        - fixes:list
      - basicAuth:
        - fixes:list
      description: "Fetches available fixes for vulnerabilities in a repository, scan, or uploaded manifest.\nRequires exactly one of repo_slug, full_scan_id, or tar_hash, as well as vulnerability_ids to be provided.\nvulnerability_ids can be a comma-separated list of GHSA or CVE IDs, or \"*\" for all vulnerabilities.\n\n## Response Structure\n\nThe response contains a `fixDetails` object where each key is a vulnerability ID (GHSA or CVE) and the value is a discriminated union based on the `type` field.\n\n### Common Fields\n\nAll response variants include:\n- `type`: Discriminator field (one of: \"fixFound\", \"partialFixFound\", \"noFixAvailable\", \"fixNotApplicable\", \"errorComputingFix\")\n- `value`: Object containing the variant-specific data\n\nThe `value` object always contains:\n- `ghsa`: string | null - The GHSA ID\n- `cve`: string | null - The CVE ID (if available)\n- `advisoryDetails`: object | null - Advisory details (only if include_details=true)\n\n### Response Variants\n\n**fixFound**: A complete fix is available for all vulnerable packages\n- `value.fixDetails.fixes`: Array of fix objects, each containing:\n  - `purl`: Package URL to upgrade\n  - `fixedVersion`: Version to upgrade to\n  - `manifestFiles`: Array of manifest files containing the package\n  - `updateType`: \"patch\" | \"minor\" | \"major\" | \"unknown\"\n- `value.fixDetails.responsibleDirectDependencies`: (optional) Map of direct dependencies responsible for the vulnerability\n\n**partialFixFound**: Fixes available for some but not all vulnerable packages\n- Same as fixFound, plus:\n- `value.fixDetails.unfixablePurls`: Array of packages that cannot be fixed, each containing:\n  - `purl`: Package URL\n  - `manifestFiles`: Array of manifest files\n  - `reasons`: Human-readable explanations of why the package cannot be upgraded. May contain multiple distinct entries when different dependency chains are blocked for different causes (e.g. one chain has no compatible upstream version; another would require a major version bump skipped by `--no-major-updates`).\n\n**noFixAvailable**: No fix exists for this vulnerability (no patched version published)\n- `value.vulnerableArtifacts`: Array of vulnerable packages with their manifest files; each carries a static `reasons` entry stating that no patched version has been published\n\n**fixNotApplicable**: A patched version of the vulnerable package exists but cannot be applied. The most common cause is that there is no upgrade path through the dependency tree — for example, given a chain `App → A@1.0.0 → B@1.0.0` where `B < 2.0.0` is vulnerable, if no version of `A` accepts `B@2.0.0` the fix cannot be applied without a manual override (e.g. `pnpm overrides`). Other causes include callers passing `--no-major-updates` when the only patched version is a major bump.\n- `value.vulnerableArtifacts`: Array of vulnerable packages with their manifest files, each with per-artifact `reasons` explaining why the fix could not be applied (omitted when no explanation is available)\n\n**errorComputingFix**: An error occurred while computing fixes\n- `value.message`: Error description\n\n### Fix version alignment\n\nWhen several requested vulnerabilities are fixed by upgrading the same package, their fix entries carry the SAME `fixedVersion` — the server computes a version that clears all of them together and verifies it against each advisory's affected ranges. Clients can apply the fixes per package without reconciling versions. Only when no single in-policy version fixes all advisories on a package (non-monotonic affected ranges) can entries differ; each is then the minimal upgrade for its own advisory.\n\n### Advisory Details (when include_details=true)\n\n- `title`: string | null\n- `description`: string | null\n- `cwes`: string[] - CWE identifiers\n- `severity`: \"LOW\" | \"MODERATE\" | \"HIGH\" | \"CRITICAL\"\n- `cvssVector`: string | null\n- `publishedAt`: string (ISO date)\n- `kev`: boolean - Whether it's a Known Exploited Vulnerability\n- `epss`: number | null - Exploit Prediction Scoring System score\n- `affectedPurls`: Array of affected packages with version ranges\n\n### Stateful Alert IDs (when include_stateful_alert_ids=true)\n\nTop-level `statefulAlertIds` field — a map of GHSA ID → array of open stateful alert IDs (the human-readable `SOCKET-XXX-N` identifiers also returned by `/v0/orgs/{org_slug}/alerts`). The lookup is org-scoped, so the same GHSA may map to multiple alert IDs when it appears in alerts across different repos or branches. Callers that need a repo/branch filter should intersect this map with results from the alerts API.\n\nThe lookup honors the same scan-type visibility as `/v0/orgs/{org_slug}/alerts` — when the `enableTier1OrgAlertApiRead` feature flag is off for the org, only `socket` scans are visible (no `socket_tier1`).\n\nNote on scopes: this field surfaces identifiers that are otherwise reachable via `/v0/orgs/{org_slug}/alerts` (which requires `alerts:list`). The fixes route is gated on `fixes:list` alone; the GHSAs the alert IDs are keyed to are already part of every `/fixes` response, and exposing the matching alert IDs through this opt-in flag is intentional — it lets a caller with only `fixes:list` complete the correlation back to /alerts on a token that already has that scope. If you require strict scope separation, do not enable this flag.\n\nThis endpoint consumes 10 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- fixes:list"
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  fixDetails:
                    type: object
                    additionalProperties:
                      type: object
                      description: ''
                      default: null
                    properties: {}
                    description: ''
                  allDetectedGhsas:
                    type: array
                    items:
                      type: string
                      description: ''
                      default: GHSA ID of a vulnerability detected in the project
                    description: All vulnerability GHSA IDs detected in the project, regardless of the vulnerability_ids filter. Only present when include_all_detected_ghsas=true is set.
                  statefulAlertIds:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                        description: ''
                        default: Stateful alert ID (the human-readable SOCKET-XXX-N identifier from /v0/orgs/{org_slug}/alerts)
                      description: ''
                    properties: {}
                    description: Map of GHSA ID → open stateful alert IDs detected in this organization. Lets callers correlate /fixes results back to the alert IDs they see in /v0/orgs/{org_slug}/alerts. Org-scoped, not repo/branch-scoped — the same GHSA may surface in multiple alerts across repos. Only present when include_stateful_alert_ids=true is set.
                required:
                - fixDetails
          description: Fix details for requested vulnerabilities
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
components:
  responses:
    SocketForbidden:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    SocketBadRequest:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Bad request
    SocketNotFoundResponse:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    SocketTooManyRequestsResponse:
      description: Insufficient quota for API route
      headers:
        Retry-After:
          description: 'Retry contacting the endpoint *at least* after seconds.

            See https://tools.ietf.org/html/rfc7231#section-7.1.3'
          schema:
            format: int32
            type: integer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
    SocketUnauthorized:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization Tokens can be passed as a Bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Organization Tokens can be passed as the user field in basic auth