Uploading Findings

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

Note

This endpoint only accepts POST (findings upload). Querying and reading findings is done from the dashboard and is not publicly exposed.

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).