Uploading Findings

The findings endpoint is the entry point for all scanner-generated findings. The CLI uses it automatically when running gerion scan ... --push.

Prerequisite

Obtain a JWT first using the M2M authentication endpoint.

Endpoint

POST https://api.gerion.dev/api/v1/findings
Authorization: Bearer <jwt>
Content-Type: application/json

The JWT must have been generated with an API Key that has the write:findings permission.

Body

{
  "metadata": {
    "repository_name": "my-org/my-repo",
    "branch_name": "main",
    "scan_type": "SECRETS",
    "build_id": "build-2026-001",
    "code_path": "/src",
    "commit_hash": "abc123def456",
    "commit_author": "dev@example.com"
  },
  "findings": [
    {
      "finding_id": "secret-001",
      "title": "Exposed AWS Access Key",
      "severity": "CRITICAL",
      "scan_type": "SECRETS",
      "repository_name": "my-org/my-repo",
      "branch_name": "main",
      "build_id": "build-2026-001",
      "code_path": "/src",
      "active": true,
      "mitigated": false,
      "false_positive": false,
      "creation_date": "2026-03-19T10:00:00Z",
      "last_update_date": "2026-03-19T10:00:00Z",
      "file_path": "config/deploy.sh",
      "line_number": 42
    }
  ]
}

`metadata` fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | repository_name | string | ✓ | Repository name (org/repo). | | branch_name | string | ✓ | Scanned branch. | | build_id | string | ✓ | Build/pipeline identifier. | | code_path | string | ✓ | Root path of the scanned code. | | scan_type | string | — | SAST, SCA, SECRETS, IAC. Inferred from findings if omitted. | | commit_hash | string | — | Hash of the scanned commit. | | commit_author | string | — | Commit author. |

Finding fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | finding_id | string | ✓ | Unique finding ID (generated by the scanner). Used for deduplication. | | title | string | ✓ | Descriptive title. | | severity | string | — | CRITICAL, HIGH, MEDIUM, LOW. Normalized to uppercase. | | scan_type | string | — | SAST, SCA, SECRETS, IAC. | | repository_name | string | ✓ | Must match metadata.repository_name. | | branch_name | string | ✓ | Finding branch. | | build_id | string | ✓ | Build in which it was detected. | | code_path | string | ✓ | Project root path. | | active | bool | ✓ | true if the finding is still present. | | mitigated | bool | ✓ | true if mitigated in this scan. | | false_positive | bool | ✓ | true if marked as false positive. | | creation_date | string | ✓ | ISO 8601. | | last_update_date | string | ✓ | ISO 8601. | | file_path | string | — | Path of the affected file. | | line_number | int | — | Finding line number. | | cve | string | — | Related CVE (e.g. CVE-2021-44228). | | cwe | string[] | — | List of related CWEs. | | description | string | — | Detailed description. | | component_name | string | — | Affected component (SCA/IAC). | | component_version | string | — | Component version. | | component_fix | string | — | Version that fixes the issue. |

Success response (201)

{
  "success": true,
  "message": "Findings processed successfully",
  "result": {
    "created": 3,
    "updated": 1,
    "mitigated": 0,
    "duplicates": 2
  }
}

Deduplication

The server deduplicates by (finding_id, organization_id, repository_name, branch_name, scan_type). If a finding already exists, it is updated rather than created. Findings present in previous runs but absent from the current payload are automatically marked as mitigated.

Common errors

| Code | Cause | |------|-------| | 401 | Missing, expired, or invalid JWT. | | 403 | JWT does not have the write:findings permission. | | 422 | Invalid or missing body fields. | | 429 | Rate limit exceeded (30 req/s, burst 10). |