Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: Socket alerts API endpoints.
title: Socket Alerts API
version: '0'
servers:
- url: https://api.socket.dev/v0
tags:
- name: alerts
paths:
/orgs/{org_slug}/historical/alerts:
get:
tags:
- alerts
summary: List historical alerts (Beta)
operationId: historicalAlertsList
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: date
in: query
required: false
description: The UTC date in YYYY-MM-DD format for which to fetch alerts
schema:
type: string
default: CURRENT_DATE
- name: range
in: query
required: false
description: The number of days of data to fetch as an offset from input date (e.g. "-7d" or "7d") or use "latest" to query for latest alerts for each repo
schema:
type: string
default: -7d
- name: per_page
in: query
required: false
description: Specify the maximum number of results to return per page (intermediate pages may have fewer than this limit and callers should always check "endCursor" in response body to know if there are more pages)
schema:
type: integer
minimum: 1
maximum: 10000
default: 10000
- name: startAfterCursor
in: query
required: false
description: The pagination cursor that was returned as the "endCursor" property in previous request
schema:
type: string
default: ''
- name: filters.alertAction
in: query
required: false
description: Comma-separated list of alert actions ("error", "warn", "monitor", or "ignore) that should be included
schema:
type: string
- name: filters.alertAction.notIn
in: query
required: false
description: Comma-separated list of alert actions ("error", "warn", "monitor", or "ignore) that should be excluded
schema:
type: string
- name: filters.alertActionSourceType
in: query
required: false
description: Comma-separated list of alert action source types ("fallback", "injected-alert", "org-policy", "reachability", "repo-label-policy", "socket-yml", or "triage") that should be included
schema:
type: string
- name: filters.alertActionSourceType.notIn
in: query
required: false
description: Comma-separated list of alert action source types ("fallback", "injected-alert", "org-policy", "reachability", "repo-label-policy", "socket-yml", or "triage") that should be excluded
schema:
type: string
- name: filters.alertCategory
in: query
required: false
description: Comma-separated list of alert categories ("supplyChainRisk", "maintenance", "quality", "license", or "vulnerability") that should be included
schema:
type: string
- name: filters.alertCategory.notIn
in: query
required: false
description: Comma-separated list of alert categories ("supplyChainRisk", "maintenance", "quality", "license", or "vulnerability") that should be excluded
schema:
type: string
- name: filters.alertCveId
in: query
required: false
description: CVE ID
schema:
type: string
- name: filters.alertCveId.notIn
in: query
required: false
description: CVE ID
schema:
type: string
- name: filters.alertCveTitle
in: query
required: false
description: CVE title
schema:
type: string
- name: filters.alertCveTitle.notIn
in: query
required: false
description: CVE title
schema:
type: string
- name: filters.alertCweId
in: query
required: false
description: CWE ID
schema:
type: string
- name: filters.alertCweId.notIn
in: query
required: false
description: CWE ID
schema:
type: string
- name: filters.alertCweName
in: query
required: false
description: CWE name
schema:
type: string
- name: filters.alertCweName.notIn
in: query
required: false
description: CWE name
schema:
type: string
- name: filters.alertEPSS
in: query
required: false
description: Alert EPSS ("low", "medium", "high", "critical")
schema:
type: string
- name: filters.alertEPSS.notIn
in: query
required: false
description: Alert EPSS ("low", "medium", "high", "critical")
schema:
type: string
- name: filters.alertFixType
in: query
required: false
description: Comma-separated list of alert fix types ("upgrade", "cve", or "remove") that should be included
schema:
type: string
- name: filters.alertFixType.notIn
in: query
required: false
description: Comma-separated list of alert fix types ("upgrade", "cve", or "remove") that should be excluded
schema:
type: string
- name: filters.alertKEV
in: query
required: false
description: Alert KEV (Known Exploited Vulnerability) filter flag
schema:
type: boolean
default: false
- name: filters.alertKEV.notIn
in: query
required: false
description: Alert KEV (Known Exploited Vulnerability) filter flag
schema:
type: boolean
default: false
- name: filters.alertPriority
in: query
required: false
description: Alert priority ("low", "medium", "high", or "critical")
schema:
type: string
- name: filters.alertPriority.notIn
in: query
required: false
description: Alert priority ("low", "medium", "high", or "critical")
schema:
type: string
- name: filters.alertReachabilityAnalysisType
in: query
required: false
description: Comma-separated list of alert CVE reachability analysis types ("full-scan" or "precomputed") that should be included
schema:
type: string
- name: filters.alertReachabilityAnalysisType.notIn
in: query
required: false
description: Comma-separated list of alert CVE reachability analysis types ("full-scan" or "precomputed") that should be excluded
schema:
type: string
- name: filters.alertReachabilityType
in: query
required: false
description: Comma-separated list of alert CVE reachability types ("direct_dependency", "error", "maybe_reachable", "missing_support", "pending", "reachable", "undeterminable_reachability", "unknown", or "unreachable") that should be included
schema:
type: string
- name: filters.alertReachabilityType.notIn
in: query
required: false
description: Comma-separated list of alert CVE reachability types ("direct_dependency", "error", "maybe_reachable", "missing_support", "pending", "reachable", "undeterminable_reachability", "unknown", or "unreachable") that should be excluded
schema:
type: string
- name: filters.alertSeverity
in: query
required: false
description: Comma-separated list of alert severities ("low", "medium", "high", or "critical") that should be included
schema:
type: string
- name: filters.alertSeverity.notIn
in: query
required: false
description: Comma-separated list of alert severities ("low", "medium", "high", or "critical") that should be excluded
schema:
type: string
- name: filters.alertType
in: query
required: false
description: Comma-separated list of alert types (e.g. "usesEval", "unmaintained", etc.) that should be included
schema:
type: string
- name: filters.alertType.notIn
in: query
required: false
description: Comma-separated list of alert types (e.g. "usesEval", "unmaintained", etc.) that should be excluded
schema:
type: string
- name: filters.artifactName
in: query
required: false
description: Name of artifact
schema:
type: string
- name: filters.artifactName.notIn
in: query
required: false
description: Name of artifact
schema:
type: string
- name: filters.artifactType
in: query
required: false
description: Comma-separated list of artifact types (e.g. "npm", "pypi", "gem", "maven", "golang", etc.) that should be included
schema:
type: string
- name: filters.artifactType.notIn
in: query
required: false
description: Comma-separated list of artifact types (e.g. "npm", "pypi", "gem", "maven", "golang", etc.) that should be excluded
schema:
type: string
- name: filters.branch
in: query
required: false
description: Comma-separated list of branch names that should be included
schema:
type: string
- name: filters.branch.notIn
in: query
required: false
description: Comma-separated list of branch names that should be excluded
schema:
type: string
- name: filters.cvePatchStatus
in: query
required: false
description: Comma-separated list of patch statuses ("patch_unavailable", "patch_available", or "patch_applied") that should be included
schema:
type: string
- name: filters.cvePatchStatus.notIn
in: query
required: false
description: Comma-separated list of patch statuses ("patch_unavailable", "patch_available", or "patch_applied") that should be excluded
schema:
type: string
- name: filters.dependencyDead
in: query
required: false
description: Dead/reachable dependency filter flag
schema:
type: boolean
default: false
- name: filters.dependencyDead.notIn
in: query
required: false
description: Dead/reachable dependency filter flag
schema:
type: boolean
default: false
- name: filters.dependencyDev
in: query
required: false
description: Development/production dependency filter flag
schema:
type: boolean
default: false
- name: filters.dependencyDev.notIn
in: query
required: false
description: Development/production dependency filter flag
schema:
type: boolean
default: false
- name: filters.dependencyDirect
in: query
required: false
description: Direct/transitive dependency filter flag
schema:
type: boolean
default: false
- name: filters.dependencyDirect.notIn
in: query
required: false
description: Direct/transitive dependency filter flag
schema:
type: boolean
default: false
- name: filters.repoFullName
in: query
required: false
description: Comma-separated list of repo full names that should be included
schema:
type: string
- name: filters.repoFullName.notIn
in: query
required: false
description: Comma-separated list of repo full names that should be excluded
schema:
type: string
- name: filters.repoLabels
in: query
required: false
description: Comma-separated list of repo labels that should be included. Use "" to filter for repositories with no labels.
schema:
type: string
- name: filters.repoLabels.notIn
in: query
required: false
description: Comma-separated list of repo labels that should be excluded. Use "" to filter for repositories with no labels.
schema:
type: string
- name: filters.repoSlug
in: query
required: false
description: Comma-separated list of repo slugs that should be included
schema:
type: string
- name: filters.repoSlug.notIn
in: query
required: false
description: Comma-separated list of repo slugs that should be excluded
schema:
type: string
security:
- bearerAuth:
- historical:alerts-list
- basicAuth:
- historical:alerts-list
description: 'List historical alerts.
This endpoint consumes 10 units of your quota.
This endpoint requires the following org token scopes:
- historical:alerts-list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
endCursor:
type:
- string
- 'null'
description: ''
default: ''
items:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
repoFullName:
type: string
description: ''
default: ''
repoId:
type:
- string
- 'null'
description: ''
default: ''
repoSlug:
type: string
description: ''
default: ''
repoLabels:
type: array
items:
type: string
description: ''
default: ''
description: ''
repoLabelIds:
type: array
items:
type: string
description: ''
default: ''
description: ''
branch:
type: string
description: ''
default: ''
defaultBranch:
type: boolean
default: false
description: ''
fullScanId:
type: string
description: ''
default: ''
scannedAt:
type: string
description: ''
default: ''
artifact:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
description: ''
default: ''
license:
type:
- string
- 'null'
description: ''
default: ''
name:
type: string
description: ''
default: ''
namespace:
type:
- string
- 'null'
description: ''
default: ''
type:
type: string
description: ''
default: ''
version:
type: string
description: ''
default: ''
artifact_id:
type: string
description: ''
default: ''
artifactId:
type: string
description: ''
default: ''
author:
type: string
description: ''
default: ''
capabilities:
$ref: '#/components/schemas/Capabilities'
qualifiers:
$ref: '#/components/schemas/Qualifiers'
scores:
$ref: '#/components/schemas/SocketScore'
size:
type: integer
description: ''
default: 0
subpath:
type: string
description: ''
default: ''
required:
- id
- license
- name
- namespace
- type
- version
alert:
type: object
additionalProperties: false
properties:
key:
type: string
description: ''
default: ''
type:
type: string
description: ''
default: ''
severity:
type: integer
description: ''
default: 0
severityName:
type: string
description: ''
default: ''
action:
type: string
description: ''
default: ''
category:
type: string
description: ''
default: ''
file:
type:
- string
- 'null'
description: ''
default: ''
props:
type:
- object
- 'null'
description: ''
default: null
start:
type:
- integer
- 'null'
description: ''
default: 0
end:
type:
- integer
- 'null'
description: ''
default: 0
fix:
type:
- object
- 'null'
additionalProperties: false
description: ''
properties:
type:
type: string
description: ''
default: ''
description:
type: string
description: ''
default: ''
required:
- description
- type
required:
- action
- category
- key
- severity
- severityName
- type
dependency:
type: object
additionalProperties: false
properties:
direct:
type: boolean
default: false
description: ''
dev:
type: boolean
default: false
description: ''
dead:
type: boolean
default: false
description: ''
manifestFiles:
type: array
items:
$ref: '#/components/schemas/SocketManifestReference'
description: ''
topLevelAncestors:
type: array
items:
$ref: '#/components/schemas/SocketId'
description: ''
dependencies:
type: array
items:
$ref: '#/components/schemas/SocketId'
description: ''
required:
- dead
- dev
- direct
required:
- alert
- artifact
- branch
- defaultBranch
- dependency
- fullScanId
- repoFullName
- repoId
- repoLabelIds
- repoLabels
- repoSlug
- scannedAt
description: ''
meta:
type: object
additionalProperties: false
description: ''
properties:
organizationId:
type: string
description: ''
default: ''
queryStartTimestamp:
type: number
description: ''
default: 0
startDateInclusive:
type: string
description: ''
default: ''
endDateInclusive:
type: string
description: ''
default: ''
includeLatestAlertsOnly:
type: boolean
default: false
description: ''
filters:
type: object
additionalProperties: false
properties:
alertAction:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert actions ("error", "warn", "monitor", or "ignore) that should be included
alertAction.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert actions ("error", "warn", "monitor", or "ignore) that should be excluded
alertActionSourceType:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert action source types ("fallback", "injected-alert", "org-policy", "reachability", "repo-label-policy", "socket-yml", or "triage") that should be included
alertActionSourceType.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert action source types ("fallback", "injected-alert", "org-policy", "reachability", "repo-label-policy", "socket-yml", or "triage") that should be excluded
alertCategory:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert categories ("supplyChainRisk", "maintenance", "quality", "license", or "vulnerability") that should be included
alertCategory.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert categories ("supplyChainRisk", "maintenance", "quality", "license", or "vulnerability") that should be excluded
alertCveId:
type: array
items:
type: string
description: ''
default: ''
description: CVE ID
alertCveId.notIn:
type: array
items:
type: string
description: ''
default: ''
description: CVE ID
alertCveTitle:
type: array
items:
type: string
description: ''
default: ''
description: CVE title
alertCveTitle.notIn:
type: array
items:
type: string
description: ''
default: ''
description: CVE title
alertCweId:
type: array
items:
type: string
description: ''
default: ''
description: CWE ID
alertCweId.notIn:
type: array
items:
type: string
description: ''
default: ''
description: CWE ID
alertCweName:
type: array
items:
type: string
description: ''
default: ''
description: CWE name
alertCweName.notIn:
type: array
items:
type: string
description: ''
default: ''
description: CWE name
alertEPSS:
type: array
items:
type: string
description: ''
default: ''
description: Alert EPSS ("low", "medium", "high", "critical")
alertEPSS.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Alert EPSS ("low", "medium", "high", "critical")
alertFixType:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert fix types ("upgrade", "cve", or "remove") that should be included
alertFixType.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert fix types ("upgrade", "cve", or "remove") that should be excluded
alertKEV:
type: array
items:
type: boolean
default: false
description: ''
description: Alert KEV (Known Exploited Vulnerability) filter flag
alertPriority:
type: array
items:
type: string
description: ''
default: ''
description: Alert priority ("low", "medium", "high", or "critical")
alertPriority.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Alert priority ("low", "medium", "high", or "critical")
alertReachabilityAnalysisType:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of alert CVE reachability analysis types ("full-scan" or "precomputed") that should be included
alertReachabilityAnalysisType.notIn:
type: array
items:
type: string
description: ''
default: ''
description: Comma-separated list of al
# --- truncated at 32 KB (152 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-dev-alerts-api-openapi.yml