Create, list, fetch, rescan, archive, and export full-scan reports for an organization's repos. Upload manifest files (package.json, requirements.txt, go.mod, pom.xml, Cargo.toml, etc.) and Socket returns a full dependency graph with alerts. Exports include CDX (CycloneDX), SPDX, OpenVEX, CSV, PDF, and GFM diff formats.
openapi: 3.0.0
info:
description: Socket full scans API endpoints.
title: Socket Full Scans API
version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
/orgs/{org_slug}/full-scans:
get:
tags:
- full-scans
summary: List full scans
operationId: getOrgFullScanList
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 order.
schema:
type: string
enum:
- name
- created_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: 30
- name: page
in: query
required: false
description: The page number to return when using offset-style pagination. Ignored when cursor pagination is used.
schema:
type: integer
minimum: 1
default: 1
- name: startAfterCursor
in: query
required: false
description: Cursor token for pagination. Pass the returned nextPageCursor from previous responses to fetch the next set of results.
schema:
type: string
- name: use_cursor
in: query
required: false
description: Set to true on the first request to opt into cursor-based pagination.
schema:
type: boolean
default: false
- name: from
in: query
required: false
description: A Unix timestamp in seconds that filters full-scans prior to the date.
schema:
type: string
- name: workspace
in: query
required: false
description: A repository workspace to filter full-scans by.
schema:
type: string
- name: repo
in: query
required: false
description: A repository slug to filter full-scans by.
schema:
type: string
- name: branch
in: query
required: false
description: A branch name to filter full-scans by.
schema:
type: string
- name: pull_request
in: query
required: false
description: A PR number to filter full-scans by.
schema:
type: string
- name: commit_hash
in: query
required: false
description: A commit hash to filter full-scans by.
schema:
type: string
- name: scan_type
in: query
required: false
description: A scan type to filter full-scans by (e.g. socket, socket_tier1, socket_basics).
schema:
type: string
security:
- bearerAuth:
- full-scans:list
- basicAuth:
- full-scans:list
description: 'Returns a paginated list of all full scans in an org, excluding SBOM artifacts.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-scans:list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
results:
type: array
items:
type: object
additionalProperties: false
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
workspace:
type: string
description: ''
default: ''
repo:
type: string
description: ''
default: ''
html_report_url:
type: string
description: ''
default: ''
integration_type:
type: string
description: ''
default: ''
nullable: true
integration_repo_url:
type: string
description: ''
default: ''
integration_branch_url:
type: string
description: ''
default: ''
nullable: true
integration_commit_url:
type: string
description: ''
default: ''
nullable: true
integration_pull_request_url:
type: string
description: ''
default: ''
nullable: true
scan_type:
type: string
description: ''
default: ''
nullable: true
scan_state:
type: string
enum:
- pending
- precrawl
- resolve
- scan
description: The current processing status of the SBOM
default: pending
nullable: true
description: ''
description: ''
nextPageCursor:
type: string
description: ''
default: ''
nullable: true
nextPage:
type: integer
description: ''
default: 0
nullable: true
required:
- nextPage
- nextPageCursor
- results
description: Lists repositories for the specified organization. The authenticated user must be a member of the 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: {}
post:
tags:
- full-scans
summary: Create full scan
operationId: CreateOrgFullScan
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: repo
in: query
required: true
description: The slug of the repository to associate the full-scan with.
schema:
type: string
- name: workspace
in: query
required: false
description: The workspace of the repository to associate the full-scan with.
schema:
type: string
- name: branch
in: query
required: false
description: 'The branch name to associate the full-scan with. Branch names must follow Git branch name rules: be 1–255 characters long; cannot be exactly @; cannot begin or end with /, ., or .lock;
cannot contain "//", "..", or "@{"; and cannot include control characters, spaces, or any of ~^:?*[.'
schema:
type: string
- name: commit_message
in: query
required: false
description: The commit message to associate the full-scan with.
schema:
type: string
- name: commit_hash
in: query
required: false
description: The commit hash to associate the full-scan with.
schema:
type: string
- name: pull_request
in: query
required: false
description: The pull request number to associate the full-scan with.
schema:
type: integer
minimum: 1
- name: committers
in: query
required: false
description: The committers to associate with the full-scan. Set query more than once to set multiple.
schema:
type: string
- name: integration_type
in: query
required: false
description: The integration type to associate the full-scan with. Defaults to "Api" if omitted.
schema:
type: string
enum:
- api
- github
- gitlab
- bitbucket
- azure
- web
- name: integration_org_slug
in: query
required: false
description: The integration org slug to associate the full-scan with. If omitted, the Socket org name will be used. This is used to generate links and badges.
schema:
type: string
- name: make_default_branch
in: query
required: false
description: Set the default branch of the repository to the branch of this full-scan. A branch name is required with this option.
schema:
type: boolean
default: false
- name: set_as_pending_head
in: query
required: false
description: Designate this full-scan as the latest scan of a given branch. Default branch head scans are included in org alerts. This is only supported on the default branch. A branch name is required
with this option.
schema:
type: boolean
default: false
- name: tmp
in: query
required: false
description: Create a temporary full-scan that is not listed in the reports dashboard. Cannot be used when set_as_pending_head=true.
schema:
type: boolean
default: false
- name: scan_type
in: query
required: false
description: The type of scan to perform. Defaults to 'socket'. Must be 32 characters or less. Used for categorizing multiple SBOM heads per repository branch.
schema:
type: string
default: socket
requestBody:
content:
multipart/form-data:
schema:
type: object
additionalProperties:
type: string
default:
type: Buffer
data: []
format: binary
description: ''
properties: {}
description: ''
required: false
security:
- bearerAuth:
- full-scans:create
- basicAuth:
- full-scans:create
description: 'Create a full scan from a set of package manifest files. Returns a full scan including all SBOM artifacts.
To get a list of supported filetypes that can be uploaded in a full-scan, see the [Get supported file types](/reference/getsupportedfiles) endpoint.
The maximum number of files you can upload at a time is 5000 and each file can be no bigger than 268 MB.
**Query Parameters:**
- `scan_type` (optional): The type of scan to perform. Defaults to ''socket''. Must be 32 characters or less. Used for categorizing multiple SBOM heads per repository branch.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-scans:create'
responses:
'201':
content:
application/json:
schema:
type: object
additionalProperties: false
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
workspace:
type: string
description: ''
default: ''
repo:
type: string
description: ''
default: ''
html_report_url:
type: string
description: ''
default: ''
integration_type:
type: string
description: ''
default: ''
nullable: true
integration_repo_url:
type: string
description: ''
default: ''
integration_branch_url:
type: string
description: ''
default: ''
nullable: true
integration_commit_url:
type: string
description: ''
default: ''
nullable: true
integration_pull_request_url:
type: string
description: ''
default: ''
nullable: true
scan_type:
type: string
description: ''
default: ''
nullable: true
scan_state:
type: string
enum:
- pending
- precrawl
- resolve
- scan
description: The current processing status of the SBOM
default: pending
nullable: true
unmatchedFiles:
type: array
items:
type: string
description: ''
default: ''
description: ''
description: ''
description: The details of the created full scan.
'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}/full-scans/{full_scan_id}:
get:
tags:
- full-scans
summary: Stream full scan
operationId: getOrgFullScan
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: full_scan_id
in: path
required: true
description: The ID of the full scan
schema:
type: string
- name: include_alert_priority_details
in: query
required: false
description: Control which alert priority fields to include in the response. Set to "true" to include all fields, "false" to exclude all fields, or specify individual fields like "components,formula"
to include only those fields.
schema:
oneOf:
- type: boolean
default: false
- type: array
items:
type: string
enum:
- component
- formula
default: false
- name: include_scores
in: query
required: true
description: Include scores event in the response. include_scores_details implies this flag
schema:
type: boolean
default: false
- name: include_scores_details
in: query
required: false
description: Control which score detail fields to include in the scores event. Set to "true" to include all fields, "false" to exclude all fields, or specify individual fields like "components,formula"
to include only those fields.
schema:
oneOf:
- type: boolean
default: false
- type: array
items:
type: string
enum:
- components
- formula
default: false
- name: include_license_details
in: query
required: true
description: Include license details in the response. This can increase the response size significantly.
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.
schema:
type: boolean
default: false
security:
- bearerAuth:
- full-scans:list
- basicAuth:
- full-scans:list
description: 'Stream all SBOM artifacts for a full scan.
This endpoint returns the latest, available alert data for artifacts in the full scan (stale while revalidate).
Actively running analysis will be returned when available on subsequent runs.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-scans:list'
responses:
'200':
content:
application/x-ndjson:
schema:
anyOf:
- $ref: '#/components/schemas/SocketArtifact'
- type: object
additionalProperties: false
properties:
_type:
type: string
enum:
- scores
value:
$ref: '#/components/schemas/SocketSBOMScore'
required:
- _type
- value
description: Socket issue lists and scores for all packages, followed by a final scores event
'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:
- full-scans
summary: Delete full scan
operationId: deleteOrgFullScan
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: full_scan_id
in: path
required: true
description: The ID of the full scan
schema:
type: string
security:
- bearerAuth:
- full-scans:delete
- basicAuth:
- full-scans:delete
description: 'Delete an existing full scan.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-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}/full-scans/{full_scan_id}/metadata:
get:
tags:
- full-scans
summary: Get full scan metadata
operationId: getOrgFullScanMetadata
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: full_scan_id
in: path
required: true
description: The ID of the full scan
schema:
type: string
security:
- bearerAuth:
- full-scans:list
- basicAuth:
- full-scans:list
description: 'Get metadata for a single full scan
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-scans:list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
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
workspace:
type: string
description: ''
default: ''
repo:
type: string
description: ''
default: ''
html_report_url:
type: string
description: ''
default: ''
integration_type:
type: string
description: ''
default: ''
nullable: true
integration_repo_url:
type: string
description: ''
default: ''
integration_branch_url:
type: string
description: ''
default: ''
nullable: true
integration_commit_url:
type: string
description: ''
default: ''
nullable: true
integration_pull_request_url:
type: string
description: ''
default: ''
nullable: true
scan_type:
type: string
description: ''
default: ''
nullable: true
scan_state:
type: string
enum:
- pending
- precrawl
- resolve
- scan
description: The current processing status of the SBOM
default: pending
nullable: true
description: ''
description: The data from the full scan
'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}/full-scans/{full_scan_id}/files/tar:
get:
tags:
- full-scans
summary: Download full scan files as tarball
operationId: downloadOrgFullScanFilesAsTar
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: full_scan_id
in: path
required: true
description: The ID of the full scan
schema:
type: string
security:
- bearerAuth:
- full-scans:list
- basicAuth:
- full-scans:list
description: 'Download all files associated with a full scan in tar format.
This endpoint consumes 1 unit of your quota.
This endpoint requires the following org token scopes:
- full-scans:list'
responses:
'200':
content:
application/x-tar: {}
description: Tar archive of full scan files
'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}/full-scans/archive:
post:
tags:
- full-scans
summary: Create full scan from archive
operationId: Crea
# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-full-scans-api-openapi.yml