Assessments API

Overview

The Assessments API provides endpoints for managing security assessments throughout their lifecycle. This includes retrieving assessment queues, getting assessment details, updating assessment fields, managing vulnerabilities, and accessing assessment history. All endpoints require authentication via the FACTION-API-KEY header.

Get Assessment Queue

curl -X GET "https://your-faction-instance.com/api/assessments/queue" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves the assessment queue for the authenticated user. Returns all non-completed assessments assigned to the user.

Authentication

FACTION-API-KEY

string

required

API authentication key for the user

Response

Returns an array of AssessmentDTO objects.

long

Assessment ID

name

string

Assessment name

appId

string

Application ID (can span multiple assessments)

start

date

Assessment start date

end

date

Assessment end date

customFields

object

Custom field key-value pairs

Status Codes

200 - Success: Assessor queue returned
401 - Not authorized
500 - Error retrieving assessments

Get Assessment Details

curl -X GET "https://your-faction-instance.com/api/assessments/123" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves full details for a specific assessment by ID, including custom fields.

Path Parameters

aid

long

required

Assessment ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Authorization

User must be:

The assigned assessor
A manager
The engagement contact
The remediation contact

Response

Returns an AssessmentDTO object with complete assessment information.

long

Assessment ID

name

string

Assessment name

notes

string

Assessment notes

summary

string

Assessment summary

distributionList

string

Email distribution list

customFields

object

Custom field key-value pairs for this assessment

Status Codes

200 - Success: Assessment details returned
400 - Assessment does not exist
401 - Not authorized for this assessment
500 - Failed to serialize response

Update Assessment

curl -X POST "https://your-faction-instance.com/api/assessments/123" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "notes=Updated assessment notes" \
  -d "summary=Executive summary" \
  -d 'customFields={"ClientContact":"John Doe","ProjectCode":"PROJ-2024"}'

Updates allowed assessment fields including notes, summary, distribution list, and custom fields.

Path Parameters

aid

long

required

Assessment ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Form Parameters

notes

string

Assessment notes

summary

string

Assessment summary

distributionList

string

Semicolon-delimited distribution list

customFields

string

JSON object with custom field key-value pairs. Keys must match existing custom field definitions for the assessment type.

Custom Fields Format

Custom fields are provided as a JSON object:

{
  "FieldKey1": "Value1",
  "FieldKey2": "Value2"
}

Status Codes

200 - Success: Update successful
400 - Assessment does not exist or locked for peer review
401 - Not authorized

Get Assessment Vulnerabilities

curl -X GET "https://your-faction-instance.com/api/assessments/vulns/123" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves all vulnerabilities for a specific assessment.

Path Parameters

aid

long

required

Assessment ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of VulnerabilityDTO objects.

long

Vulnerability ID

name

string

Vulnerability name

description

string

Vulnerability description (HTML/Markdown)

recommendation

string

Remediation recommendation (HTML/Markdown)

details

string

Exploit details and proof of concept

categoryId

long

Category ID

severityId

integer

Severity level (0-9)

impact

integer

Impact score (0-9)

likelihood

integer

Likelihood score (0-9)

cvssScore

string

CVSS score

cvssString

string

CVSS vector string

customFields

array

Array of custom field objects

Status Codes

200 - Success: Vulnerabilities returned
401 - Not authorized

Add Vulnerability

curl -X POST "https://your-faction-instance.com/api/assessments/addVuln/123" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=SQL Injection" \
  -d "vulnTemplateId=45" \
  -d "description=$(echo 'Vulnerability description' | base64)" \
  -d "details=$(echo 'Exploit steps' | base64)" \
  -d "severity=7" \
  -d "impact=8" \
  -d "likelihood=6" \
  -d 'customFields={"AffectedURL":"https://example.com/login"}'

Creates a new vulnerability for the specified assessment. All Base64 encoded inputs support HTML and Markdown syntax.

Path Parameters

aid

long

required

Assessment ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Form Parameters

name

string

required

Vulnerability name

vulnTemplateId

long

Vulnerability template ID to use as base

description

string

Vulnerability description (Base64 encoded, supports HTML/Markdown)

recommendation

string

Remediation recommendation (Base64 encoded, supports HTML/Markdown)

details

string

Exploit details and proof of concept (Base64 encoded, supports HTML/Markdown)

categoryId

long

Vulnerability category ID

severity

integer

Severity ID (0-9)

impact

integer

Impact score (0-9). Defaults to severity if not provided.

likelihood

integer

Likelihood score (0-9). Defaults to severity if not provided.

cvssScore

string

CVSS score

cvssString

string

CVSS vector string

section

string

Report section (Enterprise feature)

customFields

string

JSON object with custom field key-value pairs

Response

vid

long

ID of the newly created vulnerability

Status Codes

200 - Success: Returns the new vulnerability ID
400 - Bad request (assessment not found, locked for peer review, invalid parameters)
401 - Not authorized

Add Vulnerability from Template

curl -X POST "https://your-faction-instance.com/api/assessments/addDefaultVuln/123/45" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=SQL Injection in Login Form" \
  -d "details=$(echo 'Specific exploit steps for this instance' | base64)" \
  -d "cvssScore=7.5"

Adds a new vulnerability based on an internal database vulnerability template. Auto-populates all non-required fields from the template.

Path Parameters

aid

long

required

Assessment ID

long

required

Vulnerability template ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Form Parameters

