API Reference - ZeroPath Documentation

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

Create and manage organizations, members, and installations

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

X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID
X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET
Content-Type: application/json

Example Request

curl -X GET https://zeropath.com/organizations \
  -H "X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/json"

Base URLs

All API endpoints are relative to: Production:

https://zeropath.com

Development:

https://dev.branch.zeropath.com

Core Resources

Organizations

Manage organizations, members, and settings. Key Operations:

POST /organizations - Create a new organization
GET /organizations - List organizations
DELETE /organizations/{id} - Delete an organization
POST /api/v2/organizations/listMembers - List all members with roles and active status
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 /repositories - Add a repository
POST /api/v2/repositories/addByUrl - Add a public repository by its git URL (no VCS credentials needed)
GET /repositories - List repositories
POST /api/v2/repositories/delete - Remove a repository from ZeroPath (does not delete from VCS provider)
POST /repositories/{id}/scan - Trigger a repository scan

Supported Repository Types:

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
POST /api/v2/scans/cancel - Cancel a running or queued scan
POST /scans/rescanPR - Trigger a rescan of a previously scanned pull request or merge request
GET /scans - List scans
GET /scans/{id} - Get scan details (a scan may show an Indexing status when it is the first scan for a newly added repository). Failed scans include a descriptive errorMessage field with the specific reason for the failure.
GET /scans supports a groupByPr parameter that collapses PR scans by pull request, returning only the newest scan per PR with a relatedScanCount indicating how many rescans were folded in. Pagination is PR-aware, so each PR appears on exactly one page.
POST /api/v2/scans/getSchedule - Get the automated scan schedule for a repository
POST /api/v2/scans/upsertSchedule - Create or update a recurring scan schedule (cron-based, with optional branch targeting via scanBranch)
POST /api/v2/scans/deleteSchedule - Delete scan schedules. Pass an optional scheduleId to 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 a containerImageId; poll containerImages/get on it (its queued flag and latestScan) 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 by repositoryId or containerImageId.
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:

GET /issues/search - Search for security issues
GET /issues/{id} - Get issue details (includes structured preconditions and attack steps, CVSS v3 and v4 scores, and vulnerability impact assessment)
POST /issues/{id}/status - Update issue status
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), optional context (up to 20,000 characters), optional organizationId. This is the only HTTP endpoint for starting investigations. There is no separate per-issue …/investigate REST route.
POST /api/v2/issues/patchStatuses - Batch fetch patch generation and validation status for up to 100 issues at once. JSON body: issueIds (string array), organizationId.
Issue chat threads can be deleted via the API, removing the root question and all follow-up messages in the conversation.
Not available via REST: Polling investigation status uses tRPC (getInvestigationStatus) today — use the MCP server (issues.getInvestigationStatus) or the dashboard, not a GET …/investigation URL. The MCP tool issues.requestInvestigation (single issueId) also maps to tRPC only; over HTTP you use requestInvestigation with issueIds as above.

Issue Detail Fields:

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)
cvssScoreDetailed — includes both CVSS v4 (cvssVector, severity) and CVSS v3 (cvssV3Vector, cvssV3Severity) scores with per-metric reasoning
securityCompassCountermeasures — 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_FK for rule-based matches, LLM for 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

Code Inspection

Read and search source code directly in connected GitHub, GitHub Enterprise Server, and GitLab repositories. Key Operations:

GET /code/search - Search for code within a repository (supports pathPrefix to narrow results to a specific directory)
GET /code/read - Read file contents with optional line range
GET /code/listFiles - List files and directories in a repository path (supports cursor-based pagination)

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 job
POST /api/v2/async-code-scans/status - Poll job status
POST /api/v2/async-code-scans/results - Fetch completed results

On-Demand Code Scans can automatically use linked repository context when the submitted Git remote resolves to exactly one accessible ZeroPath repository. Otherwise, they can run standalone against only the submitted code.

On-Demand Code Scans are currently in beta. See the On-Demand Code Scans Beta guide for target modes, request examples, limits, and result behavior.

