---
title: "Start an assessment"
method: POST
path: "/v1/assessments"
tags: ["Assessments"]
---

# Start an assessment

`POST /v1/assessments`

## Request

- Base URL: `https://api.ironfang.com/security`
- URL: `https://api.ironfang.com/security/v1/assessments`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Starts one collection run by one producer against one asset. The asset is named by id, or by type and name (created, with its parents, when it does not exist). With a `client_reference` the call is idempotent: the same reference answers 200 with the same assessment. An assessment not completed within 24 hours fails and resolves nothing.

## Request body

- StartAssessmentRequest
  - `asset` AssetReference, required: An asset by id, or by type and name (created with its parents when it does not exist).
    - `id` string, uuid
    - `name` string
    - `parent` AssetReference (recursive)
    - `type` 'domain' | 'hostname' | 'ip_address' | 'service' | 'website' | 'host' | 'virtual_machine' | 'container' | 'container_image' | 'kubernetes_cluster' | 'kubernetes_namespace' | 'cloud_account' | 'wordpress_installation' | 'repository' | 'application' | 'api'
  - `client_reference` string: The producer's id for this run; use a UUID.
  - `protocol_version` 1, required
  - `source` SourceReference, required
    - `instance` string: The registered producer's instance id.
    - `name` string
    - `type` 'external_scan' | 'wordpress_agent' | 'linux_agent' | 'kubernetes_agent' | 'container_scanner' | 'cloud_integration' | 'dependency_scanner' | 'ai_assessment' | 'nuclei' | 'import' | 'manual', required: What kind of producer a result came from. external_scan is the External Security Check and cannot be submitted.
    - `version` string, required: The producer's release version, unrelated to the protocol's.
  - `started_at` string, date-time

## Response `200`

Already started with this client_reference.

- Assessment
  - `asset` AssetRef, required
    - `id` string, uuid, required
    - `name` string, required
    - `type` 'domain' | 'hostname' | 'ip_address' | 'service' | 'website' | 'host' | 'virtual_machine' | 'container' | 'container_image' | 'kubernetes_cluster' | 'kubernetes_namespace' | 'cloud_account' | 'wordpress_installation' | 'repository' | 'application' | 'api', required
  - `batches_received` integer, required
  - `checks` object
    - `attempted` integer, required
    - `completed` integer, required
    - `failed` integer, required
  - `client_reference` string
  - `completed_at` string, date-time
  - `created_at` string, date-time, required
  - `expires_at` string, date-time: While open, when it fails if not completed.
  - `findings` object, required
    - `new` integer, required
    - `observed` integer, required
    - `reopened` integer, required
    - `resolved` integer, required
  - `id` string, uuid, required
  - `protocol_version` integer, required
  - `results_received` integer, required
  - `scan_id` string, uuid: The External Security Check this assessment is.
  - `source` object, required
    - `instance` string
    - `name` string, required
    - `type` 'external_scan' | 'wordpress_agent' | 'linux_agent' | 'kubernetes_agent' | 'container_scanner' | 'cloud_integration' | 'dependency_scanner' | 'ai_assessment' | 'nuclei' | 'import' | 'manual', required: What kind of producer a result came from. external_scan is the External Security Check and cannot be submitted.
    - `version` string, required
  - `started_at` string, date-time
  - `status` 'queued' | 'running' | 'completed' | 'partial' | 'failed' | 'cancelled', required
  - `status_reason` string

## Other responses

- `201`: Started.
- `409`: An error.
- `422`: An error.
- `429`: 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)