Findings and review

Finding endpoints use /scans, the existing API resource name. Use X-HASHIRO-TOKEN with https://api.hashiro.ai/api/.

Access

Read access follows project membership or organization-wide project access. Creation, update, and deletion require pentester/project-management permission and a permitted provider or client-owned project. Clients can review eligible public AI candidates, but cannot access private provider drafts or unrelated findings.

Routes

Method	Path	Operation
GET	/scans/	List findings with project, page, pageSize
GET	/scans/:scanId	Read a finding
PUT	/scans/:projectName	Create a finding
POST	/scans/:projectName	Update a finding using its ID in the body
DELETE	/scans/:projectName/:scanId	Delete a finding
POST	/scans/:projectName/bulk-status	Change selected findings status
POST	/scans/:projectName/bulk-delete	Delete selected findings
POST	/scans/:projectName/:scanId/review	Review a candidate with its expected version
POST	/scans/:projectName/:scanId/ai/demonstration	Generate a draft demonstration for review
POST	/scans/:projectName/:scanId/ai/demonstration/apply	Apply a reviewed draft
POST	/scans/:projectName/:scanId/ai/merge	Propose a merge for review

Create a finding

Send this body to PUT /scans/my-project:

{
  "title":"Missing security header",
  "asset":["app.example.com"],
  "severity":"low",
  "description":"Observed during the assessment",
  "remediation":"Configure the required header"
}

asset is an array, even for one host. Optional fields include observation, demonstration, remediation, references, requests, CVSS, and tags. References must be HTTP or HTTPS URLs. cwe and owasp, when supplied, are also URLs.

Creation returns a result containing success and Ids; preserve those identifiers. Clients' new findings are opened according to the server's policy; do not assume a requested draft status is accepted for every caller.

Update

POST /scans/my-project requires id, title, and a nonempty asset array. Read the current finding first, preserve these required fields, and submit the permitted changes. Pending AI candidates must use the candidate-review route for status decisions.

Bulk status

{
  "ids":["FINDING_ID"],
  "status":"pending_retest"
}

Send to POST /scans/my-project/bulk-status. Bulk requests are limited to 500 IDs. bulk-delete accepts the ids array without status and permanently removes authorized findings.

Candidate review

Use the review version returned by the candidate and submit the decision with expected_review_version. A conflict requires reading the latest record before deciding again. Review and merge options are constrained by the caller's role, project, and candidate visibility. AI draft generation can consume credits; review the draft before applying it.

See the issue lifecycle and AI review guide for the interface workflow.