name

string

required

Vulnerability name (can override template name)

details

string

Exploit details (Base64 encoded)

severity

integer

Severity override (0-9)

impact

integer

Impact override (0-9)

likelihood

integer

Likelihood override (0-9)

cvssScore

string

CVSS score override

cvssString

string

CVSS string override

section

string

Report section (Enterprise feature)

customFields

string

JSON object with custom field key-value pairs

Status Codes

200 - Success: Vulnerability created
400 - Bad request
401 - Not authorized

Get Assessment History

curl -X GET "https://your-faction-instance.com/api/assessments/history/APP-2024-001" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves vulnerability history for all assessments of a specific application. Application ID is not the same as Assessment ID - an Application ID can span multiple assessments.

Path Parameters

appid

string

required

Application ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of VulnerabilityDTO objects from all assessments for the application.

Status Codes

200 - Success: Vulnerability history returned
401 - Not authorized or no assessment found

Create Assessment

curl -X POST "https://your-faction-instance.com/api/assessments/create" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "appName=Web Application" \
  -d "start=2024-03-01" \
  -d "end=2024-03-15" \
  -d "[email protected];[email protected]" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "type=Web Application" \
  -d "campaign=Q1 2024 Security Assessments" \
  -d "auto_create_campaigns=true" \
  -d "scope=Application scope and credentials"

Creates a new assessment and schedules it to assessor(s). Can auto-create users and teams if they don’t exist in the system.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Engagement or Manager role)

Form Parameters

appid

string

Application ID (links to existing application)

appName

string

required

Application name (required if appid not provided)

start

date

required

Assessment start date (YYYY-MM-DD format)

end

date

required

Assessment end date (YYYY-MM-DD format)

assessors

string

required

Semicolon-delimited list of assessor usernames

distro

string

Semicolon-delimited distribution list

engagement_username

string

required

Engagement contact username

remediation_username

string

required

Remediation contact username

type

string

required

Assessment type (e.g., “Web Application”, “Mobile”, “Network”)

scope

string

Scope and credentials for assessors

campaign

string

required

Campaign name

auto_create_campaigns

boolean

required

Create campaign if it doesn’t exist

Status Codes

200 - Success: Assessment created
400 - Bad request
401 - Not authorized

Get Vulnerability Details

curl -X GET "https://your-faction-instance.com/api/assessments/vuln/456" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves detailed information for a specific vulnerability including exploit steps.

Path Parameters

vid

long

required

Vulnerability ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns a VulnerabilityDTO object with complete vulnerability information including custom fields.

Status Codes

200 - Success: Vulnerability details returned
400 - Vulnerability does not exist
401 - Not authorized

Authorization Requirements

Assessment Queue

Requires: Assessor or Manager role

Get/Update Assessment

Requires one of:
- Manager role
- Assigned assessor
- Engagement contact
- Remediation contact

Create Assessment

Requires: Engagement or Manager role

Add Vulnerabilities

Requires: Assessor or Manager role
Assessment must not be locked for peer review
User must be assigned to the assessment

Notes

Base64 Encoding: Description, recommendation, and details fields accept Base64 encoded content that supports HTML and Markdown syntax.
Peer Review Lock: Assessments locked for peer review cannot be modified until the review is complete.
Custom Fields: Custom field keys must match existing custom field definitions configured for the assessment type.
Application vs Assessment: An Application ID can have multiple assessments over time. Use the history endpoint to retrieve all vulnerabilities across assessments.

Overview

Endpoints

​Overview

​Get Assessment Queue

​Authentication

​Response

​Status Codes

​Get Assessment Details

​Path Parameters

​Authentication

​Authorization

​Response

​Status Codes

​Update Assessment

​Path Parameters

​Authentication

​Form Parameters

​Custom Fields Format

​Status Codes

​Get Assessment Vulnerabilities

​Path Parameters

​Authentication

​Response

​Status Codes

​Add Vulnerability

​Path Parameters

​Authentication

​Form Parameters

​Response

​Status Codes

​Add Vulnerability from Template

​Path Parameters

​Authentication

​Form Parameters

​Status Codes

​Get Assessment History

​Path Parameters

​Authentication

​Response

​Status Codes

​Create Assessment

​Authentication

​Form Parameters

​Status Codes

​Get Vulnerability Details

​Path Parameters

​Authentication

​Response

​Status Codes

​Authorization Requirements

​Assessment Queue

​Get/Update Assessment

​Create Assessment

​Add Vulnerabilities

​Notes

Build docs developers (and LLMs) love

Overview

Get Assessment Queue

Authentication

Response

Status Codes

Get Assessment Details

Path Parameters

Authentication

Authorization

Response

Status Codes

Update Assessment

Path Parameters

Authentication

Form Parameters

Custom Fields Format

Status Codes

Get Assessment Vulnerabilities

Path Parameters

Authentication

Response

Status Codes

Add Vulnerability

Path Parameters

Authentication

Form Parameters

Response

Status Codes

Add Vulnerability from Template

Path Parameters

Authentication

Form Parameters

Status Codes

Get Assessment History

Path Parameters

Authentication

Response

Status Codes

Create Assessment

Authentication

Form Parameters

Status Codes

Get Vulnerability Details

Path Parameters

Authentication

Response

Status Codes

Authorization Requirements

Assessment Queue

Get/Update Assessment

Create Assessment

Add Vulnerabilities

Notes