Issues API - Vidoc

Before you run these examples, select your deployment API address. Set VIDOC_API_URL without a trailing slash or /v1, and keep the key in VIDOC_API_KEY. Example dashboard URLs below use https://app.vidoc.dev. The API returns links with the web app host configured for your deployment. The Issues API gives programmatic access to the validated security issues of one project: list them, read one issue with its detail fields, get its fix prompt, and change its status one at a time or in bulk.

The API key names the project. Every route reads and writes that project only, so there is no projectId parameter. For a second project, create a second key. See API Authentication.

If a route on this page answers 404 Cannot GET /v1/issues, the API you call runs a release that does not have the Issues API yet. The older route GET /v1/codebase/:codebaseId/issues?branchName=main keeps working; see Legacy Route.

Find repository IDs with List Codebases.

List Issues

Endpoint

GET /v1/issues

Requires issue:view. Lists the validated issues of the project, most severe first. The API returns true positives only: findings that validation marked as false positives, or that validation has not finished, never appear. Without codebaseId, every repository of the project contributes its default branch.

Query Parameters

Parameter	Type	Default	Description
`codebaseId`	string	all repositories	Filter by repository. It must belong to the project; otherwise `404 Codebase not found`
`branch`	string	the default branch	Branch to read. Send `codebaseId` with it; without `codebaseId` the API answers `400`
`status`	`open`, `ignored`, `fixed`, `closed`, `all`	`open`	`fixed` selects automatically resolved issues. `closed` includes both `closed` and `fixed`. `ignored` includes issues marked as false positive in the dashboard. `all` returns every state
`severity`	`informative`, `low`, `medium`, `high`, `critical`	all severities	Repeat the parameter (`severity=critical&severity=high`) or send one comma list (`severity=critical,high`)
`path`	string	none	A substring of the file path. The match is case-insensitive
`scanId`	string	none	Match the scan ID stored on the issue. Other filters, including the branch, still apply. Send `codebaseId` and `branch` to read a non-default branch.
`updatedAfter`	ISO 8601 timestamp with time zone	none	Include issues whose `updatedAt` is equal to or later than this time.
`sort`	`severity`, `createdAt`, `updatedAt`, `category`	`severity`	See the sorting notes below
`dir`	`asc`, `desc`	`desc`
`limit`	integer, 1 to 100	50	Results per page
`offset`	integer, 0 or more	0	Pagination offset

Unknown query parameters return 400 with code: unknown_parameter. There is no category filter. Filter by category on the client after the read. The scanId filter reads current issue records. It is not a historical snapshot: later scans and triage actions can change these records. Use updatedAfter with status=all for synchronization. The time comparison is inclusive; de-duplicate records by instanceId when you repeat a timestamp. Sorting notes:

The list keeps the order of the dashboard. When the project has triage priorities, issues come in priority order first, and sort and dir order the issues inside each priority group. sort=severity&dir=asc can therefore return high before medium.
sort=category orders by the platform’s category order, not alphabetically, and ignores dir.

Example Request

curl "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues?status=open&severity=critical,high&limit=50&offset=0" \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Response

This example shows one issue; additional rows are omitted.

{
  "issues": [
    {
      "instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70",
      "canonicalId": "019f8a2c-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "name": "SQL injection in user lookup",
      "tldr": "User input reaches a raw query without parameterization.",
      "severity": "critical",
      "status": "open",
      "statusReason": null,
      "statusChangedAt": null,
      "category": "sqli",
      "cwe": 89,
      "cvssScore": 9.1,
      "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
      "codebaseName": "api",
      "branchName": "main",
      "path": "src/db/users.ts",
      "line": 41,
      "rangeStart": 39,
      "rangeEnd": 44,
      "pullRequestId": null,
      "scanId": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-10T08:00:00.000Z",
      "url": "https://app.vidoc.dev/projects/019f8a00-1b2c-7d3e-8f40-5a6b7c8d9e0f/issues?issue=...",
      "lastSeenAt": "2026-09-10T08:00:00.000Z",
      "commitSha": null,
      "triage": null
    }
  ],
  "total": 23,
  "limit": 50,
  "offset": 0,
  "stats": {
    "severityCounts": {
      "critical": 3,
      "high": 20,
      "medium": 0,
      "low": 0,
      "informative": 0
    },
    "statusCounts": {
      "open": 23,
      "ignored": 14,
      "closed": 30
    },
    "triage": null
  }
}

total counts the issues that pass the filters, not the rows in this page. To read the next page, add limit to offset.
stats.severityCounts counts the issues that pass every filter, by severity.
stats.statusCounts counts the issues that pass the other filters, by status, so you see how many issues are ignored or closed while you list the open ones.
stats.triage is null without a triage view. Otherwise, hiddenByPolicy counts issues hidden by the triage policy. The list and its severity counts use that policy.

