> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues API

> Access and manage security issues via the REST API

The Issues API allows you to programmatically access security findings from your scans.

<Info>
  The Issues API is available for enterprise plans. Contact support for access.
</Info>

## List Issues

### Endpoint

```
GET /v1/issues
```

### Query Parameters

| Parameter    | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| `projectId`  | string | Filter by project                                  |
| `codebaseId` | string | Filter by repository                               |
| `status`     | string | `open`, `ignored`, `closed`                        |
| `severity`   | string | `critical`, `high`, `medium`, `low`, `informative` |
| `category`   | string | Security category (e.g., `sqli`, `xss`)            |
| `limit`      | number | Results per page (default: 50, max: 100)           |
| `offset`     | number | Pagination offset                                  |

### Example Request

```bash theme={null}
curl "https://api.vidocsecurity.com/v1/issues?status=open&severity=critical" \
  -H "Authorization: Bearer $VIDOC_API_KEY"
```

### Response

```json theme={null}
{
  "issues": [
    {
      "id": "issue_abc123",
      "title": "SQL Injection in user query",
      "severity": "critical",
      "category": "sqli",
      "status": "open",
      "filePath": "src/db/users.js",
      "lineNumber": 45,
      "codebaseId": "codebase_xyz",
      "branch": "main",
      "createdAt": "2024-01-15T10:35:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Get Issue Details

### Endpoint

```
GET /v1/issues/:issueId
```

### Example Request

```bash theme={null}
curl https://api.vidocsecurity.com/v1/issues/issue_abc123 \
  -H "Authorization: Bearer $VIDOC_API_KEY"
```

### Response

```json theme={null}
{
  "id": "issue_abc123",
  "title": "SQL Injection in user query",
  "description": "User input is directly concatenated into SQL query without sanitization.",
  "severity": "critical",
  "category": "sqli",
  "status": "open",
  "filePath": "src/db/users.js",
  "lineNumber": 45,
  "codeSnippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
  "remediation": "Use parameterized queries to prevent SQL injection.",
  "codebaseId": "codebase_xyz",
  "branch": "main",
  "scanId": "scan_789",
  "createdAt": "2024-01-15T10:35:00Z"
}
```

## Update Issue Status

### Endpoint

```
PATCH /v1/issues/:issueId
```

### Request Body

| Field    | Type   | Description                             |
| -------- | ------ | --------------------------------------- |
| `status` | string | New status: `open`, `ignored`, `closed` |
| `reason` | string | Reason (required for `ignored`)         |

### Mark as Fixed

```bash theme={null}
curl -X PATCH https://api.vidocsecurity.com/v1/issues/issue_abc123 \
  -H "Authorization: Bearer $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}'
```

### Ignore Issue

```bash theme={null}
curl -X PATCH https://api.vidocsecurity.com/v1/issues/issue_abc123 \
  -H "Authorization: Bearer $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ignored",
    "reason": "False positive - input is sanitized in middleware"
  }'
```

### Response

```json theme={null}
{
  "id": "issue_abc123",
  "status": "ignored",
  "updatedAt": "2024-01-15T11:00:00Z"
}
```

## Issue Categories

| Category            | Description                      |
| ------------------- | -------------------------------- |
| `sqli`              | SQL Injection                    |
| `xss`               | Cross-Site Scripting             |
| `command-injection` | Command Injection                |
| `ssrf`              | Server-Side Request Forgery      |
| `path-traversal`    | Path Traversal                   |
| `idor`              | Insecure Direct Object Reference |
| `hardcoded-secrets` | Hardcoded Credentials            |
| `weak-cryptography` | Weak Cryptography                |

See [Security Categories](/security/overview) for the full list.

## Pagination

For large result sets, use pagination:

```javascript theme={null}
async function getAllIssues(apiKey, projectId) {
  const issues = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://api.vidocsecurity.com/v1/issues?projectId=${projectId}&limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );

    const data = await response.json();
    issues.push(...data.issues);

    if (data.issues.length < limit) {
      break; // No more results
    }

    offset += limit;
  }

  return issues;
}
```

## Filtering Examples

### Critical Issues Only

```
GET /v1/issues?severity=critical&status=open
```

### By Repository

```
GET /v1/issues?codebaseId=codebase_abc123
```

### By Category

```
GET /v1/issues?category=sqli
```

### Multiple Filters

```
GET /v1/issues?severity=high&category=xss&status=open
```

## Webhooks (Coming Soon)

Subscribe to issue events:

* New issue detected
* Issue status changed
* Scan completed

Contact support to join the beta.

## Related Pages

<CardGroup cols={2}>
  <Card title="API Authentication" icon="key" href="/api/authentication">
    Authentication setup
  </Card>

  <Card title="Scanning API" icon="magnifying-glass" href="/api/scanning">
    Trigger scans
  </Card>

  <Card title="Issues Dashboard" icon="bug" href="/dashboard/issues">
    Web interface
  </Card>

  <Card title="Security Categories" icon="shield" href="/security/overview">
    Issue categories
  </Card>
</CardGroup>