API Reference

​

Overview

​

Key Capabilities

​

Authentication

​

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

https://zeropath.com

https://dev.branch.zeropath.com

https://<your-deployment>.zeropath.com

export ZEROPATH_ENVIRONMENT=https://<your-deployment>.zeropath.com

​

Core Resources

​

Organizations

• 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 (requires MEMBER_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

• 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. When a repository’s most recent scan finished with an error, the response includes a lastScanFailure object with a message (human-readable error), an outcome (FAILED or CANNOT_SCAN), and a details object containing the scanId of the failed scan, the branch that was targeted (nullable), and a recovery hint (CONNECTION to check VCS connectivity, BRANCH to verify the target branch exists, or NONE when no automated recovery suggestion applies).
• POST /api/v2/repositories/delete - Remove a repository from ZeroPath (does not delete from VCS provider)
• POST /repositories/{id}/scan - Trigger a repository scan

• GitHub
• GitLab
• Bitbucket
• Azure DevOps Services
• Any publicly accessible git repository (via URL)

​

Scans

• 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. Scan list items include a scaScan.inventoryRetiredAt field (ISO 8601 timestamp or null) that is set once the dependency inventory from this scan has been superseded by a newer scan. A non-null value means the dependency graph edges for this scan are no longer present; null means the inventory is current.
• 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

• 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

• POST /api/v2/issues/search - Search for security issues. The statuses filter 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: issueIds and issueStatus, one of PENDING_REVIEW, BACKLOG, REVIEWING, PATCHING, RESOLVED, NON_EXPLOITABLE, FALSE_POSITIVE, ACCEPTED_RISK, or INFORMATIONAL. With ACCEPTED_RISK you can pass acceptedRiskExpiresAt, a future ISO 8601 date-time. When that date passes, the issue returns to PENDING_REVIEW unless it was resolved or marked a false positive in the meantime. When issueIds names exactly one issue, you can pass expected as { "status": ..., "updatedAt": ... }, set to the issueStatus and updatedAt you last read from issues/get. If the issue has changed since, the update is refused with 409 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), 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. 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 returns 403 with { "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/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.

• 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. Returns null for findings that have no measured severity (unassessed findings). A score of 0 is a real “no impact” result and is distinct from null.
• 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

• 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) or current_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). scaPackageId is the package record whose dependency graph was read. isDirectDependency is true when that same scan declares the package directly in the manifest; read directness from it rather than from chainHash, which describes the finding’s own package record.
• dependencyPathsRetiredAt — ISO 8601 timestamp set instead of dependencyPathsSource when 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, dependencyPaths is omitted and transitiveDependencies is 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 with createdAfter, the more restrictive bound applies.
• resolvedInLastNDays: return only findings resolved within the last N days (integer, 1 to 36,500). When combined with resolvedAfter, the more restrictive bound applies.
• scoreRange — the scoreRange object now supports optional minExclusive and maxExclusive boolean fields to request an open (exclusive) bound on either end of the score window.

​

Code Inspection

• 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

• 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

​

Schedules

• 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)

​

Rules

• 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

• 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. getPermissions also returns memberActions: { 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

• 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.

• 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. 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[] }

​

Scanner Settings

• 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

​

Semantic Search

• 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

• POST /api/v2/agent/getConfig - Read effective settings without changing configuration or returning webhook secrets
• POST /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 messages
• POST /api/v2/agent/listCronSchedules - List all cron schedules (each schedule includes its cronExpression)
• POST /api/v2/agent/createCronSchedule - Create a recurring schedule with cron expression, prompt, and optional repo/tag scoping
• POST /api/v2/agent/updateCronSchedule - Modify a schedule
• POST /api/v2/agent/deleteCronSchedule - Remove a schedule
• POST /api/v2/agent/triggerCronSchedule - Manually trigger a scheduled task
• POST /api/v2/agent/listEventTriggers - List configured event triggers
• POST /api/v2/agent/upsertEventTrigger - Create or update an event trigger
• POST /api/v2/agent/deleteEventTrigger - Remove an event trigger
• POST /api/v2/agent/listTriggerHistory - List event-triggered runs
• POST /api/v2/agent/getTriggerEvent - Retrieve an authorized run and its trigger metadata

​

Security Compass

• POST /api/v2/securityCompass/getIntegration - Fetch the integration and all project mappings for an organization, including the integration’s default taskStatusMapping and each mapping’s own taskStatusMapping plus the effectiveTaskStatusMapping pushes use. Each mapping’s lastPushStats carries issuesMapped, countermeasuresUpdated, statusChangesRequested, passCount, partialCount, failCount, notApplicableSkipped, updateFailures, mappingFailures, unmapped, and linksPersisted. 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/listTaskStatuses - List the task statuses on the connected SD Elements instance, returned as statuses (each with id, slug, name, and a meaning of DONE, TODO, or NA). Slugs with meaning DONE or TODO are the valid values for a taskStatusMapping. Fails with 400 when the SD Elements instance cannot be reached. Requires admin role
• POST /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. Accepts an optional taskStatusMapping (pass, partial, fail slugs; omit or null to inherit the integration default), validated the same way as in updateProjectMapping. Returns the new mapping with ruleSync.state: "running". Requires admin role
• POST /api/v2/securityCompass/updateProjectMapping - Replace a mapping’s taskStatusMapping, or pass null to make it inherit the integration default. Every slug is checked against the live instance: an unknown slug, or one whose meaning is NA, is rejected with 400, as is any mapping that names a status while the instance cannot be reached. The change applies to the next push; call pushLatestScan to apply it to the current scan. 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/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 with 409 while a push of that scan is already running and 412 when 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 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, newest first: security_compass.rule_sync, push, push_requested, mapping_add, mapping_update, mapping_remove, upsert, delete, and test_connection; configurable up to 100 events

​

Stats

• POST /api/v2/stats/summary - Get issue counts by status and severity, plus scan activity, scoped to a scan, repository, or organization

​

Dashboard Profiles

• Personal profiles: any member can create, edit, and delete their own.
• Org templates: any member can list and open them. Creating, editing, deleting, or converting a profile to a template requires the DASHBOARD_TEMPLATE_MANAGE permission (held by admins by default).
• Service tokens (API credentials without a user) cannot own profiles and are rejected by all dashboard-profile endpoints.

• POST /api/v2/dashboardProfiles/list - List all profiles the caller may open (their own personal profiles and all org templates), along with the caller’s current defaultProfileId.
• POST /api/v2/dashboardProfiles/create - Save a new profile. Pass visibility: "personal" or visibility: "org". A member’s first personal profile automatically becomes their default.
• POST /api/v2/dashboardProfiles/update - Rename, re-share, or update the filters and layout of an existing profile. Only the fields provided in the request body are changed.
• POST /api/v2/dashboardProfiles/delete - Delete a profile. Members who had it as their default fall back to no default; the dashboard selects the next available profile.
• POST /api/v2/dashboardProfiles/setDefault - Set a profile as the caller’s default (the one the dashboard opens automatically). Only a member of the organization can set a default.
• POST /api/v2/dashboardProfiles/duplicate - Create a personal copy of any visible profile. Accepts an optional name for the copy; defaults to "<source name> (copy)". The copy is always personal, regardless of the source’s visibility.

• id — unique identifier.
• name — display name.
• visibility — "personal" or "org".
• createdBy — { id, name } of the user who created the profile, or null when the creator’s account no longer exists.
• updatedAt — ISO 8601 timestamp of the last modification.
• filters — the page filter state saved with this profile.
• items — the widget layout saved with this profile.

​

Quick Start

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"}'

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"
  }'

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"