---
title: "Upload a batch of findings and coverage"
method: PUT
path: "/v1/assessments/{assessmentId}/batches/{batchId}"
tags: ["Assessments"]
---

# Upload a batch of findings and coverage

`PUT /v1/assessments/{assessmentId}/batches/{batchId}`

## Request

- Base URL: `https://api.ironfang.com/security`
- URL: `https://api.ironfang.com/security/v1/assessments/{assessmentId}/batches/{batchId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Up to 500 findings and 2,000 coverage entries, 2 MiB. Idempotent: the same batch id with the same bytes answers 200 with the first response (`replayed: true`); different bytes under the same id are 409 `batch_conflict`. A finding that is not valid is rejected on its own and named in `rejected`; coverage that is not valid refuses the whole batch. A result id the assessment already has counts as a duplicate.

## Request body

- BatchRequest
  - `coverage` Coverage[]
    - `check` string, required: A check id, a check group, or a namespace wildcard such as ironfang.wordpress.plugin.*.
    - `outcome` 'completed' | 'failed' | 'skipped', required
    - `resource` object: Omitted for the whole asset.
      - `identifier` string, required
      - `type` string, required
  - `findings` SubmittedFinding[]
    - `check` object, required
      - `category` 'dns' | 'tls' | 'http' | 'email' | 'exposure' | 'technology' | 'discovery' | 'configuration' | 'vulnerability' | 'access_control' | 'authentication' | 'secrets' | 'network' | 'logging' | 'malware' | 'data_protection' | 'other', required: The area a finding is in; the first seven are the External Security Check's.
      - `group` string
      - `id` string, required: Namespaced and permanent; the ironfang. namespace is for Ironfang's own producers.
      - `subcategory` string
      - `title` string, required
      - `version` string
    - `classifications` Classification[]
      - `id` string, required: e.g. CVE-2026-12345, CWE-79, A05:2021, 1.1.1.
      - `scheme` 'cve' | 'cwe' | 'ghsa' | 'osv' | 'owasp_top10' | 'owasp_asvs' | 'capec' | 'mitre_attack' | 'cis' | 'nist_800_53' | 'nist_csf' | 'cyber_essentials' | 'iso27001' | 'pci_dss', required
    - `confidence` 'confirmed' | 'high' | 'medium' | 'low', required: How sure Ironfang is. `low` is presented as "potential".
    - `cvss` Cvss
      - `base_score` number, required
      - `vector` string
      - `version` '2.0' | '3.0' | '3.1' | '4.0', required
    - `description` string
    - `detail` string
    - `evidence` SubmittedEvidence[]
      - `captured_at` string, date-time
      - `content_type` string
      - `data` unknown
      - `kind` 'dns_answer' | 'certificate' | 'tls_handshake' | 'http_response' | 'tcp_connect' | 'service_banner' | 'certificate_transparency' | 'note' | 'http_request' | 'http_headers' | 'file' | 'configuration' | 'package' | 'software_version' | 'kubernetes_object' | 'command_output' | 'matcher' | 'native_result' | 'screenshot', required
      - `label` string, required
      - `sensitivity` 'public' | 'internal' | 'confidential' | 'restricted': public is what the internet sees; restricted is never stored.
      - `sha256` string: Required for local evidence.
      - `size_bytes` integer
      - `storage` 'inline' | 'local'
      - `text` string
    - `identity` object
    - `impact` string
    - `kind` 'issue' | 'hardening' | 'informational' | 'potential_vulnerability'
    - `native` object
      - `check_id` string
      - `metadata` object: At most 8 KiB.
      - `severity` string
      - `version` string
    - `observed_at` string, date-time
    - `references` string[]
    - `remediation` object
      - `action` string
      - `guidance` string
      - `parameters` object
    - `resource` object
      - `identifier` string, required
      - `type` string, required
    - `result_id` string, required: Unique within the assessment.
    - `severity` 'critical' | 'high' | 'medium' | 'low' | 'info', required
    - `summary` string: Required.
  - `protocol_version` 1, required

## Response `200`

The same batch, sent again.

- BatchResponse
  - `accepted` integer, required
  - `assessment` object, required
    - `id` string, uuid, required
    - `results_received` integer, required
    - `status` 'queued' | 'running' | 'completed' | 'partial' | 'failed' | 'cancelled', required
  - `batch_id` string, required
  - `coverage` integer, required
  - `duplicates` integer, required
  - `new` integer, required
  - `rejected` object[], required
    - `field` string, required
    - `index` integer, required
    - `message` string, required
    - `result_id` string, required
  - `reopened` integer, required
  - `replayed` boolean, required
  - `seen` integer, required
  - `warnings` object[], required
    - `index` integer, required
    - `message` string, required
    - `result_id` string, required

## Other responses

- `201`: Accepted.
- `400`: An error.
- `404`: An error.
- `409`: An error.
- `413`: An error.
- `422`: An error.
- `default`: An error.

---

[API](https://skmtc.dev/ironfang/apis/ironfang-security-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-security-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-security-api/revisions/73bd66283d59?raw)