Get Issue Details

Endpoint

GET /v1/issues/:instanceId

Requires issue:view. instanceId is the instanceId of a list row.

Example Request

curl "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70" \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Response

Every field of a list row, plus the detail fields validationVerdict, validationReason, attackVector, statusChangedBy, fileId and snippet:

{
  "instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70",
  "canonicalId": "019f8a2c-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "name": "SQL injection in user lookup",
  "tldr": "User input reaches a raw query without parameterization.",
  "severity": "critical",
  "status": "open",
  "statusReason": null,
  "statusChangedAt": null,
  "category": "sqli",
  "cwe": 89,
  "cvssScore": 9.1,
  "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
  "codebaseName": "api",
  "branchName": "main",
  "path": "src/db/users.ts",
  "line": 41,
  "rangeStart": 39,
  "rangeEnd": 44,
  "pullRequestId": null,
  "scanId": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-09-10T08:00:00.000Z",
  "url": "https://app.vidoc.dev/projects/019f8a00-1b2c-7d3e-8f40-5a6b7c8d9e0f/issues?issue=...",
  "validationVerdict": "true-positive",
  "validationReason": "The userId query parameter is concatenated into the SQL string with no parameter binding.",
  "attackVector": "network",
  "statusChangedBy": null,
  "fileId": "019f8a1c-2d3e-7f40-a1b2-c3d4e5f60718",
  "snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;\nconst rows = await db.raw(query);",
  "lastSeenAt": "2026-09-10T08:00:00.000Z",
  "commitSha": null,
  "triage": null
}

Two gates apply:

404 for an issue you must not see. The API answers 404 Issue not found when the instance is not in the key’s project, when it is deleted, and when it belongs to an experiment pull request. The answer is the same as for an unknown ID.
Teaser redaction. An organization in the onboarding teaser sees a small part of the scan. For a redacted issue, tldr, statusReason, validationReason and snippet hold the notice Unlock the full Vidoc report to view this finding detail. The other fields keep their values.

Get the Fix Prompt

Endpoint

GET /v1/issues/:instanceId/fix-prompt

Requires issue:view. Returns the same text as the Copy fix prompt button in the dashboard. Give the prompt to a coding agent to start the fix. The 404 rules of GET /v1/issues/:instanceId apply.

curl "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70/fix-prompt" \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Response

{
  "instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70",
  "prompt": "/goal Fix the critical-severity SQL injection in user lookup (CWE-89) in src/db/users.ts.\n\n/context\n..."
}

The prompt has the sections /goal, /context, /code, /fix and /done-when. The /code section holds the source lines with a gutter; line numbers in the prompt start at 1.

Update Issue Status

Endpoint

PATCH /v1/issues/:instanceId

Requires issue:update_status (roles developer, security_engineer, admin) and a key that belongs to a user. Keys created in the dashboard qualify; system, GitHub and legacy tokens get 403 Status changes need a user API key.

Request Body

Field	Type	Description
`status`	string	Required. `open`, `ignored` or `closed`. The API does not accept `fixed`; send `closed` instead
`reason`	string	2000 characters or fewer, trimmed before the length check. Required for `ignored`, with 5 characters or more. Optional for `open` and `closed`. The API stores it for every status; if you omit it, the stored reason is cleared

Effects, in this order:

The API writes the row: status, statusReason, statusChangedBy (the user of the key), statusChangedAt, and fixedAt for closed.
When status is ignored and a reason is present, a learning workflow starts. The learning changes how later scans judge similar code, so write a reason that says why the code is safe or why the team accepts the risk.

Close an Issue

curl -X PATCH "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed", "reason": "Fixed in PR #412"}'

Ignore an Issue

curl -X PATCH "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ignored",
    "reason": "False positive - input is validated by the schema layer before this call"
  }'

Reopen an Issue

curl -X PATCH "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "open"}'

Response

{
  "instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70",
  "status": "ignored",
  "statusReason": "False positive - input is validated by the schema layer before this call",
  "statusChangedAt": "2026-09-18T12:00:00.166Z",
  "learningWorkflowId": "learning-019f8b01-2c3d-7e4f-a5b6-c7d8e9f0a1b2"
}

learningWorkflowId is null when no learning workflow starts (every status other than ignored).

The call is not idempotent for the learning. A second call with the same body writes the same row but starts a second learning workflow. Send the request one time per verdict.

statusChangedAt in this response has millisecond precision. The stored value is truncated to the second, so a later GET of the same issue returns 2026-09-18T12:00:00.000Z for this change. Compare timestamps at second precision.

Update Many Issues (Bulk)

Endpoint

PATCH /v1/issues

Same permission and user-key rule as the single update. Use it to triage a filtered list.

Request Body