Schedules

Manage automated scanning schedules. Key Operations:

POST /api/v2/scans/upsertSchedule - Create or update a scan schedule (use scanBranch to target a specific branch)
POST /api/v2/scans/getSchedule - Get all schedules for a repository (returns an array of schedules, each with its own scanBranch and cron expression)
POST /api/v2/scans/deleteSchedule - Delete scan schedules (pass scheduleId to delete a single schedule, or omit it to delete all schedules for the specified repositories)

Scan schedules support branch-specific targeting: you can create multiple schedules for the same repository, each scanning a different branch on its own cron interval.

Rules

Create and manage custom security rules. Key Operations:

POST /rules - Create a custom rule (applies org-wide by default; optionally restrict to specific repos via repositoryIds)
GET /rules - List custom rules (each rule includes an allRepositories field indicating whether it applies to all repositories, and a source field — USER for manually created rules, SECURITY_COMPASS for rules auto-generated from SD Elements countermeasures)
PUT /rules/{id} - Update a rule (only provided fields are changed; pass allRepositories: true to apply org-wide, or repositoryIds to scope to specific repos — these are mutually exclusive)

Teams

Manage teams, memberships, and granular permissions. Key Operations:

POST /api/v2/teams/list - List all teams in the organization
POST /api/v2/teams/create - Create a new team
POST /api/v2/teams/delete - Delete a team
POST /api/v2/teams/getMembers - Get team members and external contributors
POST /api/v2/teams/addMembers / removeMembers - Manage team membership
POST /api/v2/teams/setPermissions / getPermissions - Configure organization, repository, and team permissions
POST /api/v2/teams/setDefault - Mark a team as the default for new users

Tag-based repository access (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.

tagIds is full-replacement, exactly like repositoryIds: the request describes the team’s complete desired state, and omitting tagIds removes all of the team’s tag grants. Read-modify-write clients must round-trip the tagIds returned by getPermissions.
In selected mode (universalRepoPermissions: false), include REPO_VIEW in repoPerms or team members will not see the granted repositories — the server writes the permission set verbatim (this matches the existing repositoryIds behavior; only universal mode auto-adds REPO_VIEW).
Setting universalRepoPermissions: true clears all tag grants along with explicit repository grants.

getPermissions returns:

tagIds: string[] — the team’s granted tags. repositoryIds stays explicit-only: tag-derived repositories are represented by tagIds and are never flattened into repositoryIds.
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[] }

repoAccess is response-only. The setPermissions input is strict: echoing the full getPermissions payload (including repoAccess) back into setPermissions is rejected. Construct write payloads from the flat fields (organizationPerms, repoPerms, teamPerms, repositoryIds, tagIds, universalRepoPermissions) only.

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, repository, or monorepo application level. Key Operations:

POST /api/v2/scannerSettings/get - Retrieve saved and effective settings for a scope. The response now includes a scanSchedules array containing all configured scan schedules (each with a scanBranch and executionCriteriaCrontab), in addition to the legacy scanSchedule field 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

You can now configure multiple scan schedules per repository, each targeting a different branch. The 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), optional limit (1-50, default 10), optional organizationId.
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), optional limit (1-50, default 10), optional organizationId.

AI Assistant

Manage the AI AppSec Assistant programmatically — create conversations, run jobs, configure schedules and event triggers, and manage the assistant’s memory. See the AI Assistant guide for full documentation. Key Operations:

