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

# Security API reference

> REST API reference for the Security Scanner.

# Security API reference

Base URL: `https://api.withfoundry.ai`\
Auth: `Authorization: Bearer key_...`

All responses use the envelope `{ success, data, meta: { requestId } }`.

***

## Start scan

`POST /v1/security/scan`

Start a security scan for a repository.

**Request body**

| Field               | Type    | Required | Description                                                    |
| ------------------- | ------- | -------- | -------------------------------------------------------------- |
| `repoUrl`           | string  | Yes      | Clone URL (e.g. `https://github.com/org/repo`).                |
| `branch`            | string  | No       | Branch or ref to scan (default: default branch).               |
| `waitForCompletion` | boolean | No       | If true, long-poll until done and return findings in response. |

**Response** `data`

| Field      | Type   | Description                                                       |
| ---------- | ------ | ----------------------------------------------------------------- |
| `scanId`   | string | Id to fetch result (e.g. `scan_...`).                             |
| `status`   | string | `pending` \| `running` \| `completed` \| `failed`.                |
| `findings` | array  | Present when `waitForCompletion: true` and status is `completed`. |

**Example**

```bash theme={null}
curl -X POST https://api.withfoundry.ai/v1/security/scan \
  -H "Authorization: Bearer key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/your-org/your-repo","branch":"main"}'
```

***

## Get scan result

`GET /v1/security/scan/:scanId`

Retrieve scan status and findings.

**Path**

| Param    | Description                              |
| -------- | ---------------------------------------- |
| `scanId` | Id returned from POST /v1/security/scan. |

**Response** `data`

| Field      | Type   | Description                                        |
| ---------- | ------ | -------------------------------------------------- |
| `scanId`   | string | Same as path.                                      |
| `status`   | string | `pending` \| `running` \| `completed` \| `failed`. |
| `findings` | array  | List of findings when status is `completed`.       |
| `error`    | string | Optional; set when status is `failed`.             |

**Finding object**

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `id`          | string | Finding id.                                          |
| `severity`    | string | `critical` \| `high` \| `medium` \| `low` \| `info`. |
| `title`       | string | Short title.                                         |
| `description` | string | Detailed description.                                |
| `file`        | string | File path in repo.                                   |
| `line`        | number | Line number.                                         |
| `suggestion`  | string | Optional remediation.                                |

**Example**

```bash theme={null}
curl -H "Authorization: Bearer key_YOUR_KEY" \
  "https://api.withfoundry.ai/v1/security/scan/scan_abc123"
```