Field	Type	Description
`updates`	array	Required. 1 to 100 items. Each `instanceId` must be unique; a duplicate gives `400`, with `Duplicate instanceId values` in the `errors` array
`updates[].instanceId`	string	Required
`updates[].status`	string	Same rule as the single update
`updates[].reason`	string	Same rule as the single update

Each item runs on its own: the items share no transaction, a failed item does not stop the others, and the API runs 4 items at a time.

curl -X PATCH "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/issues" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70", "status": "ignored", "reason": "The schema layer validates this input."},
      {"instanceId": "019f8a2c-0000-7000-8000-000000000000", "status": "open"}
    ]
  }'

Response

200, with one result per item, in the order of the input:

{
  "results": [
    {
      "instanceId": "019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70",
      "ok": true,
      "status": "ignored",
      "statusReason": "The schema layer validates this input.",
      "statusChangedAt": "2026-09-18T12:00:00.166Z",
      "learningWorkflowId": "learning-019f8b01-2c3d-7e4f-a5b6-c7d8e9f0a1b2"
    },
    {
      "instanceId": "019f8a2c-0000-7000-8000-000000000000",
      "ok": false,
      "code": "issue_not_found",
      "message": "Issue not found"
    }
  ],
  "summary": { "total": 2, "succeeded": 1, "failed": 1 }
}

The route answers 200 always, also when every item fails. Read summary.failed, then the items with ok: false. A failed item has a code: issue_not_found for an unknown issue, internal_error for any other failure. Validation of the body itself (an empty array, more than 100 items, a duplicate ID, an invalid status) fails the whole request with 400.

Field Reference

Summary Fields

These fields are in each row of GET /v1/issues and in the response of GET /v1/issues/:instanceId.

Field	Type	Meaning
`instanceId`	string	The ID of this issue in this repository and branch. Use it in every route
`canonicalId`	string	The ID of the finding across branches and scans
`name`	string	The short title of the finding
`tldr`	string	One or two sentences that say what is wrong
`severity`	enum	`informative`, `low`, `medium`, `high` or `critical`
`status`	enum	`open`, `ignored`, `closed`, or `fixed`. Refer to Status values.
`statusReason`	string or null	The reason of the last status change
`statusChangedAt`	string or null	The time of the last status change, ISO 8601
`category`	string	The security category, for example `sqli`. See Issue Categories
`cwe`	number	The CWE number of the finding
`cvssScore`	number	The CVSS score of the finding
`codebaseId`	string	The repository that holds the file
`codebaseName`	string	The name of that repository
`branchName`	string	The branch the scan read
`path`	string	The file path from the root of the repository
`line`	number	The line of the finding, zero-based
`rangeStart`	number	The first line of the finding, zero-based
`rangeEnd`	number	The last line of the finding, zero-based
`pullRequestId`	string or null	The pull request that found the issue, or `null` for a branch scan
`scanId`	string or null	The scan currently associated with the issue
`lastSeenAt`	string	The last time a scan saw the issue, ISO 8601
`commitSha`	string or null	The commit of the associated scan, when available
`triage`	object or null	Triage disposition and `priorityGroup` (number or null), when a triage view applies
`createdAt`	string	When the platform first saw the issue, ISO 8601
`updatedAt`	string	The time of the last change, ISO 8601
`url`	string	The dashboard link to this issue

Detail Fields

GET /v1/issues/:instanceId adds these fields.

Field	Type	Meaning
`validationVerdict`	enum	`true-positive`, `false-positive` or `unknown`
`validationReason`	string or null	Why the validation agent gave that verdict
`attackVector`	enum or null	`network`, `adjacent`, `local` or `physical`
`statusChangedBy`	string or null	The user ID of the last status change, or `null`
`fileId`	string	The indexed file that holds the finding
`snippet`	string	The source lines of the issue range, as the dashboard shows them

Line Numbers

line, rangeStart and rangeEnd are zero-based line indexes, as the platform stores them. The dashboard shows line + 1. Add 1 before you show a line number to a person.

Status Values

status is the value the platform stores:

fixed: a scan automatically resolved the issue. This value is still used for new scan results.
closed: a user closed the issue, or revalidation no longer confirmed it.

The web app shows both as Closed. Use status=fixed to select automatic resolutions only, or status=closed to select both values. Status-update requests do not accept fixed; a user sends closed instead. Refer to Finding lifecycle.

Issue Categories

category holds one of these values:

xss, sqli, nosql-injection, command-injection, rce, path-traversal, idor, csrf,
ssrf, ssti, dos, open-redirect, prototype-pollution, insecure-deserialization,
broken-access-control, broken-authentication, information-disclosure,
sensitive-data-logging, weak-cryptography, weak-randomness, insecure-transport,
misconfiguration, header-injection, log-injection, path-injection,
session-fixation, unrestricted-file-upload, timing-side-channel, race-condition,
memory-safety, regex-injection, postmessage-misuse, hardcoded-secrets,
supply-chain-risk, excessive-privileges, xxe, code-evaluation, unknown

