Findings

Findings are issues discovered by agents during test runs, discoveries, and test plans. Each finding includes severity, evidence linking back to specific agent trace steps, and a lifecycle status (open, regressed, resolved, dismissed).

GET /api/v1/findings

List findings

Returns tenant findings visible to the authenticated principal. Defaults to active findings (open and regressed) when status is omitted. Follow next_cursor with the same filters and sort to read subsequent pages.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	No	Restrict results to one project.
`severity`	string	query	No	Severity filter.
`status`	string	query	No	Comma-separated lifecycle status filter.
`source`	string	query	No	Finding source filter.
`type`	string	query	No	Finding type filter.
`date_range`	string	query	No	Recently observed findings window.
`day`	date	query	No	Calendar day on which the finding was first seen.
`query`	string	query	No	Case-insensitive title substring.
`sort`	string	query	No	Finding ordering.
`limit`	integer	query	No	Maximum findings to return.
`cursor`	string	query	No	Continue pagination from the next_cursor of the previous page. Opaque; send it with the same sort and filters.
`not_seen_days`	integer	query	No	Only findings whose last recorded observation is older than N days. This does not establish that a relevant test ran or that the issue was fixed. Staleness alone is not evidence for resolving or dismissing a finding.
`url`	string	query	No	Case-insensitive fragment of the finding's normalized host and path.
`agent_id`	uuid	query	No	Only findings with evidence observed by this agent run.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/findings" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Matching findings.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`findings`	object[]
`findings[].id`	uuid
`findings[].tenant_id`	uuid
`findings[].project_id`	uuid
`findings[].type`	string
`findings[].severity`	string
`findings[].title`	string
`findings[].description`	string
`findings[].url`	string
`findings[].element`	string
`findings[].source`	string
`findings[].origin`	string
`findings[].impact`	string
`findings[].remediation`	string
`findings[].status`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`findings[].github_repo`	string
`findings[].github_issue_number`	integer
`findings[].github_issue_url`	string
`findings[].github_issue_created_at`	date-time
`findings[].created_at`	date-time
`findings[].first_seen_at`	date-time
`findings[].last_seen_at`	date-time
`findings[].evidence_count`	integer
`findings[].last_agent_id`	uuid
`findings[].last_agent_name`	string
`findings[].test_id`	uuid
`findings[].test_name`	string
`total`	integer	Findings matching the filters across every page.
`next_cursor`	string	Opaque cursor for the next page; absent on the last page.

GET /api/v1/findings/summary

Summarize findings

Returns counts of the tenant's visible findings by status, severity, type, and source. Defaults to all lifecycle states, unlike the findings list which defaults to open and regressed. Supply matching status filters when comparing the summary with the list.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	No	Restrict results to one project.
`severity`	string	query	No	Comma-separated severity filter.
`status`	string	query	No	Comma-separated lifecycle status filter; every state when omitted.
`source`	string	query	No	Comma-separated source filter.
`type`	string	query	No	Comma-separated finding type filter.
`date_range`	string	query	No	Only findings observed within a recent window.
`not_seen_days`	integer	query	No	Only findings whose last recorded observation is older than N days. This does not establish that a relevant test ran or that the issue was fixed. Staleness alone is not evidence for resolving or dismissing a finding.
`url`	string	query	No	Case-insensitive fragment of the finding's normalized host and path.
`agent_id`	uuid	query	No	Only findings with evidence observed by this agent run.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/findings/summary" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Tenant findings summary.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`total`	integer
`by_status`	object	Counts keyed by a finding classification value.
`by_severity`	object	Counts keyed by a finding classification value.
`by_type`	object	Counts keyed by a finding classification value.
`by_source`	object	Counts keyed by a finding classification value.

POST /api/v1/findings/transition

Transition findings in bulk

Applies one lifecycle action to up to 100 findings atomically with a shared reason. If any finding is missing, hidden, or cannot take the action from its current state, nothing changes.

Request Body (application/json)

Field	Type	Required	Description
`action`	string	Yes	Lifecycle action a caller may apply to a finding.
`ids`	string[]	Yes
`reason`	string	Yes	Why this action is being applied to every listed finding.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/findings/transition" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "<string>",
    "ids": ["<string>"],
    "reason": "<string>"
  }'

Status Codes

Code	Description
`200`	The action was applied to every listed finding.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`action`	string	Lifecycle action a caller may apply to a finding. Values: resolve, dismiss, reopen.
`updated`	integer	Findings the action was applied to.
`ids`	uuid[]

GET /api/v1/findings/{id}

Get a finding

