---
updatedAt: 2026-07-26T12:31:37.000Z
agentTools:
  siteIndex: https://docs.jfrog.com/llms.txt
  projectIndex: https://docs.jfrog.com/security/llms.txt
---

# Get Violations

Gets Xray violations based on a set of search criteria. Returns violations with details about severity, type, infected components, and impacted artifacts. Use the `filters` object to narrow results by violation type, watch, severity, time range, CVE, issue ID, and specific resources. Use the `pagination` object to control sorting and paging.

Starting from Xray version 3.42.3, JFrog Security CVE Research and Enrichment data is supported in the response. Fields short_description, full_description, and remediation are markdown.

Requires a user with Read permissions.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Xray REST APIs",
    "description": "Combined JFrog Xray REST API specification (all endpoints).",
    "version": "3.140"
  },
  "servers": [
    {
      "url": "https://jf.example.com/xray",
      "description": "JFrog Platform (Xray)"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/api/v1/violations": {
      "post": {
        "operationId": "get-violations",
        "summary": "Get Violations",
        "description": "Gets Xray violations based on a set of search criteria. Returns violations with details about severity, type, infected components, and impacted artifacts. Use the `filters` object to narrow results by violation type, watch, severity, time range, CVE, issue ID, and specific resources. Use the `pagination` object to control sorting and paging.\n\nStarting from Xray version 3.42.3, JFrog Security CVE Research and Enrichment data is supported in the response. Fields short_description, full_description, and remediation are markdown.\n\nRequires a user with Read permissions.\n",
        "tags": [
          "Violations V1"
        ],
        "parameters": [
          {
            "name": "projectKey",
            "in": "query",
            "description": "When included, the response is scoped to the specified project.\n",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ViolationsSearchRequest"
              },
              "examples": {
                "scoped": {
                  "summary": "Filter by an artifact and a git repository",
                  "value": {
                    "filters": {
                      "resources": {
                        "artifacts": [
                          {
                            "repo": "libs-release-local",
                            "path": "jfrog-artifactory-pro-5.9.0.zip"
                          }
                        ],
                        "git_repositories": [
                          {
                            "name": "github.com/jfrog/cli-security.git"
                          }
                        ]
                      }
                    },
                    "pagination": {
                      "order_by": "created",
                      "direction": "desc",
                      "limit": 25,
                      "offset": 1
                    }
                  }
                },
                "allResourceTypes": {
                  "summary": "Filter using all supported resource types",
                  "value": {
                    "filters": {
                      "violation_type": "Security",
                      "min_severity": "High",
                      "resources": {
                        "artifacts": [
                          {
                            "repo": "default/libs-release-local",
                            "path": "jfrog-artifactory-pro-5.9.0.zip"
                          }
                        ],
                        "builds": [
                          {
                            "name": "my-build",
                            "number": "51",
                            "project": "default"
                          }
                        ],
                        "release_bundles": [
                          {
                            "name": "my-release-bundle",
                            "version": "1.0.0"
                          }
                        ],
                        "release_bundles_v2": [
                          {
                            "name": "my-release-bundle-v2",
                            "version": "2.0.0",
                            "project": "default"
                          }
                        ],
                        "git_repositories": [
                          {
                            "name": "github.com/jfrog/cli-security.git"
                          }
                        ]
                      }
                    },
                    "pagination": {
                      "order_by": "severity",
                      "direction": "desc",
                      "limit": 50,
                      "offset": 1
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_violations": {
                      "type": "integer"
                    },
                    "violations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "description": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string"
                          },
                          "infected_components": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "created": {
                            "type": "string"
                          },
                          "watch_name": {
                            "type": "string"
                          },
                          "issue_id": {
                            "type": "string"
                          },
                          "violation_details_url": {
                            "type": "string"
                          },
                          "impacted_artifacts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "applicability": {
                            "type": "null"
                          }
                        },
                        "required": [
                          "description",
                          "severity",
                          "type",
                          "infected_components",
                          "created",
                          "watch_name",
                          "issue_id",
                          "violation_details_url",
                          "impacted_artifacts"
                        ]
                      }
                    }
                  },
                  "required": [
                    "total_violations",
                    "violations"
                  ]
                },
                "example": {
                  "total_violations": 1,
                  "violations": [
                    {
                      "description": "Number of new versions and Version Age",
                      "severity": "High",
                      "type": "Operational_Risk",
                      "infected_components": [
                        "gav://joda-time:joda-time:2.9.9"
                      ],
                      "created": "2022-03-24T14:54:42+02:00",
                      "watch_name": "OpRiskWatch",
                      "issue_id": "1ea7a8e0904b4a6c1a837e8ab437e0892dd00ad203814f3b9edfd2a3d8be3b88",
                      "violation_details_url": "http://test.jfrog.io/xray/api/v1/violations?watch_id=8d5a6d7364154c5c2455993a&issue_id=1ea7a8e0904b4a6c1a837e8ab437e0892dd00ad203814f3b9edfd2a3d8be3b88&comp_id=gav:%2F%2Forg.jruby:jruby-complete:9.2.0.0",
                      "impacted_artifacts": [
                        "default/generic-local/jruby-complete-9.2.0.0.jar"
                      ],
                      "applicability": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Possible causes include: malformed JSON body; `filters.watch_name` doesn't match an existing watch; a resource under `filters.resources` is missing a required field (for example an artifact without `repo`/`path`, or a build without `name`/`number`); an artifact `repo` isn't in a valid `bin-mgr-id/repo` format; or `created_from` is after `created_until`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No authentication credentials provided.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Permission denied. The user lacks Read or Manage Watches permission, anonymous access is disallowed, or the license is expired or invalid.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Returned instead of 401/403 when the tenant's \"Hide Unauthorized Resources\" setting is enabled, to avoid revealing that a resource exists.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "The `Content-Type` header isn't `application/json`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "A database query limitation was reached while processing the search.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Basic authentication using username/password or API key"
      }
    },
    "schemas": {
      "ViolationsSearchFilters": {
        "type": "object",
        "description": "Filtering parameters for a violations search.",
        "properties": {
          "name_contains": {
            "type": "string",
            "description": "Filter results where the description contains this string."
          },
          "include_details": {
            "type": "boolean",
            "description": "Include additional violation detail properties in the response. Used by `POST /api/v1/violations` only. For v2, use `pagination.include_details` instead.\n"
          },
          "violation_type": {
            "type": "string",
            "description": "Filter by violation type.",
            "enum": [
              "Security",
              "License",
              "Operational_Risk"
            ]
          },
          "watch_name": {
            "type": "string",
            "description": "Filter by watch name."
          },
          "min_severity": {
            "type": "string",
            "description": "Filter violations with severity equal to or higher than this value.",
            "enum": [
              "Critical",
              "High",
              "Medium",
              "Low",
              "Information",
              "Unknown"
            ]
          },
          "created_from": {
            "type": "string",
            "format": "date-time",
            "description": "Filter violations created from this time (RFC 3339)."
          },
          "created_until": {
            "type": "string",
            "format": "date-time",
            "description": "Filter violations created until this time (RFC 3339)."
          },
          "issue_id": {
            "type": "string",
            "description": "Filter by issue ID (e.g., XRAY-94620)."
          },
          "cve_id": {
            "type": "string",
            "description": "Filter by CVE ID (e.g., CVE-2019-17531)."
          },
          "resources": {
            "type": "object",
            "description": "Filter by specific resources.",
            "properties": {
              "artifacts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "repo": {
                      "type": "string",
                      "description": "Repository key. Optionally prefixed with the binary manager ID (e.g., default/libs-release-local).",
                      "example": "libs-release-local"
                    },
                    "path": {
                      "type": "string",
                      "description": "Artifact path within the repository.",
                      "example": "jfrog-artifactory-pro-5.9.0.zip"
                    }
                  }
                }
              },
              "builds": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Build name.",
                      "example": "my-build"
                    },
                    "number": {
                      "type": "string",
                      "description": "Build number.",
                      "example": "51"
                    },
                    "project": {
                      "type": "string",
                      "description": "Project key the build belongs to.",
                      "example": "default"
                    }
                  }
                }
              },
              "release_bundles": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Release bundle name.",
                      "example": "my-release-bundle"
                    },
                    "version": {
                      "type": "string",
                      "description": "Release bundle version.",
                      "example": "1.0.0"
                    }
                  }
                }
              },
              "release_bundles_v2": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Release bundle v2 name.",
                      "example": "my-release-bundle-v2"
                    },
                    "version": {
                      "type": "string",
                      "description": "Release bundle v2 version.",
                      "example": "2.0.0"
                    },
                    "project": {
                      "type": "string",
                      "description": "Project key the release bundle belongs to.",
                      "example": "default"
                    }
                  }
                }
              },
              "git_repositories": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Git repository identifier.",
                      "example": "github.com/jfrog/cli-security.git"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ViolationsSearchRequest": {
        "type": "object",
        "description": "Request body for searching violations. Contains a filters object for narrowing results and a pagination object for controlling sort order and paging.\n",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/ViolationsSearchFilters"
          },
          "pagination": {
            "type": "object",
            "description": "Pagination and sorting parameters.",
            "properties": {
              "order_by": {
                "type": "string",
                "description": "Sort field. Valid values: created, summary, severity, type, watcher_name, issue_id.",
                "example": "created"
              },
              "direction": {
                "type": "string",
                "description": "Sort direction.",
                "enum": [
                  "asc",
                  "desc"
                ]
              },
              "limit": {
                "type": "integer",
                "description": "Maximum number of items to return. Default: 25.",
                "example": 25
              },
              "offset": {
                "type": "integer",
                "description": "Page offset. Default: 1.",
                "example": 1
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Violations V1",
      "description": "APIs from Violations V1"
    }
  ]
}
```