See Security Categories for what each category means.

Pagination

For large result sets, use total to drive pagination:

async function getAllIssues(apiKey, codebaseId) {
  const apiUrl = process.env.VIDOC_API_URL;
  if (!apiUrl) throw new Error('Set VIDOC_API_URL to your deployment URL');
  const issues = [];
  const limit = 100;
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const response = await fetch(
      `${apiUrl}/v1/issues?codebaseId=${codebaseId}&limit=${limit}&offset=${offset}`,
      {
        headers: { 'x-vidoc-token': apiKey }
      }
    );

    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    const data = await response.json();
    issues.push(...data.issues);
    total = data.total;
    offset += limit;
  }

  return issues;
}

Filtering Examples

Critical and High Open Issues

GET /v1/issues?severity=critical,high&status=open

By Repository and Branch

GET /v1/issues?codebaseId=019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a&branch=release/2.4

By File Path

GET /v1/issues?path=src/api/

Every State, Newest First

GET /v1/issues?status=all&sort=createdAt&dir=desc

Ignored Issues of One Repository

GET /v1/issues?codebaseId=019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a&status=ignored

Errors

Case	HTTP	`message`
No or unknown key	`401`	`Token is missing` or `Invalid or expired token`
The key’s role lacks the permission	`403`	`Missing required permission(s): issue:update_status`
`PATCH` with a system, GitHub or legacy token	`403`	`Status changes need a user API key`
Unknown query or body parameter	`400`	`Validation failed`, with `code: unknown_parameter` and the unknown keys in `errors`
Body or query fails the schema, `branch` without `codebaseId`, duplicate IDs	`400`	`Validation failed`, with `code: validation_failed` and the `errors` array
Unknown issue, other project, deleted, experiment pull request	`404`	`Issue not found`
`codebaseId` not in the project	`404`	`Codebase not found`
Anything else	`500`	`Internal server error`

See API Authentication for the body shape.

Legacy Route

GET /v1/codebase/:codebaseId/issues?branchName=main is the older route that feeds the vidoc CLI. It needs branchName, pages with page and pageSize (maximum 500), and returns a different shape: issues[] with a nested issue object, stats, and pagination. It stays available, but use GET /v1/issues for new work.

Limits, and What Is Not Here Yet

No rate limiting. The API does not count your requests today. Keep bulk requests at 100 items or fewer and do not run many at the same time.
No dedicated pull request route. Find a PR scan with GET /v1/scans?type=pull_request, then use its codebaseId, branch, and scanId to filter issues. The response is current state, not an immutable PR review.
No category filter. Filter on the client.
No webhooks. There is no event subscription. Poll with status=all&sort=updatedAt&dir=asc&updatedAfter=<timestamp>. Read every page and de-duplicate by instanceId at the inclusive timestamp boundary.
No OpenAPI document and no SDK. This page is the contract.

API Authentication

Authentication setup

Scanning API

Trigger scans

Issues Dashboard

Web interface

Security Categories

Issue categories

​List Issues

​Endpoint

​Query Parameters

​Example Request

​Response

​Get Issue Details

​Endpoint

​Example Request

​Response

​Get the Fix Prompt

​Endpoint

​Response

​Update Issue Status

​Endpoint

​Request Body

​Close an Issue

​Ignore an Issue

​Reopen an Issue

​Response

​Update Many Issues (Bulk)

​Endpoint

​Request Body

​Response

​Field Reference

​Summary Fields

​Detail Fields

​Line Numbers

​Status Values

​Issue Categories

​Pagination

​Filtering Examples

​Critical and High Open Issues

​By Repository and Branch

​By File Path

​Every State, Newest First

​Ignored Issues of One Repository

​Errors

​Legacy Route

​Limits, and What Is Not Here Yet

​Related Pages

API Authentication

Scanning API

Issues Dashboard

Security Categories

List Issues

Endpoint

Query Parameters

Example Request

Response

Get Issue Details

Endpoint

Example Request

Response

Get the Fix Prompt

Endpoint

Response

Update Issue Status

Endpoint

Request Body

Close an Issue

Ignore an Issue

Reopen an Issue

Response

Update Many Issues (Bulk)

Endpoint

Request Body

Response

Field Reference

Summary Fields

Detail Fields

Line Numbers

Status Values

Issue Categories

Pagination

Filtering Examples

Critical and High Open Issues

By Repository and Branch

By File Path

Every State, Newest First

Ignored Issues of One Repository

Errors

Legacy Route

Limits, and What Is Not Here Yet

Related Pages