# API reference

Base URL: `https://app.zerocool.ai/api`

Send `Authorization: Bearer <api-key>`. Use [API keys](/docs/api-keys) to create one.
New here? Start with [Get started](/docs/get-started).

[Download the customer OpenAPI specification](/docs/openapi.json) for request and response schemas.
Request bodies use `Content-Type: application/json`, except context-file uploads.
Upload a context file with `multipart/form-data` and one `file` field.
An API key's role ceiling and its creator's current access both apply.
The API calls an audit a **Job**. Use IDs returned by the API.

## Operations

### List accessible workspaces

`GET /workspaces`

Minimum role: **Viewer**.

Responses: `200`, `401`, `403`, `429`, `503`, `default`.

### Archive a workspace

`DELETE /workspaces/{workspace_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### List workspace members

`GET /workspaces/{workspace_id}/members`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Change a member's role

`PUT /workspaces/{workspace_id}/members/{account_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `account_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Remove a member

`DELETE /workspaces/{workspace_id}/members/{account_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `account_id` | path | Yes |

Responses: `204`, `401`, `403`, `404`, `429`, `503`, `default`.

### List workspace invitations

`GET /workspaces/{workspace_id}/invitations`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Invite a workspace member

`POST /workspaces/{workspace_id}/invitations`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Revoke an invitation

`DELETE /workspaces/{workspace_id}/invitations/{invitation_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `invitation_id` | path | Yes |

Responses: `204`, `401`, `403`, `404`, `429`, `503`, `default`.

### List funded workspaces

`GET /workspaces/{workspace_id}/funded-workspaces`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Create a funded workspace

`POST /workspaces/{workspace_id}/funded-workspaces`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Adjust a funded workspace's credits

`PUT /workspaces/{workspace_id}/funded-workspaces/{team_workspace_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `team_workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Read funding history

`GET /workspaces/{workspace_id}/funding-history`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Read workspace billing

`GET /workspaces/{workspace_id}/billing`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `after` | query | No |
| `limit` | query | No |

Responses: `200`, `401`, `403`, `404`, `422`, `429`, `503`, `default`.

### Upload a context file

`POST /workspaces/{workspace_id}/context-files`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `429`, `503`, `default`.

### List context files

`GET /workspaces/{workspace_id}/context-files`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `source_url` | query | No |

Responses: `200`, `401`, `403`, `404`, `422`, `429`, `503`, `default`.

### List pull request review settings

`GET /workspaces/{workspace_id}/github/pull-request-repositories`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Set pull request review settings

`PUT /workspaces/{workspace_id}/github/pull-request-repositories/{repository_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `repository_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Disable pull request reviews

`DELETE /workspaces/{workspace_id}/github/pull-request-repositories/{repository_id}`

Minimum role: **Admin**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `repository_id` | path | Yes |

Responses: `204`, `401`, `403`, `404`, `429`, `503`, `default`.

### Read a pull request review

`GET /workspaces/{workspace_id}/github/pull-request-reviews/{review_id}`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `review_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Start a pull request review audit

`POST /workspaces/{workspace_id}/github/pull-request-reviews/{review_id}/jobs`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |
| `review_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### List audits and their fork chains

`GET /jobs`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | query | No |
| `q` | query | No |
| `status` | query | No |
| `requester` | query | No |
| `created_after` | query | No |
| `created_before` | query | No |
| `favorited` | query | No |
| `after` | query | No |
| `limit` | query | No |

Responses: `200`, `401`, `403`, `422`, `429`, `503`, `default`.

### List audits shared with you

`GET /jobs/shared-with-me`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `after` | query | No |
| `limit` | query | No |

Responses: `200`, `401`, `403`, `422`, `429`, `503`, `default`.

### Quote an audit without starting it

`POST /workspaces/{workspace_id}/jobs/quote`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Start an audit or fork a completed audit

`POST /workspaces/{workspace_id}/jobs`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `workspace_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Read an audit with findings and comments

`GET /jobs/{job_id}`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Read a source or finding PoC file

`POST /jobs/{job_id}/source-file`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Create a public share link

`POST /jobs/{job_id}/public-shares`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### List public share links

`GET /jobs/{job_id}/public-shares`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Revoke a public share link

`DELETE /jobs/{job_id}/public-shares/{share_id}`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |
| `share_id` | path | Yes |

Responses: `204`, `401`, `403`, `404`, `429`, `503`, `default`.

### Share an audit with an Account

`POST /jobs/{job_id}/account-shares`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### List direct shares

`GET /jobs/{job_id}/account-shares`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Revoke a direct share

`DELETE /jobs/{job_id}/account-shares/{account_id}`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |
| `account_id` | path | Yes |

Responses: `204`, `401`, `403`, `404`, `429`, `503`, `default`.

### Request cancellation

`POST /jobs/{job_id}/cancellation`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Pause an audit

`POST /jobs/{job_id}/pause`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

### Resume an audit

`POST /jobs/{job_id}/resume`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Read the audit timeline

`GET /jobs/{job_id}/events`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |
| `after` | query | No |
| `limit` | query | No |

Responses: `200`, `401`, `403`, `404`, `422`, `429`, `503`, `default`.

### Read findings and comments

`GET /jobs/{job_id}/artifacts`

Minimum role: **Viewer**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `200`, `401`, `403`, `404`, `429`, `503`, `default`.

### Add a comment or response status

`POST /jobs/{job_id}/artifacts`

Minimum role: **Member**.

| Parameter | Location | Required |
| --- | --- | --- |
| `job_id` | path | Yes |

Responses: `201`, `401`, `403`, `404`, `415`, `422`, `429`, `503`, `default`.

## Request parameters

The `parameters` object describes the audit.

### Audit

| Field | Required | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `audit_mode` | Yes | light or deep | `—` | Audit mode. Default: Deep for full audits, Agile for reviews. |
| `credits` | No | integer or null | `null` | Credits to spend on the audit. Default: the suggested amount for the scope. More credits let the agents explore further. |
| `documents` | No | array of DocumentRequest | `[]` |  |
| `focus` | No | string or null | `null` | Audit priorities. |
| `job_type` | Yes | scan or fix_review or diff_review | `—` | Audit type. Reviews compare commits; fix reviews verify findings. |
| `name` | No | string | `—` | Audit name. |
| `poc_policy` | No | all or low or medium or high or skip | `"medium"` | Findings that get a proof-of-concept test: all, the given severity and higher, or none (skip). |
| `program_url` | No | string or null | `null` | Program or engagement URL. |
| `report_format` | No | zc or cantina or sherlock or hackenproof or yaudit or cyfrin | `"zc"` | Finding report format. |
| `targets` | Yes | array of TargetRequest | `—` |  |

### DocumentRequest

| Field | Required | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | Yes | string | `—` | What the preceding document contains and why it matters to the audit: one line, at most 240 characters. |
| `name` | Yes | string | `—` | Name of the uploaded context document. |
| `title` | Yes | string | `—` | Title of the preceding document: one line, at most 120 characters. |

### TargetRequest

| Field | Required | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `base_commit` | No | string or null | `null` | Base commit for a root review. Fork fix reviews derive their base. |
| `exclusions` | No | array of string | `[]` | Repository paths, directories or globs to exclude. |
| `scope` | Yes | array of string | `—` | Repository paths, directories or globs to include. |
| `source_commit` | Yes | string | `—` | Full hash of the pushed commit to audit. |
| `source_url` | Yes | string or null | `—` | Repository URL. |
| `target_id` | Yes | string | `—` | Stable identifier for this target within the audit. |

The audit name defaults to the target IDs. Without `credits`, an audit spends the suggested amount for its scope.

Use full commit hashes. A diff review needs a target `base_commit`.
A fork uses `parent_job_id`; the prior audit supplies fix-review bases.
The [CLI](/docs/reference/cli) prepares configuration and resolves scope through a quote.
Approve the quote before creating an audit. Creation reserves credits.

## Pagination and errors

For Job lists and billing, pass `next_cursor` as `after` until it is null.
For Events, pass `next_cursor` as `after` until `items` is empty.
An empty Events page can keep the same non-null `next_cursor`. Stop paging and keep that cursor.
Only when deliberately following a Job that is still running, poll later with `after=<cursor>`.
Errors use an `error` message in a JSON object.

| Status | Meaning |
| --- | --- |
| 401 | Missing or invalid credentials, including expired or revoked keys |
| 402 | Insufficient credits |
| 403 | Insufficient permission |
| 404 | Missing resource or resource outside your access |
| 409 | The current state prevents the operation |
| 422 | Invalid input |
| 429 | Rate limit reached; respect `Retry-After` |
| 503 | Service temporarily unavailable |

After an uncertain creation response, check the audit list before submitting again.