Findings, Answers, And Reports

This guide helps you tell workflow findings, analysis answers, and reports apart, and shows where to read each one.

The result surface has three separate resources:

• Findings belong to workflow runs. They record rule results with rule provenance, result state, limitations, and evidence.
• Answers belong to analysis runs. They are named by the analysis profile and carry typed fields, coverage, provenance, result state, limitations, and evidence.
• Reports present existing answer data. A run uses a stored report template by ID and version; the rerender endpoint accepts an inline template for a new presentation view.

None of these resources converts uncertainty into a clean pass.

Workflow Findings

List findings for a workflow run:

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/findings" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "run_id=$RUN_ID" \
  --data-urlencode "result_state=uncertain"

The finding response uses snake_case fields:

{
  "id": "finding_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "run_id": "run_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "workflow_id": "wf_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "rule_id": "rule_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "rule_reference": "SEC-04",
  "result_state": "uncertain",
  "status": "open",
  "evidence": [
    {
      "id": "evidence_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "video_id": "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "start_time": 42.25,
      "end_time": 49.75,
      "clip_url": "https://cdn.example.test/media/clip.mp4"
    }
  ]
}

Use GET /api/v1alpha1/findings/{finding_id} for one finding. Evidence URLs are reviewable product URLs. Result states are found, not_found, uncertain, and not_checked.

Analysis Answers

An analysis run returns answers at:

GET /api/v1alpha1/runs/{run_id}/answers

Answers have an answer_type, typed fields, coverage, limitations, provenance, and evidence references. Use expand[] when you need deeper events, evidence, snapshots, or provenance. Read the Analysis guide for the request language. Read Reports And Templates for the presentation language.

To turn completed answers into JSON or Markdown output, continue to Generate reports.

Trust Fields

Preserve result_state, limitations, provenance_ref, and evidence URLs when storing or exporting a result. A report is incomplete if its claim cannot be traced to its evidence.

When a report manifest contains signed evidence URLs, evidence_urls_expire_at gives their expiry time. Keep the evidence ID and call GET /api/v1alpha1/evidence/{evidence_id} to refresh an expired URL; the endpoint returns 302 Found with a fresh signed media URL and Cache-Control: no-store.