Compute and inspect diff scans between two full scans — the engine that powers Socket's pull-request comments. Identifies added, removed, and modified dependencies with their security implications. Returns added/removed alerts in JSON or GFM markdown. Diff scans can be created from full-scan IDs or from a target repo branch.
openapi: 3.0.0
info:
description: Socket diff scans API endpoints.
title: Socket Diff Scans API
version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
/orgs/{org_slug}/diff-scans:
get:
tags:
- diff-scans
summary: List diff scans
operationId: listOrgDiffScans
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: sort
in: query
required: false
description: Specify sort field.
schema:
type: string
enum:
- created_at
- updated_at
default: created_at
- name: direction
in: query
required: false
description: Specify sort direction.
schema:
type: string
enum:
- asc
- desc
default: desc
- name: per_page
in: query
required: false
description: Specify the maximum number of results to return per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
required: false
description: Cursor for pagination. Use the next_cursor or prev_cursor from previous responses.
schema:
type: string
- name: repository_id
in: query
required: false
description: Filter by repository ID.
schema:
type: string
- name: before_full_scan_id
in: query
required: false
description: Filter by before full scan ID.
schema:
type: string
- name: after_full_scan_id
in: query
required: false
description: Filter by after full scan ID.
schema:
type: string
security:
- bearerAuth:
- diff-scans:list
- basicAuth:
- diff-scans:list
description: 'Returns a paginated list of all diff scans in an organization.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- diff-scans:list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
results:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
before_full_scan_id:
type: string
description: ''
default: ''
after_full_scan_id:
type: string
description: ''
default: ''
description:
type: string
description: ''
default: ''
nullable: true
external_href:
type: string
description: ''
default: ''
nullable: true
merge:
type: boolean
default: false
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
required:
- after_full_scan_id
- api_url
- before_full_scan_id
- created_at
- description
- external_href
- html_url
- id
- merge
- organization_id
- repository_id
- updated_at
description: ''
next_page_href:
type: string
description: ''
default: ''
nullable: true
next_cursor:
type: string
description: ''
default: ''
nullable: true
required:
- next_cursor
- next_page_href
- results
description: Lists diff scans for the specified organization.
'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: {}
/orgs/{org_slug}/diff-scans/{diff_scan_id}:
get:
tags:
- diff-scans
summary: Get diff scan
operationId: getDiffScanById
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: diff_scan_id
in: path
required: true
description: The ID of the diff scan
schema:
type: string
format: uuid
- name: omit_license_details
in: query
required: false
description: Omit license details in the response. This can reduce the size of the response significantly, but will not include license information for the artifacts.
schema:
type: boolean
default: false
- name: omit_unchanged
in: query
required: false
description: Omit unchanged artifacts from the response. When set to true, the unchanged field will be set to null.
schema:
type: boolean
default: false
- name: cached
in: query
required: false
description: 'Return cached immutable scan results. When enabled and results are cached, returns the pre-computed scan. When results are not yet cached, returns 202 Accepted and enqueues a background
job. Note: When cached=true, the omit_license_details parameter is ignored as cached results always includes license details.'
schema:
type: boolean
default: false
security:
- bearerAuth:
- diff-scans:list
- basicAuth:
- diff-scans:list
description: 'Get the difference between two full scans from an existing diff scan resource.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- diff-scans:list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
diff_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
before_full_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
organization_slug:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
repository_slug:
type: string
description: ''
default: ''
branch:
type: string
description: ''
default: ''
nullable: true
commit_message:
type: string
description: ''
default: ''
nullable: true
commit_hash:
type: string
description: ''
default: ''
nullable: true
pull_request:
type: integer
description: ''
default: 0
nullable: true
committers:
type: array
items:
type: string
description: ''
default: ''
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
required:
- api_url
- branch
- commit_hash
- commit_message
- committers
- created_at
- html_url
- id
- organization_id
- organization_slug
- pull_request
- repository_id
- repository_slug
- updated_at
after_full_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
organization_slug:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
repository_slug:
type: string
description: ''
default: ''
branch:
type: string
description: ''
default: ''
nullable: true
commit_message:
type: string
description: ''
default: ''
nullable: true
commit_hash:
type: string
description: ''
default: ''
nullable: true
pull_request:
type: integer
description: ''
default: 0
nullable: true
committers:
type: array
items:
type: string
description: ''
default: ''
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
required:
- api_url
- branch
- commit_hash
- commit_message
- committers
- created_at
- html_url
- id
- organization_id
- organization_slug
- pull_request
- repository_id
- repository_slug
- updated_at
description:
type: string
description: ''
default: ''
nullable: true
external_href:
type: string
description: ''
default: ''
nullable: true
merge:
type: boolean
default: false
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
artifacts:
type: object
additionalProperties: false
description: ''
properties:
added:
type: array
items:
$ref: '#/components/schemas/SocketDiffArtifact'
description: ''
removed:
type: array
items:
$ref: '#/components/schemas/SocketDiffArtifact'
description: ''
unchanged:
type: array
items:
$ref: '#/components/schemas/SocketDiffArtifact'
description: ''
nullable: true
replaced:
type: array
items:
$ref: '#/components/schemas/SocketDiffArtifact'
description: ''
updated:
type: array
items:
$ref: '#/components/schemas/SocketDiffArtifact'
description: ''
required:
- added
- removed
- replaced
- unchanged
- updated
required:
- after_full_scan
- api_url
- artifacts
- before_full_scan
- created_at
- description
- external_href
- html_url
- id
- merge
- organization_id
- repository_id
- updated_at
required:
- diff_scan
description: The difference between the two Full Scans in the diff scan.
'202':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
status:
type: string
description: ''
default: processing
id:
type: string
description: ''
default: ''
required:
- id
- status
description: Scan is being processed. Poll again later to retrieve results.
'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: {}
delete:
tags:
- diff-scans
summary: Delete diff scan
operationId: deleteOrgDiffScan
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: diff_scan_id
in: path
required: true
description: The ID of the diff scan
schema:
type: string
format: uuid
security:
- bearerAuth:
- diff-scans:delete
- basicAuth:
- diff-scans:delete
description: 'Delete an existing diff scan.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- diff-scans:delete'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
status:
type: string
description: ''
default: ok
required:
- status
description: Success
'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: {}
/orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm:
get:
tags:
- diff-scans
summary: SCM Comment for Diff Scan
operationId: GetDiffScanGfm
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: diff_scan_id
in: path
required: true
description: The ID of the diff scan
schema:
type: string
format: uuid
- name: github_installation_id
in: query
required: false
description: The ID of the GitHub installation. This will be used to get the GitHub installation settings. If not provided, the default GitHub installation settings will be used.
schema:
type: string
security:
- bearerAuth:
- diff-scans:list
- basicAuth:
- diff-scans:list
description: 'Get the dependency overview and dependency alert comments in GitHub flavored markdown for an existing diff scan.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- diff-scans:list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
diff_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
before_full_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
organization_slug:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
repository_slug:
type: string
description: ''
default: ''
branch:
type: string
description: ''
default: ''
nullable: true
commit_message:
type: string
description: ''
default: ''
nullable: true
commit_hash:
type: string
description: ''
default: ''
nullable: true
pull_request:
type: integer
description: ''
default: 0
nullable: true
committers:
type: array
items:
type: string
description: ''
default: ''
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
required:
- api_url
- branch
- commit_hash
- commit_message
- committers
- created_at
- html_url
- id
- organization_id
- organization_slug
- pull_request
- repository_id
- repository_slug
- updated_at
after_full_scan:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
created_at:
type: string
description: ''
default: ''
updated_at:
type: string
description: ''
default: ''
organization_id:
type: string
description: ''
default: ''
organization_slug:
type: string
description: ''
default: ''
repository_id:
type: string
description: ''
default: ''
repository_slug:
type: string
description: ''
default: ''
branch:
type: string
description: ''
default: ''
nullable: true
commit_message:
type: string
description: ''
default: ''
nullable: true
commit_hash:
type: string
description: ''
default: ''
nullable: true
pull_request:
type: integer
description: ''
default: 0
nullable: true
committers:
type: array
items:
type: string
description: ''
default: ''
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
required:
- api_url
- branch
- commit_hash
- commit_message
- committers
- created_at
- html_url
- id
- organization_id
- organization_slug
- pull_request
- repository_id
- repository_slug
- updated_at
description:
type: string
description: ''
default: ''
nullable: true
external_href:
type: string
description: ''
default: ''
nullable: true
merge:
type: boolean
default: false
description: ''
html_url:
type: string
description: ''
default: ''
nullable: true
api_url:
type: string
description: ''
default: ''
nullable: true
gfm:
type: object
additionalProperties: false
description: ''
properties:
overview:
type: string
description: ''
default: ''
alerts:
type: string
description: ''
default: ''
required:
- alerts
- overview
required:
- after_full_scan
- api_url
- before_full_scan
- created_at
- desc
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-diff-scans-api-openapi.yml