> ## 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

<CardGroup cols={2}>
  <Card title="Manage Organizations" icon="building">
    Create and manage organizations, members, and installations
  </Card>

  <Card title="Repository Operations" icon="git-branch">
    Add repositories from GitHub, GitLab, Bitbucket, or any public URL, and manage them
  </Card>

  <Card title="Security Scans" icon="shield-check">
    Trigger, cancel, and schedule scans on repositories and pull requests
  </Card>

  <Card title="Issue Management" icon="bug">
    Search, investigate, and manage security issues found in your code
  </Card>

  <Card title="Code Inspection" icon="file-code">
    Read and search source code directly in connected repositories
  </Card>

  <Card title="Teams & Permissions" icon="users">
    Create teams, manage members, and configure granular permissions
  </Card>

  <Card title="AI Assistant" icon="robot">
    Manage the AI AppSec Assistant — conversations, schedules, event triggers, and memory
  </Card>

  <Card title="Semantic Search" icon="magnifying-glass">
    Search vulnerabilities and endpoints using natural language queries
  </Card>
</CardGroup>

## 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
* `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
* 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.
* `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.

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

### 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

<Note>
  All Teams endpoints now use `organizationId` instead of the previous `orgId` parameter. The old `orgId` parameter is no longer accepted.
</Note>

### 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

<Steps>
  <Step title="Get API Credentials">
    Generate API token credentials from your ZeroPath dashboard
  </Step>

  <Step title="Create an Organization">
    ```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"}'
    ```
  </Step>

  <Step title="Add a Repository">
    ```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"
      }'
    ```
  </Step>

  <Step title="Trigger a Scan">
    ```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"
    ```
  </Step>
</Steps>

<Note>
  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.
</Note>

<Note>
  The detailed API endpoints documentation below is automatically generated from our OpenAPI specification.
</Note>