> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Integrate ZeroPath's security scanning into your applications and workflows
## 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
Create and manage organizations, members, and installations
Add repositories from GitHub, GitLab, Bitbucket, Azure DevOps Services, or any public URL, and
manage them
Trigger, cancel, and schedule scans on repositories and pull requests
Submit diffs, files, and snippets for asynchronous security review
Search, investigate, and manage security issues found in your code
Read and search source code directly in connected repositories
Create teams, manage members, and configure granular permissions
Manage the AI AppSec Assistant — conversations, schedules, event triggers,
and memory
Search vulnerabilities and endpoints using natural language queries
## Authentication
All API requests require authentication using API token headers:
### Required Headers
```bash theme={null}
X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID
X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET
Content-Type: application/json
```
### Example Request
```bash theme={null}
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](/mcp/overview) (`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
### Code Inspection
Read and search source code directly in connected GitHub 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](/developer-tools/async-code-scans) 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)
* `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](/platform/ai-assistant) 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
### 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
Generate API token credentials from your ZeroPath dashboard
```bash theme={null}
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"}'
```
```bash theme={null}
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"
}'
```
```bash theme={null}
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.