This SDK supports Python 3.10 and newer.
The Socket.dev Python SDK provides a wrapper around the Socket.dev REST API to simplify making calls to the API from Python.
Socket API v0 - https://docs.socket.dev/reference/introduction-to-socket-api
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME", timeout=30)PARAMETERS:
- token (str) - The Socket API Key for your Organization. Each method needs the token to carry particular scopes; see API token scopes
- timeout (int) - The number of seconds to wait before failing the connection
- allow_unverified (bool) - Whether to skip SSL certificate verification (default: False). Set to True for testing with self-signed certificates.
- user_agent (str, optional) - Custom User-Agent string to use in API requests. If not provided, defaults to "SocketSDKPython/{version}"
Retrieve package information for one or more PURLs. Pass org_slug to use the
current org-scoped endpoint. Omitting org_slug keeps the legacy deprecated
endpoint for backwards compatibility.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
org_slug = "your-org-slug"
license = "true"
components = [
{
"purl": "pkg:pypi/pyonepassword@5.0.0"
},
{
"purl": "pkg:pypi/socketsecurity"
}
]
print(socket.purl.post(license, components, org_slug=org_slug))PARAMETERS:
- license (str) - The license parameter if enabled will show alerts and license information. If disabled will only show the basic package metadata and scores. Default is true
- components (array{dict}) - The components list of packages urls
- org_slug (str, optional) - Organization slug for the supported org-scoped PURL endpoint. If omitted, the SDK uses the deprecated legacy endpoint for backwards compatibility.
Export a Socket SBOM as a CycloneDX SBOM
Usage:
from socketdev import socketdev
from socketdev.export import ExportQueryParams
socket = socketdev(token="REPLACE_ME")
query_params = ExportQueryParams(
author="john_doe",
project_name="my-project"
)
print(socket.export.cdx_bom("org_slug", "sbom_id", query_params))PARAMETERS:
- org_slug (str) - The organization name
- id (str) - The ID of either a full scan or an SBOM report
- query_params (ExportQueryParams) - Optional query parameters for filtering:
- author (str) - Filter by author
- project_group (str) - Filter by project group
- project_name (str) - Filter by project name
- project_version (str) - Filter by project version
- project_id (str) - Filter by project ID
Export a Socket SBOM as an SPDX SBOM
Usage:
from socketdev import socketdev
from socketdev.export import ExportQueryParams
socket = socketdev(token="REPLACE_ME")
query_params = ExportQueryParams(
project_name="my-project",
project_version="1.0.0"
)
print(socket.export.spdx_bom("org_slug", "sbom_id", query_params))PARAMETERS:
- org_slug (str) - The organization name
- id (str) - The ID of either a full scan or an SBOM report
- query_params (ExportQueryParams) - Optional query parameters for filtering:
- author (str) - Filter by author
- project_group (str) - Filter by project group
- project_name (str) - Filter by project name
- project_version (str) - Filter by project version
- project_id (str) - Filter by project ID
Export a Socket SBOM as an OpenVEX SBOM
Usage:
from socketdev import socketdev
from socketdev.export import ExportQueryParams
socket = socketdev(token="REPLACE_ME")
query_params = ExportQueryParams(
project_name="my-project",
project_version="1.0.0"
)
print(socket.export.openvex_bom("org_slug", "sbom_id", query_params))PARAMETERS:
- org_slug (str) - The organization name
- id (str) - The ID of either a full scan or an SBOM report
- query_params (ExportQueryParams) - Optional query parameters for filtering:
- author (str) - Filter by author
- project_group (str) - Filter by project group
- project_name (str) - Filter by project name
- project_version (str) - Filter by project version
- project_id (str) - Filter by project ID
Retrieve the Fullscans information for an Organization with query parameters
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# Query parameters for filtering full scans
params = {
"repo": "my-repo",
"branch": "main",
"limit": 10,
"offset": 0
}
print(socket.fullscans.get("org_slug", params))PARAMETERS:
- org_slug (str) - The organization name
- params (dict) - Query parameters for filtering results (required)
Create a full scan from a set of package manifest files. Returns a full scan including all SBOM artifacts.
Usage:
from socketdev import socketdev
from socketdev.fullscans import FullScanParams
socket = socketdev(token="REPLACE_ME")
files = [
"/path/to/manifest/package.json"
]
params = FullScanParams(
org_slug="org_name",
repo="TestRepo",
workspace="my-workspace",
branch="main",
commit_message="Test Commit Message",
commit_hash="abc123def456",
pull_request=123,
committers=["committer1", "committer2"],
make_default_branch=False,
set_as_pending_head=False
)
print(socket.fullscans.post(files, params))PARAMETERS:
- files (list) - List of file paths of manifest files
- params (FullScanParams) - FullScanParams object containing scan configuration
| Parameter | Required | Description |
|---|---|---|
| org_slug | True | The string name in a git approved name for organization. |
| repo | True | The string name in a git approved name for repositories. |
| branch | False | The string name in a git approved name for branches. |
| committers | False | List of committer names (List[str]). |
| pull_request | False | The integer for the PR or MR number. |
| commit_message | False | The string for a commit message if there is one. |
| make_default_branch | False | Boolean to signal that this is the default branch. |
| commit_hash | False | Optional git commit hash |
| set_as_pending_head | False | Boolean to set as pending head |
| tmp | False | Boolean temporary flag |
| workspace | False | The workspace of the repository to associate the full-scan with. |
| integration_type | False | IntegrationType enum value (e.g., "api", "github") |
| integration_org_slug | False | Organization slug for integration |
| scan_type | False | ScanType enum value: "socket", "socket_tier1", or "socket_basics" |
Delete an existing full scan.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fullscans.delete("org_slug", "full_scan_id"))PARAMETERS:
- org_slug (str) - The organization name
- full_scan_id (str) - The ID of the full scan
fullscans.stream_diff(org_slug, before, after, use_types=True, include_license_details="true", **kwargs)
Stream a diff between two full scans. Returns a scan diff.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fullscans.stream_diff("org_slug", "before_scan_id", "after_scan_id"))
# With additional parameters
print(socket.fullscans.stream_diff(
"org_slug",
"before_scan_id",
"after_scan_id",
use_types=False,
include_license_details="false"
))PARAMETERS:
- org_slug (str) - The organization name
- before (str) - The base full scan ID
- after (str) - The comparison full scan ID
- use_types (bool) - Whether to return typed response objects (default: True)
- include_license_details (str) - Include license details ("true"/"false"). Can greatly increase response size. Defaults to "true".
- kwargs - Additional query parameters
Stream all SBOM artifacts for a full scan. If the scan is still being analyzed, the SDK polls
cached results until they are ready, backing off from 5 to 10 seconds between attempts, and
raises APITimeout if they are not ready within the polling budget. Transient failures
(HTTP 408/502/503/504, timeouts, dropped connections) are retried within the budget; other
errors raise immediately.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fullscans.stream("org_slug", "full_scan_id"))
# With typed response
print(socket.fullscans.stream("org_slug", "full_scan_id", use_types=True))
# Wait up to 10 minutes for analysis to finish
print(socket.fullscans.stream("org_slug", "full_scan_id", poll_timeout_seconds=600))PARAMETERS:
- org_slug (str) - The organization name
- full_scan_id (str) - The ID of the full scan
- use_types (bool) - Whether to return typed response objects (default: False)
- poll_timeout_seconds (float) - Keyword-only. Total time to wait for results (default: the SDK's configured
timeout) - poll_initial_interval_seconds (float) - Keyword-only. Wait before the first retry (default: 5.0)
- poll_max_interval_seconds (float) - Keyword-only. Longest wait between retries (default: 10.0)
Get metadata for a single full scan
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fullscans.metadata("org_slug", "full_scan_id"))
# With typed response
print(socket.fullscans.metadata("org_slug", "full_scan_id", use_types=True))PARAMETERS:
- org_slug (str) - The organization name
- full_scan_id (str) - The ID of the full scan
- use_types (bool) - Whether to return typed response objects (default: False)
Get GitHub Flavored Markdown diff between two full scans.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fullscans.gfm("org_slug", "before_scan_id", "after_scan_id"))PARAMETERS:
- org_slug (str) - The organization name
- before (str) - The base full scan ID
- after (str) - The comparison full scan ID
Finalize a tier 1 reachability scan by associating it with a full scan.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
success = socket.fullscans.finalize_tier1("full_scan_id", "tier1_reachability_scan_id")
print(f"Finalization successful: {success}")PARAMETERS:
- full_scan_id (str) - The ID of the full scan to associate with the tier 1 scan
- tier1_reachability_scan_id (str) - The tier 1 reachability scan ID from the facts file
Get Socket Basics configuration for an organization. Socket Basics is a CI/CD security scanning suite that includes SAST scanning, secret detection, container security, and dependency analysis.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# Basic usage - returns dictionary
config = socket.basics.get_config("org_slug")
print(f"Python SAST enabled: {config['pythonSastEnabled']}")
print(f"Secret scanning enabled: {config['secretScanningEnabled']}")
# Using typed response objects
from socketdev.basics import SocketBasicsConfig, SocketBasicsResponse
response = socket.basics.get_config("org_slug", use_types=True)
if response.success and response.config:
print(f"JavaScript SAST: {response.config.javascriptSastEnabled}")
print(f"Trivy scanning: {response.config.trivyImageEnabled}")PARAMETERS:
- org_slug (str) - The organization name
- use_types (bool) - Whether to return typed response objects (default: False)
Socket Basics Features:
- Python SAST - Static analysis for Python code
- Go SAST - Static analysis for Go code
- JavaScript SAST - Static analysis for JavaScript/TypeScript code
- Secret Scanning - Detection of hardcoded secrets and credentials
- Trivy Image Scanning - Vulnerability scanning for Docker images
- Trivy Dockerfile Scanning - Vulnerability scanning for Dockerfiles
- Socket SCA - Supply chain analysis for dependencies
- Socket Scanning - General dependency security scanning
- Additional Parameters - Custom configuration options
Retrieve the dependencies for the organization associated with the API Key
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.dependencies.get(10, 0))PARAMETERS:
- limit (int) - The maximum number of dependencies to return
- offset (int) - The index to start from for pulling the dependencies
Retrieve the dependencies for the organization associated with the API Key
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
file_names = [
"path/to/package.json"
]
params = {
"repository": "username/repo-name",
"branch": "dependency-branch"
}
print(socket.dependencies.post(file_names, params))PARAMETERS:
- files (list) - The file paths of the manifest files to import into the Dependency API.
- params (dict) - A dictionary of the repository and branch options for the API
Get a list of information about the tracked repositories
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.repos.get(sort="name", direction="asc", per_page=100, page=1))PARAMETERS:
- sort - The key to sort on from the repo properties. Defaults to created_at
- direction - Can be desc or asc. Defaults to desc
- per_page - Integer between 1 to 100. Defaults to 10
- page - Integer page number defaults to 1. If there are no more results it will be 0
Create a new Socket Repository
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(
socket.repos.post(
name="example",
description="Info about Repo",
homepage="http://homepage",
visibility='public',
archived=False,
default_branch='not-main'
)
)PARAMETERS:
- name(required) - The name of the Socket Repository
- description(optional) - String description of the repository
- homepage(optional) - URL of the homepage of the
- visibility(optional) - Can be public or private and defaults to private
- archived(optional) - Boolean on if the repository is archived. Defaults to False
- default_branch(optional) - String name of the default branch for the repository. Defaults to main
Get a list of information about the tracked repositories
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.repos.repo(org_slug="example", repo_name="example-repo"))Update an existing Socket Repository
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(
socket.repos.update(
org_slug="example-org",
repo_name="example",
name="new-name-example",
description="Info about Repo",
homepage="http://homepage",
visibility='public',
archived=False,
default_branch='not-main'
)
)- name(optional) - The name of the Socket Repository
- description(optional) - String description of the repository
- homepage(optional) - URL of the homepage of the
- visibility(optional) - Can be public or private and defaults to private
- archived(optional) - Boolean on if the repository is archived. Defaults to False
- default_branch(optional) - String name of the default branch for the repository. Defaults to main
Delete a Socket Repository
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.repos.delete(org_slug="example", repo_name="example-repo"))PARAMETERS:
- org_slug - Name of the Socket Org
- repo_name - The name of the Socket Repository to delete
Retrieve the Socket.dev org information
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.org.get())Retrieve the the current quota available for your API Key
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.quota.get())Retrieve the Socket Organization Settings
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.settings.get())Retrieve the supported types of manifest files for creating a report
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.report.supported())Retrieve the list of all reports for the organization
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.report.list(from_time=1726183485))PARAMETERS:
- from_time (int) - The Unix Timestamp in Seconds to limit the reports pulled
Delete the specified report
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.report.delete("report-id"))PARAMETERS:
- report_id (str) - The report ID of the report to delete
Retrieve the information for a Project Health Report
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.report.view("report_id"))PARAMETERS:
- report_id (str) - The report ID of the report to view
Create a new project health report with the provided files
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
files = [
"/path/to/manifest/package.json"
]
print(socket.report.create(files))PARAMETERS:
- files (list) - List of file paths of manifest files
Get a list of information about the tracked repositories
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.repositories.get())Retrieve the information for a SBOM Report
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.sbom.view("report_id"))Retrieve the Issues associated with a package and version.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.npm.issues("hardhat-gas-report", "1.1.25"))PARAMETERS:
- package (str) - The name of the NPM package.
- version (str) - The version of the NPM Package.
Retrieve the Issues associated with a package and version.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.npm.score("hardhat-gas-report", "1.1.25"))PARAMETERS:
- package (str) - The name of the NPM package.
- version (str) - The version of the NPM Package.
List all repository labels for the given organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.labels.list("org_slug"))PARAMETERS:
- org_slug (str) – The organization name
Create a new label in the organization.
Usage:
print(socket.labels.post("org_slug", "my-label"))PARAMETERS:
- org_slug (str) – The organization name
- label_name (str) – Name of the label to create
Retrieve a single label by its ID.
Usage:
print(socket.labels.get("org_slug", "label_id"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (str) – The label ID
Delete a label by ID.
Usage:
print(socket.labels.delete("org_slug", "label_id"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (str) – The label ID
Associate a label with a repository.
Usage:
print(socket.labels.associate("org_slug", 1234, "repo_id"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (int) – The label ID
- repo_id (str) – The repository ID
Disassociate a label from a repository.
Usage:
print(socket.labels.disassociate("org_slug", 1234, "repo_id"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (int) – The label ID
- repo_id (str) – The repository ID
Get a setting for a specific label.
Usage:
print(socket.labels.setting.get("org_slug", 1234, "severity"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (int) – The label ID
- setting_key (str) – The key of the setting
Update settings for a specific label.
Usage:
settings = {"severity": {"value": {"level": "high"}}}
print(socket.labels.setting.put("org_slug", 1234, settings))PARAMETERS:
- org_slug (str) – The organization name
- label_id (int) – The label ID
- settings (dict) – A dictionary of label settings
Delete a setting from a label.
Usage:
print(socket.labels.setting.delete("org_slug", 1234, "severity"))PARAMETERS:
- org_slug (str) – The organization name
- label_id (int) – The label ID
- setting_key (str) – The setting key to delete
List historical alerts for an organization.
Usage:
print(socket.historical.list("org_slug", {"repo": "example-repo"}))PARAMETERS:
- org_slug (str) – The organization name
- query_params (dict, optional) – Optional query parameters
Retrieve alert trend data across time.
Usage:
print(socket.historical.trend("org_slug", {"range": "30d"}))PARAMETERS:
- org_slug (str) – The organization name
- query_params (dict, optional) – Optional query parameters
Create a new snapshot of historical data.
Usage:
print(socket.historical.snapshots.create("org_slug"))PARAMETERS:
- org_slug (str) – The organization name
List all historical snapshots for an organization.
Usage:
print(socket.historical.snapshots.list("org_slug", {"repo": "example-repo"}))PARAMETERS:
- org_slug (str) – The organization name
- query_params (dict, optional) – Optional query parameters
List all diff scans for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.diffscans.list("org_slug", {"limit": 10, "offset": 0}))PARAMETERS:
- org_slug (str) – The organization name
- params (dict, optional) – Optional query parameters for filtering
Fetch a specific diff scan by ID.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.diffscans.get("org_slug", "diff_scan_id"))PARAMETERS:
- org_slug (str) – The organization name
- diff_scan_id (str) – The ID of the diff scan to retrieve
Create a diff scan from two full scan IDs.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
params = {
"before": "full_scan_id_1",
"after": "full_scan_id_2",
"description": "Compare two scans"
}
print(socket.diffscans.create_from_ids("org_slug", params))PARAMETERS:
- org_slug (str) – The organization name
- params (dict) – Parameters including before and after scan IDs
Create a diff scan from repository files.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
files = ["/path/to/package.json"]
params = {"branch": "main", "commit": "abc123"}
print(socket.diffscans.create_from_repo("org_slug", "repo_slug", files, params))PARAMETERS:
- org_slug (str) – The organization name
- repo_slug (str) – The repository name
- files (list) – List of file paths to scan
- params (dict, optional) – Optional parameters for the scan
Get GitHub Flavored Markdown comments for a diff scan.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.diffscans.gfm("org_slug", "diff_scan_id"))PARAMETERS:
- org_slug (str) – The organization name
- diff_scan_id (str) – The ID of the diff scan
Delete a specific diff scan.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.diffscans.delete("org_slug", "diff_scan_id"))PARAMETERS:
- org_slug (str) – The organization name
- diff_scan_id (str) – The ID of the diff scan to delete
Get threat feed items for an organization or globally.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# Get org-specific threat feed
print(socket.threatfeed.get("org_slug", per_page=50, sort="created_at"))
# Get global threat feed (deprecated)
print(socket.threatfeed.get())PARAMETERS:
- org_slug (str, optional) – The organization name (recommended for new implementations)
- kwargs – Query parameters like per_page, page_cursor, sort, etc.
Create a new API token for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
token_config = {
"name": "My API Token",
"permissions": ["read", "write"],
"expires_at": "2024-12-31T23:59:59Z"
}
print(socket.apitokens.create("org_slug", **token_config))PARAMETERS:
- org_slug (str) – The organization name
- kwargs – Token configuration parameters
Update an existing API token.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
update_params = {
"token_id": "token_123",
"name": "Updated Token Name",
"permissions": ["read"]
}
print(socket.apitokens.update("org_slug", **update_params))PARAMETERS:
- org_slug (str) – The organization name
- kwargs – Token update parameters
Get audit log entries for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.auditlog.get("org_slug", limit=100, cursor="abc123"))PARAMETERS:
- org_slug (str) – The organization name
- kwargs – Query parameters like limit, cursor, etc.
Get organization analytics (deprecated - use Historical module instead).
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# DEPRECATED: Use socket.historical.list() or socket.historical.trend() instead
print(socket.analytics.get_org("alerts", start_date="2024-01-01"))PARAMETERS:
- filter (str) – Analytics filter type
- kwargs – Additional query parameters
Get repository analytics (deprecated - use Historical module instead).
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# DEPRECATED: Use socket.historical.list() or socket.historical.trend() instead
print(socket.analytics.get_repo("repo_name", "alerts", start_date="2024-01-01"))PARAMETERS:
- name (str) – Repository name
- filter (str) – Analytics filter type
- kwargs – Additional query parameters
Get alert types metadata.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
# Get metadata for specific alert types
alert_list = ["supply_chain_risk", "license_risk"]
print(socket.alerttypes.get(alert_list, language="en-US"))
# Get all alert types metadata
print(socket.alerttypes.get())PARAMETERS:
- alert_types (list, optional) – List of alert type strings to get metadata for
- language (str) – Language for alert metadata (default: en-US)
- kwargs – Additional query parameters
Get list of triaged alerts for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
query_params = {"status": "triaged", "limit": 50}
print(socket.triage.list_alert_triage("org_slug", query_params))PARAMETERS:
- org_slug (str) – The organization name
- query_params (dict, optional) – Optional query parameters for filtering
Retrieve the OpenAPI specification for the Socket API.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.openapi.get())PARAMETERS:
None required.
List all webhooks for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.webhooks.list("org_slug"))
# With query parameters
print(socket.webhooks.list("org_slug", limit=10, offset=0))PARAMETERS:
- org_slug (str) - The organization slug
- query_params - Optional query parameters for filtering
Create a new webhook for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
webhook_config = {
"url": "https://example.com/webhook",
"events": ["alert.created", "scan.completed"]
}
print(socket.webhooks.create("org_slug", **webhook_config))PARAMETERS:
- org_slug (str) - The organization slug
- kwargs - Webhook configuration parameters
Get details for a specific webhook.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.webhooks.get("org_slug", "webhook_id"))PARAMETERS:
- org_slug (str) - The organization slug
- webhook_id (str) - The webhook ID
Update an existing webhook.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
updates = {
"url": "https://example.com/new-webhook",
"events": ["alert.created"]
}
print(socket.webhooks.update("org_slug", "webhook_id", **updates))PARAMETERS:
- org_slug (str) - The organization slug
- webhook_id (str) - The webhook ID
- kwargs - Webhook configuration parameters to update
Delete a webhook.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.webhooks.delete("org_slug", "webhook_id"))PARAMETERS:
- org_slug (str) - The organization slug
- webhook_id (str) - The webhook ID
Get telemetry configuration for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.telemetry.get_config("org_slug"))PARAMETERS:
- org_slug (str) - The organization slug
Update telemetry configuration for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
config = {
"enabled": True,
"sampling_rate": 0.5
}
print(socket.telemetry.update_config("org_slug", **config))PARAMETERS:
- org_slug (str) - The organization slug
- kwargs - Configuration parameters to update
Get alerts for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.alerts.get("org_slug"))
# With query parameters
print(socket.alerts.get("org_slug", severity="high", limit=50))PARAMETERS:
- org_slug (str) - The organization slug
- query_params - Optional query parameters for filtering
Get available fixes for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.fixes.get("org_slug"))
# With query parameters
print(socket.fixes.get("org_slug", ecosystem="npm"))PARAMETERS:
- org_slug (str) - The organization slug
- query_params - Optional query parameters for filtering
Get list of supported manifest file types for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.supportedfiles.get("org_slug"))PARAMETERS:
- org_slug (str) - The organization slug
Search alerts across full scans.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
search_params = {
"query": "CVE-2024-1234",
"limit": 20
}
print(socket.alertfullscansearch.search("org_slug", **search_params))PARAMETERS:
- org_slug (str) - The organization slug
- query_params - Optional query parameters for filtering
Get historical dependency trends data for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
query_params = {
"from": "2024-01-01",
"to": "2024-12-31"
}
print(socket.historical.dependencies_trend("org_slug", query_params))PARAMETERS:
- org_slug (str) - The organization slug
- query_params (dict, optional) - Optional query parameters for date filtering
Create a new snapshot for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.historical.snapshots.create("org_slug"))PARAMETERS:
- org_slug (str) - The organization slug
List historical snapshots for an organization.
Usage:
from socketdev import socketdev
socket = socketdev(token="REPLACE_ME")
print(socket.historical.snapshots.list("org_slug"))
# With query parameters
query_params = {"limit": 10, "offset": 0}
print(socket.historical.snapshots.list("org_slug", query_params))PARAMETERS:
- org_slug (str) - The organization slug
- query_params (dict, optional) - Optional query parameters for filtering
The SDK authenticates every call with one organization API token, and each Socket API
endpoint checks that the token carries particular scopes. The table below lists, for each
SDK method, the endpoint it calls and the scopes that endpoint checks. Where an endpoint
lists more than one scope, the token needs all of them. "none" means the endpoint checks
no scope, so any valid token for the organization works. Paths are relative to
https://api.socket.dev/v0/; query strings are omitted.
The scopes each endpoint checks are also listed in the API reference. For a least-privilege token, grant only the scopes of the methods your integration calls.
Scopes are grouped by their prefix, and a token that holds a group holds every scope in
it: full-scans covers full-scans:list, full-scans:create and
full-scans:delete. When a token is given every scope of a group, the API stores and
reports the group name instead, so a token created with packages:list, the only
scope in its group, is listed with packages.
Scopes are not the only check. A token restricted to specific repositories is rejected by some endpoints whatever scopes it holds, and organizations that restrict repository access apply per-repository checks on top of the scopes listed here.
Methods do not return an empty result on a 401 or 403. API.do_request() raises
before the method sees the response, so the exception reaches the caller, including when
use_types=True.
A missing scope raises APIAccessDenied with status_code 403. Its message starts
with the server's Insufficient permissions, followed by the request URL and the
response headers. A 401, from a bad or revoked token, also raises APIAccessDenied,
with Unauthorized in the message.
Recent API responses name the required scopes in the 403 body under
error.details.requiredScopes, but the SDK does not include them in the exception
message; to see them, look up the endpoint in the table below or the API reference.
A token restricted to specific repositories gets the same exception from an endpoint
that does not accept such tokens. Its message starts with This endpoint does not
support repository-scoped tokens.
A 403 whose message contains Insufficient max quota raises APIInsufficientQuota
instead, as does a 429, and logs the server's message at ERROR on the socketdev
logger.
socketdev.exceptions also defines APIInsufficientPermissions and
APIOrganizationNotAllowed. The SDK raises them for 403 messages containing
Insufficient permissions for API method and Organization not allowed, which the
API does not currently send. Do not rely on either to detect a missing scope: catch
APIAccessDenied.
All of these classes carry the HTTP status in status_code and subclass
APIFailure, so catching APIFailure covers every case.
from socketdev import socketdev
from socketdev.exceptions import APIAccessDenied
socket = socketdev(token="REPLACE_ME")
try:
socket.diffscans.list("org_slug")
except APIAccessDenied as error:
if error.status_code == 403:
print("Access denied; check the token's scopes for this method:", error)
raiseA few rows need a note:
- "Deprecated" marks an endpoint the API reference lists as deprecated. Prefer the
method the reference names as its successor.
report.view()callsGET report/view/{id}, which the reference says will be removed on 2026-11-20; usefullscansinstead. fullscans.finalize_tier1(),uploadmanifests.upload_manifest_files()andsbom.view()call endpoints the API reference does not list. Their scopes are given in the table.- Three calls request a path the API has no route for, so they fail with a 404
(
APIResourceNotFound) whatever the token:apitokens.update()whentoken_idis passed,dependencies.get()whenorg_slug,ecosystem,packageandversionare all passed, andrepositories.list(). Callapitokens.update()withouttoken_id, and userepos.get()to list repositories. dependencies.get()otherwise callsPOST dependencies/search. That endpoint accepts any valid token, but it returns only results from repositories the token can read underdependencies:list. Depending on how the organization restricts repository access, a token without that scope gets an empty result instead of a 403, so grantdependencies:list.- Some scopes differ from what the method name suggests:
analytics.get_org()andanalytics.get_repo()checkreport:write;apitokens.update()checksapi-tokens:create;labels.setting.delete()checksrepo-label:update; and theexportmethods checkreport:readrather than a full-scans scope.
| Method | Endpoint | Scopes |
|---|---|---|
alertfullscansearch.search() |
GET orgs/{org_slug}/alert-full-scan-search |
alerts:list |
alerts.get() |
GET orgs/{org_slug}/alerts |
alerts:list |
alerttypes.get() |
POST alert-types |
none |
analytics.get_org() |
GET analytics/org/{filter}. Deprecated |
report:write |
analytics.get_repo() |
GET analytics/repo/{name}/{filter}. Deprecated |
report:write |
apitokens.create() |
POST orgs/{org_slug}/api-tokens |
api-tokens:create |
apitokens.list() |
GET orgs/{org_slug}/api-tokens |
api-tokens:list |
apitokens.update() |
POST orgs/{org_slug}/api-tokens/update |
api-tokens:create |
apitokens.update(token_id=...) |
PUT orgs/{org_slug}/api-tokens/{token_id} |
no such route; the call fails |
apitokens.rotate() |
POST orgs/{org_slug}/api-tokens/rotate |
api-tokens:rotate |
apitokens.revoke() |
POST orgs/{org_slug}/api-tokens/revoke |
api-tokens:revoke |
auditlog.get() |
GET orgs/{org_slug}/audit-log |
audit-log:list |
basics.get_config() |
GET orgs/{org_slug}/settings/socket-basics |
socket-basics:read |
dependencies.post() |
POST dependencies/upload. Deprecated |
report:write |
dependencies.get() |
POST dependencies/search |
none; dependencies:list to get results (see the note above) |
dependencies.get(org_slug, ecosystem, package, version) |
GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version} |
no such route; the call fails |
diffscans.list() |
GET orgs/{org_slug}/diff-scans |
diff-scans:list |
diffscans.get() |
GET orgs/{org_slug}/diff-scans/{diff_scan_id} |
diff-scans:list |
diffscans.create_from_repo() |
POST orgs/{org_slug}/diff-scans/from-repo/{repo_slug} |
diff-scans:create, full-scans:create and repo:list |
diffscans.create_from_ids() |
POST orgs/{org_slug}/diff-scans/from-ids |
diff-scans:create and full-scans:list |
diffscans.gfm() |
GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm. Deprecated |
diff-scans:list |
diffscans.delete() |
DELETE orgs/{org_slug}/diff-scans/{diff_scan_id} |
diff-scans:delete |
export.cdx_bom() |
GET orgs/{org_slug}/export/cdx/{id} |
report:read |
export.spdx_bom() |
GET orgs/{org_slug}/export/spdx/{id} |
report:read |
export.openvex_bom() |
GET orgs/{org_slug}/export/openvex/{id} |
report:read |
fixes.get() |
GET orgs/{org_slug}/fixes. Deprecated |
fixes:list |
fullscans.get() |
GET orgs/{org_slug}/full-scans, or GET orgs/{org_slug}/full-scans/{full_scan_id} when params holds only id |
full-scans:list |
fullscans.post() |
POST orgs/{org_slug}/full-scans |
full-scans:create |
fullscans.delete() |
DELETE orgs/{org_slug}/full-scans/{full_scan_id} |
full-scans:delete |
fullscans.stream_diff() |
GET orgs/{org_slug}/full-scans/diff. Deprecated |
full-scans:list |
fullscans.stream() |
GET orgs/{org_slug}/full-scans/{full_scan_id} |
full-scans:list |
fullscans.metadata() |
GET orgs/{org_slug}/full-scans/{full_scan_id}/metadata |
full-scans:list |
fullscans.gfm() |
GET orgs/{org_slug}/full-scans/diff/gfm. Deprecated |
full-scans:list |
fullscans.finalize_tier1() |
POST tier1-reachability-scan/finalize |
full-scans:create (not in the API reference) |
fullscans.archive() |
POST orgs/{org_slug}/full-scans/archive |
full-scans:create |
fullscans.rescan() |
POST orgs/{org_slug}/full-scans/{full_scan_id}/rescan |
full-scans:create |
fullscans.get_tar_files() |
GET orgs/{org_slug}/full-scans/{full_scan_id}/files/tar |
full-scans:list |
historical.list() |
GET orgs/{org_slug}/historical/alerts |
historical:alerts-list |
historical.trend() |
GET orgs/{org_slug}/historical/alerts/trend |
historical:alerts-trend |
historical.dependencies_trend() |
GET orgs/{org_slug}/historical/dependencies/trend |
historical:dependencies-trend |
historical.snapshots.create() |
POST orgs/{org_slug}/historical/snapshots |
historical:snapshots-start |
historical.snapshots.list() |
GET orgs/{org_slug}/historical/snapshots |
historical:snapshots-list |
labels.list() |
GET orgs/{org_slug}/repos/labels |
repo-label:list |
labels.post() |
POST orgs/{org_slug}/repos/labels |
repo-label:create |
labels.get() |
GET orgs/{org_slug}/repos/labels/{label_id} |
repo-label:list |
labels.delete() |
DELETE orgs/{org_slug}/repos/labels/{label_id} |
repo-label:delete |
labels.associate() |
POST orgs/{org_slug}/repos/labels/{label_id}/associate |
repo-label:update |
labels.disassociate() |
POST orgs/{org_slug}/repos/labels/{label_id}/disassociate |
repo-label:update |
labels.setting.get() |
GET orgs/{org_slug}/repos/labels/{label_id}/label-setting |
repo-label:list |
labels.setting.put() |
PUT orgs/{org_slug}/repos/labels/{label_id}/label-setting |
repo-label:update |
labels.setting.delete() |
DELETE orgs/{org_slug}/repos/labels/{label_id}/label-setting |
repo-label:update |
licensemetadata.post() |
POST license-metadata |
none |
npm.issues() |
GET npm/{package}/{version}/issues. Deprecated |
none |
npm.score() |
GET npm/{package}/{version}/score. Deprecated |
none |
openapi.get() |
GET openapi |
none |
org.get() |
GET organizations |
none |
purl.post(org_slug=...) |
POST orgs/{org_slug}/purl |
packages:list |
purl.post() |
POST purl. Deprecated |
packages:list |
quota.get() |
GET quota |
none |
report.list() |
GET report/list. Deprecated |
report:list |
report.delete() |
DELETE report/delete/{id}. Deprecated |
report:write |
report.view() |
GET report/view/{id}. Deprecated |
report:read |
report.supported() |
GET report/supported. Deprecated |
none |
report.create() |
PUT report/upload. Deprecated |
report:write |
repos.get() |
GET orgs/{org_slug}/repos |
repo:list |
repos.repo() |
GET orgs/{org_slug}/repos/{repo_slug} |
repo:list |
repos.post() |
POST orgs/{org_slug}/repos |
repo:create |
repos.update() |
POST orgs/{org_slug}/repos/{repo_slug} |
repo:update |
repos.delete() |
DELETE orgs/{org_slug}/repos/{repo_slug} |
repo:delete |
repositories.list() |
GET repos |
no such route; the call fails |
sbom.view() |
GET sbom/view/{id} |
report:read (not in the API reference) |
settings.get() |
GET orgs/{org_slug}/settings/security-policy |
security-policy:read |
settings.update_security_policy() |
POST orgs/{org_slug}/settings/security-policy |
security-policy:update |
settings.get_license_policy() |
GET orgs/{org_slug}/settings/license-policy. Deprecated |
license-policy:read |
settings.update_license_policy() |
POST orgs/{org_slug}/settings/license-policy |
license-policy:update |
settings.integration_events() |
GET orgs/{org_slug}/settings/integrations/{integration_id}/events |
integration:list |
supportedfiles.get() |
GET orgs/{org_slug}/supported-files |
none |
telemetry.get_config() |
GET orgs/{org_slug}/telemetry/config |
none |
telemetry.update_config() |
PUT orgs/{org_slug}/telemetry/config |
telemetry-policy:update |
threatfeed.get(org_slug) |
GET orgs/{org_slug}/threat-feed |
threat-feed:list |
threatfeed.get() |
GET threat-feed. Deprecated |
threat-feed:list |
triage.list_alert_triage() |
GET orgs/{org_slug}/triage/alerts |
triage:alerts-list |
triage.update_alert_triage() |
POST orgs/{org_slug}/triage/alerts |
triage:alerts-update |
uploadmanifests.upload_manifest_files() |
POST orgs/{org_slug}/upload-manifest-files |
full-scans:create (not in the API reference) |
webhooks.list() |
GET orgs/{org_slug}/webhooks |
webhooks:list |
webhooks.create() |
POST orgs/{org_slug}/webhooks |
webhooks:create |
webhooks.get() |
GET orgs/{org_slug}/webhooks/{webhook_id} |
webhooks:list |
webhooks.update() |
PUT orgs/{org_slug}/webhooks/{webhook_id} |
webhooks:update |
webhooks.delete() |
DELETE orgs/{org_slug}/webhooks/{webhook_id} |
webhooks:delete |