Returns a visible tenant finding with its evidence chain and its lifecycle history (every resolve, dismiss, reopen, and regress with who applied it and why).

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Finding ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/findings/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Finding and evidence.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`finding`	object	A tenant finding and its current lifecycle state.
`finding.id`	uuid
`finding.tenant_id`	uuid
`finding.project_id`	uuid
`finding.type`	string
`finding.severity`	string
`finding.title`	string
`finding.description`	string
`finding.url`	string
`finding.element`	string
`finding.source`	string
`finding.origin`	string
`finding.impact`	string
`finding.remediation`	string
`finding.status`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`finding.status_changed_at`	date-time	When the finding last changed state. Who changed it and why is in the history returned by getFinding.
`finding.github_repo`	string
`finding.github_issue_number`	integer
`finding.github_issue_url`	string
`finding.github_issue_created_at`	date-time
`finding.github_pr_number`	integer
`finding.github_pr_url`	string
`finding.github_pr_created_at`	date-time
`finding.first_seen_at`	date-time
`finding.last_seen_at`	date-time
`finding.created_at`	date-time
`finding.updated_at`	date-time
`evidence`	object[]
`evidence[].agent_id`	uuid
`evidence[].agent_name`	string
`evidence[].test_id`	uuid
`evidence[].test_name`	string
`evidence[].trace_step_id`	uuid
`evidence[].trace_step_index`	integer
`evidence[].observed_at`	date-time
`history`	object[]	Every recorded status transition, oldest first. Empty for a finding that has never left open. The finding's current status equals the `to` of the last entry.
`history[].occurred_at`	date-time
`history[].action`	string	The lifecycle action that was applied. regress is only ever applied by the auditor. Values: resolve, dismiss, reopen, regress.
`history[].from`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`history[].to`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`history[].reason`	string	Why the action was applied. Absent when the web UI applied it without a reason.
`history[].channel`	string	The surface the action came through. Values: web, api, chat, auditor.
`history[].actor`	object	Who applied a lifecycle action. Exactly one id is present, matching the kind.
`history[].actor.kind`	string	user is a signed-in person (web, chat, or a user-owned API key); api_key is a tenant-owned key with no person behind it; auditor is the audit worker acting on a run's outcome. Values: user, api_key, auditor.
`history[].actor.user_id`	uuid
`history[].actor.api_key_id`	uuid
`history[].actor.agent_id`	uuid	The run whose audit triggered the change, for the auditor.

POST /api/v1/findings/{id}/dismiss

Dismiss a finding

Marks the finding dismissed (not a bug, obsolete, or a test-fixture artifact) and records who did it and why in the finding history. Dismissing an already dismissed finding is a no-op and records nothing.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Finding ID.

Request Body (application/json)

Field	Type	Required	Description
`reason`	string	Yes	Why this action is being applied. Recorded in the finding history so a scripted decision stays auditable.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/findings/<id>/dismiss" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "<string>"
  }'

Status Codes

Code	Description
`200`	The dismissed finding.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`type`	string
`severity`	string
`title`	string
`description`	string
`url`	string
`element`	string
`source`	string
`origin`	string
`impact`	string
`remediation`	string
`status`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`status_changed_at`	date-time	When the finding last changed state. Who changed it and why is in the history returned by getFinding.
`github_repo`	string
`github_issue_number`	integer
`github_issue_url`	string
`github_issue_created_at`	date-time
`github_pr_number`	integer
`github_pr_url`	string
`github_pr_created_at`	date-time
`first_seen_at`	date-time
`last_seen_at`	date-time
`created_at`	date-time
`updated_at`	date-time

POST /api/v1/findings/{id}/reopen

Reopen a finding

Returns a resolved or dismissed finding to open and records who did it and why in the finding history. Reopening an open finding is a no-op and records nothing.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Finding ID.

Request Body (application/json)

Field	Type	Required	Description
`reason`	string	Yes	Why this action is being applied. Recorded in the finding history so a scripted decision stays auditable.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/findings/<id>/reopen" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "<string>"
  }'

Status Codes

Code	Description
`200`	The reopened finding.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`type`	string
`severity`	string
`title`	string
`description`	string
`url`	string
`element`	string
`source`	string
`origin`	string
`impact`	string
`remediation`	string
`status`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`status_changed_at`	date-time	When the finding last changed state. Who changed it and why is in the history returned by getFinding.
`github_repo`	string
`github_issue_number`	integer
`github_issue_url`	string
`github_issue_created_at`	date-time
`github_pr_number`	integer
`github_pr_url`	string
`github_pr_created_at`	date-time
`first_seen_at`	date-time
`last_seen_at`	date-time
`created_at`	date-time
`updated_at`	date-time

POST /api/v1/findings/{id}/resolve

Resolve a finding

Marks the finding resolved (fixed, or no longer reproducible) and records who did it and why in the finding history. Resolving an already resolved finding is a no-op and records nothing.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Finding ID.

Request Body (application/json)

Field	Type	Required	Description
`reason`	string	Yes	Why this action is being applied. Recorded in the finding history so a scripted decision stays auditable.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/findings/<id>/resolve" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "<string>"
  }'

Status Codes

Code	Description
`200`	The resolved finding.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`type`	string
`severity`	string
`title`	string
`description`	string
`url`	string
`element`	string
`source`	string
`origin`	string
`impact`	string
`remediation`	string
`status`	string	Finding lifecycle state. Values: open, regressed, resolved, dismissed.
`status_changed_at`	date-time	When the finding last changed state. Who changed it and why is in the history returned by getFinding.
`github_repo`	string
`github_issue_number`	integer
`github_issue_url`	string
`github_issue_created_at`	date-time
`github_pr_number`	integer
`github_pr_url`	string
`github_pr_created_at`	date-time
`first_seen_at`	date-time
`last_seen_at`	date-time
`created_at`	date-time
`updated_at`	date-time