POST /api/v2/agent/getConfig - Get the assistant’s configuration and event triggers
POST /api/v2/agent/updateConfig - Update assistant settings (enable/disable, Slack channel, max concurrent runs, global instructions)
POST /api/v2/agent/createConversation - Start a new conversation, optionally with an initial message that immediately creates a job
POST /api/v2/agent/listConversations - List conversations with pagination, search, and source filtering (manual, scheduled, event, Slack)
POST /api/v2/agent/getConversation - Get a conversation with all its jobs and messages
POST /api/v2/agent/sendMessage - Send a follow-up message in an existing conversation
POST /api/v2/agent/archiveConversation / unarchiveConversation - Archive or restore conversations
POST /api/v2/agent/listJobs - List jobs with optional status and trigger filters
POST /api/v2/agent/getJob - Get job details including messages
POST /api/v2/agent/cancelJob - Cancel a pending or running job
POST /api/v2/agent/listCronSchedules - List all cron schedules
POST /api/v2/agent/createCronSchedule - Create a recurring schedule with cron expression, prompt, and optional repo/tag scoping
POST /api/v2/agent/updateCronSchedule / deleteCronSchedule - Modify or remove schedules
POST /api/v2/agent/triggerCronSchedule - Manually trigger a scheduled task
POST /api/v2/agent/listEventTriggers - List configured event triggers
POST /api/v2/agent/upsertEventTrigger / deleteEventTrigger - Create, update, or remove event triggers
POST /api/v2/agent/listMemories - List the assistant’s stored memories
POST /api/v2/agent/updateMemory / deleteMemory / clearMemories - Manage memory entries

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 Settings → Integrations → Security Compass — the API never accepts or returns them. Key Operations:

POST /api/v2/securityCompass/getIntegration - Fetch the integration and all project mappings for an organization. Returns null when no integration is configured yet
POST /api/v2/securityCompass/testConnection - Validate the dashboard-saved credentials against a specific SD Elements project; returns the number of risk-relevant countermeasures visible on it
POST /api/v2/securityCompass/addProjectMapping - Link an SD Elements project to a ZeroPath repository; automatically enqueues the initial rule sync. Returns the new mapping with ruleSync.state: "running". Requires admin role
POST /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 and deletedRuleCount is 0. Requires admin role
POST /api/v2/securityCompass/syncRules - Manually enqueue a countermeasure-to-rule sync for a mapping. Returns { status: "enqueued" } immediately; poll getIntegration or getMappingAudit for the outcome. Requires admin role
POST /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 counts
POST /api/v2/securityCompass/getLinkedIssues - List ZeroPath findings currently linked to a specific SD Elements countermeasure of a mapping, with match method and rationale
POST /api/v2/securityCompass/getSyncHistory - Retrieve recent Security Compass audit-log events for an organization (rule syncs, findings pushes, mapping changes, connection tests), newest first; 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

Quick Start

Get API Credentials

Generate API token credentials from your ZeroPath dashboard

Create an Organization

curl -X POST https://zeropath.com/organizations \
  -H "X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Organization"}'

Add a Repository

curl -X POST https://zeropath.com/repositories \
  -H "X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "repository_type": "github",
    "repository_url": "https://github.com/owner/repo"
  }'

Trigger a Scan

curl -X POST https://zeropath.com/repositories/repo_123/scan \
  -H "X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/json"

Most V2 endpoints accept an optional organizationId parameter. When omitted, the organization is automatically resolved from your API token. You only need to pass organizationId explicitly if your token has access to multiple organizations and you want to target a specific one.

The detailed API endpoints documentation below is automatically generated from our OpenAPI specification.

​Overview

​Key Capabilities

Manage Organizations

Repository Operations

Security Scans

On-Demand Code Scans

Issue Management

Code Inspection

Teams & Permissions

AI Assistant

Semantic Search

​Authentication

​Required Headers

​Example Request

​Base URLs

​Core Resources

​Organizations

​Repositories

​Scans

​Container Scanning

​Issues

​Code Inspection

​On-Demand Code Scans Beta

​Schedules

​Rules

​Teams

​Scanner Settings

​Semantic Search

​AI Assistant

​Security Compass

​Stats

​Quick Start

Overview

Key Capabilities

Authentication

Required Headers

Example Request

Base URLs

Core Resources

Organizations

Repositories

Scans

Container Scanning

Issues

Code Inspection

On-Demand Code Scans Beta

Schedules

Rules

Teams

Scanner Settings

Semantic Search

AI Assistant

Security Compass

Stats

Quick Start