Overview
The ZeroPath REST API provides programmatic access to security scanning capabilities for your repositories. Manage organizations, repositories, scans, and security issues across multiple version control systems.Key Capabilities
Manage Organizations
Manage organization membership and roles
Repository Operations
Add repositories from GitHub, GitHub Enterprise Server, GitLab, Bitbucket, Azure DevOps Services, or any public URL, and
manage them
Security Scans
Trigger, cancel, and schedule scans on repositories and pull requests
On-Demand Code Scans
Submit diffs, files, and snippets for asynchronous security review
Issue Management
Search, investigate, and manage security issues found in your code
Code Inspection
Read and search source code directly in connected repositories
Teams & Permissions
Create teams, manage members, and configure granular permissions
AI Assistant
Manage the AI AppSec Assistant — conversations, schedules, event triggers,
and memory
Semantic Search
Search vulnerabilities and endpoints using natural language queries
Authentication
All API requests require authentication using API token headers:Required Headers
Example Request
Base URLs
All API endpoints are relative to: Production:https://zeropath.com:
ZEROPATH_ENVIRONMENT environment variable,
which accepts a full origin:
Core Resources
Organizations
Manage organizations, members, and settings. Key Operations:POST /api/v1/orgs/create- Create an organization with a name and domainPOST /api/v1/orgs/list- List available organizationsPOST /api/v1/orgs/delete- Delete an organizationPOST /api/v2/organizations/listMembers- List all members with roles and active status (requiresMEMBER_VIEW)POST /api/v2/organizations/inviteMember- Invite a user by email, optionally with a role (ADMIN, MEMBER; defaults to MEMBER)POST /api/v2/organizations/updateMemberRole- Update a member’s role (ADMIN, MEMBER)POST /api/v2/organizations/removeMember- Remove a member from the organization
Repositories
Add and manage repositories from various VCS providers. Key Operations:POST /api/v2/repositories/addByUrl- Add a public repository by its git URL (no VCS credentials needed)POST /api/v2/repositories/list- List repositories. When a repository’s most recent scan finished with an error, the response includes alastScanFailureobject with amessage(human-readable error), anoutcome(FAILEDorCANNOT_SCAN), and adetailsobject containing thescanIdof the failed scan, thebranchthat was targeted (nullable), and arecoveryhint (CONNECTIONto check VCS connectivity,BRANCHto verify the target branch exists, orNONEwhen no automated recovery suggestion applies).POST /api/v2/repositories/delete- Remove a repository from ZeroPath (does not delete from VCS provider)
- GitHub
- GitLab
- Bitbucket
- Azure DevOps Services
- Any publicly accessible git repository (via URL)
Scans
Initiate, monitor, and schedule security scans. Key Operations:POST /api/v2/scans/start- Start a full security scan on one or more repositories, with optional branch targeting. When ZeroPath is processing another start request for the same repository and branch, it returns HTTP409. Retry that request shortly.POST /api/v2/scans/cancel- Cancel a running or queued scanPOST /api/v2/scans/rescanPR- Trigger a rescan of a previously scanned pull request or merge requestPOST /api/v2/scans/list- List scans. SetgroupByPrto return only the newest scan per pull request and arelatedScanCountshowing how many scans were grouped. Each PR appears on one page.POST /api/v2/scans/get- Get scan details. Failed scans include anerrorMessage. WhenscaScan.inventoryRetiredAtis set, a newer scan superseded the dependency inventory and its graph edges are no longer available.POST /api/v2/scans/getSchedule- Get the automated scan schedule for a repositoryPOST /api/v2/scans/upsertSchedule- Create or update a recurring scan schedule (cron-based, with optional branch targeting viascanBranch)POST /api/v2/scans/deleteSchedule- Delete scan schedules. Pass an optionalscheduleIdto delete a specific schedule; otherwise all schedules for the specified repositories are removed.
Container Scanning
Scan container images for OS-package and bundled-dependency vulnerabilities, and optionally monitor them on a recurring schedule. Submit an image by its registry reference (e.g.ghcr.io/acme/api:1.4); if you don’t attach it to an existing
repository, an ephemeral standalone repository is created for it automatically.
Findings flow through the same triage, patch, and notification pipeline as every
other scan type. Each scan also detects the image’s base image and, when
possible, recommends a base-image upgrade that would remove the most
vulnerabilities, along with a per-layer breakdown.
Key Operations:
POST /api/v2/containerScans/submit- Submit a container image for scanning. Returns acontainerImageId; pollcontainerImages/geton it (itsqueuedflag andlatestScan) to follow progress.POST /api/v2/containerScans/get- Get a single container scan, including its ordered image layers and finding count.POST /api/v2/containerScans/list- List container scans (cursor-paginated), optionally filtered byrepositoryIdorcontainerImageId.POST /api/v2/containerImages/get- Get a tracked container image with its latest scan summary and queue state.POST /api/v2/containerImages/list- List tracked container images (cursor-paginated), each with its latest scan summary.POST /api/v2/containerImages/monitor- Enable recurring monitoring on an image by setting a cron schedule.POST /api/v2/containerImages/unmonitor- Disable recurring monitoring on an image.
Issues
Search and manage security issues found in scans. Key Operations:POST /api/v2/issues/search- Search for security issues. Thestatusesfilter defaults to["PENDING_REVIEW"], so pass every status you want to see explicitly.POST /api/v2/issues/get- Get issue details (includes structured preconditions and attack steps, CVSS v3 and v4 scores, and vulnerability impact assessment)POST /api/v2/issues/updateStatus- Update the status of one or more issues. JSON body:issueIdsandissueStatus, one ofPENDING_REVIEW,BACKLOG,REVIEWING,PATCHING,RESOLVED,NON_EXPLOITABLE,FALSE_POSITIVE,ACCEPTED_RISK, orINFORMATIONAL. WithACCEPTED_RISKyou can passacceptedRiskExpiresAt, a future ISO 8601 date-time. When that date passes, the issue returns toPENDING_REVIEWunless it was resolved or marked a false positive in the meantime. WhenissueIdsnames exactly one issue, you can passexpectedas{ "status": ..., "updatedAt": ... }, set to theissueStatusandupdatedAtyou last read fromissues/get. If the issue has changed since, the update is refused with409 ISSUE_MOVE_STALE.POST /api/v2/issues/requestInvestigation- Request on-demand investigations with larger AI models. JSON body:issueIds(non-empty string array; use a one-element array for a single issue), optionalcontext(up to 20,000 characters), optionalorganizationId. This is the only HTTP endpoint for starting investigations. There is no separate per-issue…/investigateREST route. A definitive verdict closes the issue and its linked ticket, so a personal API token needs permission to close findings (ISSUE_EDIT_CLOSE) on the repository of every requested issue it can see. Otherwise the whole request returns403with{ "error": "Re-investigation can close findings, so it needs permission to close findings." }and nothing is queued. Service tokens and organization admins’ tokens are not refused.POST /api/v2/issues/export- Export findings matching your filters with their linked ticket metadataPOST /api/v2/issues/vulnerabilityReport- Generate a Markdown report for one finding. Send oneissueIdand optionallyorganizationId. The JSON response containsissueId,fileName, andmarkdown. To download one Word document for up to 25 findings, use the dashboard export.- Not available via REST: Polling investigation status uses tRPC (
getInvestigationStatus) today — use the MCP server (issues.getInvestigationStatus) or the dashboard, not aGET …/investigationURL. The MCP toolissues.requestInvestigation(singleissueId) also maps to tRPC only; over HTTP you userequestInvestigationwithissueIdsas above.
vulnImpact— a human-readable description of the vulnerability’s potential impact (available on issue detail and export)scanTargetBranch— the branch that was scanned when the issue was detected (available on issue list items)score— the composite severity × confidence score (0–100), rounded to a whole number. Returnsnullfor findings that have no measured severity (unassessed findings). A score of0is a real “no impact” result and is distinct fromnull.cvssScoreDetailed— includes both CVSS v4 (cvssVector,severity) and CVSS v3 (cvssV3Vector,cvssV3Severity) scores with per-metric reasoningsecurityCompassCountermeasures— when the issue is linked to one or more SD Elements countermeasures, this array lists each linked countermeasure with its task ID, title, SD Elements URL, match method (NL_RULE_FKfor rule-based matches,LLMfor AI-assisted matches), whether it is the primary countermeasure (isPrimary), and the AI model’s matching rationale (rationale, when available). Empty array when no Security Compass mapping exists for the repository. See the Security Compass integration guide for details on how findings are matched to countermeasures
dependencyPathsSource— set on the SCA package object whenever dependency-path data is available, naming where it was read from:finding_generation(the finding’s own scan generation) orcurrent_generation(the finding’s own generation was retired, so the path comes from the current scan of the same branch,scaScanId, which still contains the same package).scaPackageIdis the package record whose dependency graph was read.isDirectDependencyistruewhen that same scan declares the package directly in the manifest; read directness from it rather than fromchainHash, which describes the finding’s own package record.dependencyPathsRetiredAt— ISO 8601 timestamp set instead ofdependencyPathsSourcewhen the finding’s scan generation was retired by a newer scan and no current scan of its branch still contains the package. When this field is present,dependencyPathsis omitted andtransitiveDependenciesis empty because the graph edges no longer exist; absence of paths in that case does not mean the package has no dependencies.
cvssAttackVectors— filter by CVSS 4.0 attack-vector metric values (e.g.NETWORK,ADJACENT,LOCAL,PHYSICAL).cvssAttackComplexities— filter by CVSS 4.0 attack-complexity metric values.cvssPrivilegesRequired— filter by CVSS 4.0 privileges-required metric values.cvssUserInteractions— filter by CVSS 4.0 user-interaction metric values.runtimeValidationSetupRequirements— filter by the runtime validation setup classification for a finding.createdInLastNDays: return only findings created within the last N days (integer, 1 to 36,500). When combined withcreatedAfter, the more restrictive bound applies.resolvedInLastNDays: return only findings resolved within the last N days (integer, 1 to 36,500). When combined withresolvedAfter, the more restrictive bound applies.scoreRange— thescoreRangeobject now supports optionalminExclusiveandmaxExclusiveboolean fields to request an open (exclusive) bound on either end of the score window.
SCA) and containers (CONTAINER). Pass detectionTypes when you want to limit the results to specific types.
Code Inspection
Read files and list directories directly in connected GitHub, GitHub Enterprise Server, GitLab, and Bitbucket Data Center repositories. Search is available for GitHub and GitLab. Bitbucket Data Center returns the commit SHA for file and directory reads, so you can reuse it to inspect related files at the same revision. Key Operations:POST /api/v2/code/search— Search for code within a repository. UsepathPrefixto narrow results to a specific directory.POST /api/v2/code/read— Read file contents with an optional line range.POST /api/v2/code/listFiles— List files and directories under a repository path, with cursor-based pagination.
CI/CD security
Read saved CI/CD monitoring results for repositories connected to GitHub or GitLab. Repository results require access to the full source repository. List requests return up to 20 entries per page. UsenextCursor to request the next page.
For a repository-specific request, send its ZeroPath
repositoryId. Include organizationId when you need to select the organization explicitly. The deprecated POST /api/v2/cicd/assess is an alias for reading saved repository results.
Supply Chain Intel
Where Supply Chain Intel is enabled and intelligence has loaded, use these read-only endpoints for npm and PyPI. Repository usage and exposure follow the caller’s repository access.On-Demand Code Scans Beta
Submit caller-provided diffs, files, or snippets for asynchronous security review. These scans are useful for CLIs, IDE integrations, pre-commit hooks, CI jobs, and custom tools that need fast feedback without starting a full repository scan. Key Operations:POST /api/v2/async-code-scans/submit- Submit a scan jobPOST /api/v2/async-code-scans/status- Poll job statusPOST /api/v2/async-code-scans/results- Fetch completed results
Schedules
Manage automated scanning schedules. Key Operations:POST /api/v2/scans/upsertSchedule- Create or update a scan schedule (usescanBranchto target a specific branch)POST /api/v2/scans/getSchedule- Get all schedules for a repository (returns an array of schedules, each with its ownscanBranchand cron expression)POST /api/v2/scans/deleteSchedule- Delete scan schedules (passscheduleIdto delete a single schedule, or omit it to delete all schedules for the specified repositories)
Rules
Create and manage custom security rules. Key Operations:POST /api/v2/rules/create- Create a custom rule for all repositories, selected repositories, or tagsPOST /api/v2/rules/list- List rules, including their scope and whether they were created manually or through Security CompassPOST /api/v2/rules/update- Update the fields you provide. SendallRepositories: trueorrepositoryIdsto change the repository scope.
Teams
Manage teams, memberships, and granular permissions. Key Operations:POST /api/v2/teams/list- List all teams in the organizationPOST /api/v2/teams/create- Create a new teamPOST /api/v2/teams/delete- Delete a teamPOST /api/v2/teams/getMembers- Get team members and external contributorsPOST /api/v2/teams/addMembers/removeMembers- Manage team membershipPOST /api/v2/teams/setPermissions/getPermissions- Configure organization, repository, and team permissions.getPermissionsalso returnsmemberActions: { add: boolean, remove: boolean }indicating whether the calling user can add or remove members on that team.POST /api/v2/teams/setDefault- Mark a team as the default for new users
setPermissions / getPermissions):
In addition to repositoryIds (explicit per-repository grants), setPermissions
accepts tagIds: string[]. Each granted tag gives the team every permission in
repoPerms on every repository that is a member of that tag, resolved live —
as repositories join or leave the tag (including automatically via GitHub custom
property sync), the team’s access follows without another API call.
tagIdsis full-replacement, exactly likerepositoryIds: the request describes the team’s complete desired state, and omittingtagIdsremoves all of the team’s tag grants. Read-modify-write clients must round-trip thetagIdsreturned bygetPermissions.- In selected mode (
universalRepoPermissions: false), includeREPO_VIEWinrepoPermsor team members will not see the granted repositories — the server writes the permission set verbatim (this matches the existingrepositoryIdsbehavior; only universal mode auto-addsREPO_VIEW). - Setting
universalRepoPermissions: trueclears all tag grants along with explicit repository grants.
getPermissions returns:
memberActions: { add: boolean, remove: boolean }— indicates whether the calling user has permission to add or remove members on this team, based on their team-level and organization-level permissions.tagIds: string[]— the team’s granted tags.repositoryIdsstays explicit-only: tag-derived repositories are represented bytagIdsand are never flattened intorepositoryIds.repoPerms— in selected mode, the union of permission actions across the team’s explicit and tag grants.repoAccess— an explicit mode discriminant, one of:{ mode: "universal", perms: RepositoryPermission[] }{ mode: "selected", perms: RepositoryPermission[], repositoryIds: string[], tagIds: string[] }
All Teams endpoints now use
organizationId instead of the previous orgId
parameter. The old orgId parameter is no longer accepted.Scanner Settings
Configure scanner behavior at the organization, tag, or repository level. A monorepo partition has its own repository settings. Key Operations:POST /api/v2/scannerSettings/get- Retrieve saved and effective settings for a scope. The response now includes ascanSchedulesarray containing all configured scan schedules (each with ascanBranchandexecutionCriteriaCrontab), in addition to the legacyscanSchedulefield which returns only the first schedule.POST /api/v2/scannerSettings/update- Update settings (PR scanning, scan modules, confidence threshold, auto-patching, file ignore patterns, etc.)POST /api/v2/scannerSettings/delete- Delete scope overrides, reverting to inherited defaults
scanSchedules array in the settings response lists all configured schedules. The previous scanSchedule field (singular) is still returned for backward compatibility but only reflects the first schedule.
Semantic Search
Search vulnerabilities and endpoints across your codebase using natural language queries. Results are ranked by semantic similarity to your query. Key Operations:POST /api/v2/vulnerabilities/search- Search for security vulnerabilities using a natural language query. Returns matching issues with title, description, severity, affected file, and a relevance score. JSON body:query(string, 1-1024 characters), optionallimit(1-50, default 10), optionalorganizationId.POST /api/v2/endpoints/search- Search for application endpoints and handlers using a natural language query. Returns matching endpoints with name, description, authentication/authorization details, HTTP path and methods, and a relevance score. JSON body:query(string, 1-1024 characters), optionallimit(1-50, default 10), optionalorganizationId.
AI Assistant
Configure the AI AppSec Assistant, manage recurring schedules and event triggers, and retrieve run results. These are V2 endpoints; use the V2 specification. See the Assistant automation workflow for complete requests. Key Operations:POST /api/v2/agent/getConfig- Read effective settings without changing configuration or returning webhook secretsPOST /api/v2/agent/updateConfig- Update assistant settings (enable/disable, Slack channel, max concurrent runs, global instructions)POST /api/v2/agent/getJob- Retrieve a run’s status, effective trust level, summary, and customer-visible messagesPOST /api/v2/agent/listCronSchedules- List all cron schedules (each schedule includes itscronExpression)POST /api/v2/agent/createCronSchedule- Create a recurring schedule with cron expression, prompt, and optional repo/tag scopingPOST /api/v2/agent/updateCronSchedule- Modify a schedulePOST /api/v2/agent/deleteCronSchedule- Remove a schedulePOST /api/v2/agent/triggerCronSchedule- Manually trigger a scheduled taskPOST /api/v2/agent/listEventTriggers- List configured event triggersPOST /api/v2/agent/upsertEventTrigger- Create or update an event triggerPOST /api/v2/agent/deleteEventTrigger- Remove an event triggerPOST /api/v2/agent/listTriggerHistory- List event-triggered runsPOST /api/v2/agent/getTriggerEvent- Retrieve an authorized run and its trigger metadata
Security Compass
Manage the SD Elements integration end-to-end via the public REST API. See the Security Compass integration guide for the full workflow and setup instructions. SD Elements credentials (base URL and API token) are managed only in the ZeroPath dashboard under Integrations → Security Compass (also reachable from Settings → Integrations). The API never accepts or returns them. Key Operations:POST /api/v2/securityCompass/getIntegration- Fetch the integration and all project mappings for an organization, including the integration’s defaulttaskStatusMappingand, on each mapping, its SD Elements project’staskStatusMapping(shared by every repository mapped to that project) plus theeffectiveTaskStatusMappingpushes use. Each mapping’slastPushStatscarriesissuesMapped,countermeasuresUpdated,statusChangesRequested,passCount,partialCount,failCount,notApplicableSkipped,updateFailures,mappingFailures,unmapped,linksPersisted,repositoriesCombined, andnotInProject(covered countermeasures no longer in the SD Elements project’s task list, which get no note); the counts describe the combined notes that push posted for every repository mapped to the SD Elements project. Returnsnullwhen no integration is configured yetPOST /api/v2/securityCompass/testConnection- Validate the dashboard-saved credentials against a specific SD Elements project; returns the number of risk-relevant countermeasures visible on itPOST /api/v2/securityCompass/listTaskStatuses- List the task statuses on the connected SD Elements instance, returned asstatuses(each withid,slug,name, and ameaningofDONE,TODO, orNA). Slugs with meaningDONEorTODOare the valid values for ataskStatusMapping. Fails with400when the SD Elements instance cannot be reached. Requires admin rolePOST /api/v2/securityCompass/addProjectMapping- Link an SD Elements project to a ZeroPath repository; automatically enqueues the initial rule sync and, when the integration is enabled, a push of the repository’s latest finished full scan that runs once the sync succeeds. Several repositories can be mapped to one SD Elements project; their results are combined into one verification note per countermeasure, which passes only when every repository is clean. Accepts an optionaltaskStatusMappingfor the SD Elements project (pass,partial,failslugs; omit to keep the project’s current mapping,nullto reset it to the integration default), validated the same way as inupdateProjectMapping. When the project already has repositories, one of them is re-pushed so the project’s notes include the new repository. Returns the new mapping withruleSync.state: "running". Requires admin rolePOST /api/v2/securityCompass/updateProjectMapping- Replace thetaskStatusMappingof a mapping’s SD Elements project (it applies to every repository mapped to that project), or passnullto make the project inherit the integration default. Every slug is checked against the live instance: an unknown slug, or one whose meaning isNA, is rejected with400, as is any mapping that names a status while the instance cannot be reached. The change applies to the next push; callpushLatestScanto apply it to the current scan. Requires admin rolePOST /api/v2/securityCompass/removeProjectMapping- Unlink a project mapping. Generated rules are deleted only when this was the last mapping targeting the repository; otherwise they are kept anddeletedRuleCountis0. When other repositories stay mapped to the SD Elements project, one of them is re-pushed so the project’s notes stop listing the removed repository; removing the project’s last mapping also removes its task status mapping. Requires admin rolePOST /api/v2/securityCompass/syncRules- Manually enqueue a countermeasure-to-rule sync for a mapping. Returns{ status: "enqueued" }immediately; pollgetIntegrationorgetMappingAuditfor the outcome. Requires admin rolePOST /api/v2/securityCompass/pushLatestScan- Enqueue a results push of the repository’s latest finished full scan for a mapping without running a new scan (for example after changing its task status mapping). Returns{ status: "enqueued", codeScanId }, or{ status: "no_scan" }when the repository has no finished full scan. Fails with409while a push of that scan is already running and412when the integration is disabled. A re-push of a scan that was pushed before runs again against the current mapping and the open findings. Requires admin rolePOST /api/v2/securityCompass/getMappingAudit- Retrieve the per-countermeasure coverage breakdown from the last successful sync: whether each SD Elements task is covered by built-in analysis (sast), an auto-generated natural-language rule (nl_rule), or not at all (unsupported), enriched with catalog metadata (SDLC phase, priority, risk rating) and linked issue countsPOST /api/v2/securityCompass/getLinkedIssues- List ZeroPath findings currently linked to a specific SD Elements countermeasure of a mapping, with match method and rationalePOST /api/v2/securityCompass/getSyncHistory- Retrieve recent Security Compass audit-log events for an organization, newest first:security_compass.rule_sync,push,push_requested,mapping_add,mapping_update,mapping_remove,upsert,delete, andtest_connection; configurable up to 100 events
Stats
Retrieve aggregate security statistics and metrics. Key Operations:POST /api/v2/stats/summary- Get issue counts by status and severity, plus scan activity, scoped to a scan, repository, or organization
Dashboard Profiles
Save layouts and filters, manage defaults, and share organization templates from the dashboard profile switcher. Use Stats to retrieve data for your own dashboards.Quick Start
1
Get API Credentials
In the ZeroPath dashboard, open Settings → API keys, click Create API Key, and copy
the Token ID and Token Secret. You create, list and delete API keys only from a
signed-in browser session. See API Tokens.
2
Find a Repository
List repositories in the organization that issued the key. Copy the
id of the repository you want to scan.3
Trigger a Scan
Replace
REPOSITORY_ID with the ID from the list. The response contains a scanId for each queued scan. Use POST /api/v2/scans/get with that ID to follow its status.When an endpoint accepts an optional
organizationId, you can omit it for a
personal or service key. If you pass it, use the organization that issued the key.The detailed API endpoints documentation below is automatically generated from
our OpenAPI specification.