Socket Fixes API
List available fixes — version bumps, patches, and overrides — for vulnerable or risky dependencies in an organization's scanned projects. Powers Socket's auto-fix pull-request generation.
OpenAPI Specification
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