openapi: 3.0.0
info:
  description: Socket fixes API endpoints.
  title: Socket Fixes API
  version: '0'
servers:
- url: https://api.socket.dev/v0
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: 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\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\n\n**errorComputingFix**: An error occurred while computing\
        \ fixes\n- `value.message`: Error description\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\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.
                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:
  requestBodies: {}
  responses:
    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
    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
    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
    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
    SocketInternalServerError:
      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: Internal server error
    SocketConflict:
      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 already exists
    SocketGone:
      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: Gone
  schemas: {}
  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