API docs by Redocly

Ostrich Birdseye API (1.0.0)

Download OpenAPI specification:

The Birdseye API gives you programmatic access to your cyber risk program: business units, qualitative assessments, and the FAIR scenarios and simulations built on top of them.

Base URLs

Environment Base URL
Production https://api.ostrichcyber-risk.com
Preview https://api.ostrichsecure.com

Authentication

Every endpoint except POST /v1/auth/token requires a bearer token. Exchange your API key for one, then send it on each request. Tokens are short lived, so fetch a new one rather than caching it for long periods.

curl -X POST https://api.ostrichcyber-risk.com/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"apiKey": "YOUR_API_KEY"}'

curl https://api.ostrichcyber-risk.com/v1/businessUnits \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Successful responses share one envelope: a human readable message and a response object holding the payload. Create endpoints return the ID of the object they created.

{
  "message": "Created scenario successfully",
  "response": { "scenarioId": "8f2c1d9e4b7a" }
}

Errors

Birdseye uses conventional HTTP status codes. 401 means the token is missing or expired, 403 means the token is valid but lacks a role on the business unit in the path, and 404 means the object does not exist or is not visible to you.

Business unit scoping

Almost every path is scoped to a businessUnitId. A token only reaches the business units its API key was granted roles on, and roles are inherited by child units in the hierarchy.

Authentication

Exchange a Birdseye API key for a short-lived bearer token. Every other endpoint expects that token in the Authorization header.

Get auth token

Generates a JWT from an API Key

Request Body schema: application/json
required

The API Key to generate a token for

apiKey
required
string

Responses

Response Schema: application/json
message
required
string
required
object
token
required
string
expiresAt
required
string <date-time>

an RFC 3339–formatted timestamp in UTC

Request samples

Content type
application/json
{
  • "apiKey": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Business Units

Business units are the organizational entities every other object hangs off. They form a parent/child hierarchy, and access is granted per unit.

Get business units

Retrieves summary info for all business units for the authenticated token

Authorizations:
Bearer

Responses

Response Schema: application/json
message
required
string
required
object (ApiGetBusinessUnits200ResponseResponse)
required
Array of objects (businessUnitSummary)
Array
businessUnitId
required
string
name
required
string
businessUnits
required
Array of objects (businessUnitSummary)

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Create business unit

Creates a business unit under the specified parent business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the parent business unit to create the new business unit under

Request Body schema: application/json
required

The business unit data to create a business unit with.

required
object
name
required
string
industry
required
string
employeeCount
required
integer
revenue
required
number <double>
scoreScale
required
string (scoreScale)
Enum: "ONE_HUNDRED_POINT" "FIVE_POINT" "FOUR_POINT"
scoreStrategy
required
string
Enum: "aggregate" "override"
targetStrategy
required
string
Enum: "aggregate" "override"
country
string
state
string
city
string
aiOptIn
boolean

Responses

Response Schema: application/json
message
required
string
required
object (ApiCreateBusinessUnitResponse)
businessUnitId
required
string

The ID of the created business unit.

Request samples

Content type
application/json
{
  • "businessUnit": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get business unit

Retrieves the details for a specific business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

Responses

Response Schema: application/json
message
required
string
required
object (apiBusinessUnit)
name
required
string
revenue
required
number <double>
required
object (businessUnitSubscription)
subscriptionType
required
string
renewalDate
required
string
employeeCount
required
integer
required
object
naicsCode
required
number
businessUnitId
required
string
object (businessUnitLocation)
country
required
string
state
required
string
city
required
string
postalCode
required
string
Array of objects
Array
title
required
string
assessmentTypeId
required
string
businessUnitId
required
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Users

Users and the roles that scope what they can read and write on a business unit.

Create user

Create a new user if they do not exist, or add roles for an existing user. At least one role must be included.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string
Request Body schema: application/json
required
email
required
string <email>

The email address of the user to create.

displayName
required
string

The display name of the user.

manager
boolean

Assign the Manager role on the requesting business unit.

delegator
boolean

Assign the Delegator role on the requesting business unit.

object

A map of business unit IDs to booleans, assigning the Practitioner Assessments role on those BUs. This role can only be assigned to leaf business units.

property name*
additional property
boolean
object

A map of business unit IDs to booleans, assigning the Practitioner Reports role on those BUs.

property name*
additional property
boolean
simulator
boolean

Assign the Simulator role on the requesting business unit.

securityAdmin
boolean

Assign the Security Admin role on the requesting business unit.

apiAccess
boolean

Assign the API Access role on the requesting business unit. Requires the Manager role.

expiry
string <date-time>

Optional expiry date for the assigned roles. Must be in the future and within one year.

Responses

Response Schema: application/json
message
required
string
required
object (UserResponse)
displayName
required
string
email
required
string
userId
required
string
required
object
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)

Request samples

Content type
application/json
{
  • "email": "jane.doe@example.com",
  • "displayName": "Jane Doe",
  • "manager": true,
  • "apiAccess": true,
  • "practitionerAssessments": {
    },
  • "practitionerReports": {
    },
  • "expiry": "2026-01-15T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get users on business unit

Retrieves all users with access to the specified business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects
Array
userId
required
string
displayName
required
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Update user roles

Updates user roles for a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit to update user roles on

userId
required
string

The ID of the user to update roles for

Request Body schema: application/json
required

A list of roles to assign or unassign to the user

required
Array of objects (apiUpdateRoleRequest)
Array
roleType
required
string
Enum: "manager" "practitionerReports" "simulator" "securityAdmin" "practitionerAssessments" "delegator" "apiAccess"
assigned
required
boolean

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get user

Retrieves the details of a user. Returned roles will only include business units the authorizing api key is a manager or delegator on.

Authorizations:
Bearer
path Parameters
userId
required
string

The ID of the user

Responses

Response Schema: application/json
message
required
string
required
object (UserResponse)
displayName
required
string
email
required
string
userId
required
string
required
object
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)
Array of objects (role)

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Assessments

Qualitative assessments of a business unit against a framework such as NIST CSF or CRI, plus the question content behind them.

Get assessments

Retrieves summaries of the assessments for a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

query Parameters
after
string

filters the response to only assessments with a last modified date greater than or equal to the passed in timestamp. Expected format is RFC 3339 ex: 2006-01-02T15:04:05.000000000Z07:00

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects (assessmentSummary)
Array
businessUnitId
required
string
businessUnitName
required
string
assessmentId
required
string
assessmentName
required
string
assessmentTypeId
required
string
assessments
required
Array of objects (assessmentSummary)

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Add assessment

Adds a new assessment to a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit to add the assessment to

Request Body schema: application/json
required

The assessment data to create an assessment with. Note that dates need to be formatted exactly as the example shows.

required
object
assessmentName
required
string
assessmentTypeId
required
string
startDate
required
string <date-time>
dueDate
required
string <date-time>
notificationsOn
required
boolean

Responses

Response Schema: application/json
message
required
string
required
object (ApiAddAssessmentResponse)
assessmentId
required
string

The ID of the created assessment.

Request samples

Content type
application/json
{
  • "assessment": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get assessment

Retrieves details of an assessment in a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment to retrieve details of

Responses

Response Schema: application/json
message
required
string
required
object

Returns either a single assessment or a rollup assessment

assessmentId
required
string
assessmentName
required
string
version
required
string
assessmentTypeId
required
string
startDate
string
dueDate
string
closed
boolean
Array of objects (SubAssessment)
Array
assessmentId
required
string
businessUnitId
required
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get assessment content

Retrieves the content for an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Responses

Response Schema: application/json
message
required
string
required
object
businessUnitId
required
string
assessmentId
required
string
assessmentTypeId
required
string
content
required
any

See the custom assessment guide for full schema

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Scores & Targets

Current and target scores for an assessment, and the questions excluded from scoring.

Get scores

Retrieves the results for an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

query Parameters
profileId
string

The ID of the profile to retrieve scores for

controlIds
Array of strings

The given control ids to apply as an adhoc profile to the scores. profileId and controlIds should not both be provided. Example ?controlIds=GV,DE.AE-2,GV.OC

Responses

Response Schema: application/json
message
required
string
required
object
businessUnitId
required
string
assessmentId
required
string
assessmentTypeId
required
string
required
Array of objects (userLabel)
Array
subId
required
string
abbr
required
string
name
required
string
required
Array of objects (userLabel)
Array
subId
required
string
abbr
required
string
name
required
string
profileId
required
string
required
Array of objects (resultScores)
Array
itemId
required
string
aspectTotalAnswerCount
required
number
aspectTotalCount
required
number
questionCount
required
number
required
Array of objects
aspectPercentDone
number

Percent of aspects with at least one answer across all practitioners. Null when no data is available for this control.

percentDone
number

Percent of questions fully answered by every practitioner. Null when no data is available for this control.

percentOfTarget
number

Score as a percent of target. Null when score or target is unavailable.

score
number

Aggregated score for the control. Null when no score data is available.

target
number

Aggregated target for the control. Null when no target data is available.

weight
number

Aggregated weight for the control. Null when no target data is available.

weightLabel
string
ignoredQuestions
required
Array of strings

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Save scores

Save scores on an assessment. Both the api key and associate user must have the "Assessment practitioner" role.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit that owns the assessment

assessmentId
required
string

The ID of the assessment to save scores on

Request Body schema: application/json
required

The list of scores to save to the assessment. Either "score" or "unknown" is required on each score, but both cannot be provided on a single score. If "score" is provided it must be a valid score for the aspect. A valid score for coverage is any multiple of 5 from 0 to 100. For any other aspect the allowed scores are specified in the content type. This can be found via the "Get Assessment Content" route.

required
Array of objects (saveScoreRequest)
Array
aspectId
required
string
score
integer
unknown
boolean

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "scores": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Save targets

Save targets on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit that owns the assessment

assessmentId
required
string

The ID of the assessment to save targets on

Request Body schema: application/json
required

A list of targets to save to the assessment. Needs at least "target" or "weight" defined on each target. Both can be defined.

required
Array of objects (saveTargetRequest)
Array
aspectId
required
string
target
integer
weight
string
Enum: "LOW" "MED-LOW" "MEDIUM" "MED-HIGH" "HIGH"

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Ignore or unignore questions

Sets ignore status on a list of questions

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit to ignore questions on

assessmentTypeId
required
string

The ID of the assessment type used for the questions

Request Body schema: application/json
required

A list of questions to save ignore status on

required
Array of objects (ignoredQuestionRequest)
Array
aspectId
required
string
ignored
required
boolean

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "ignoredQuestions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Notes & Findings

Free-text notes and findings recorded against the aspects of an assessment.

Get findings

Gets findings on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects (getAspectTextMetadataResponse)
Array
aspectId
required
string
value
required
string
modifiedBy
required
string
modifiedAt
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Save findings

Saves findings on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Request Body schema: application/json
required

The list of findings to save to the assessment. Duplicate aspectIds between findings are not allowed.

required
Array of objects (saveAspectTextMetadataRequest)
Array
aspectId
required
string
value
required
string

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "findings": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get notes

Gets notes on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects (getAspectTextMetadataResponse)
Array
aspectId
required
string
value
required
string
modifiedBy
required
string
modifiedAt
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Save notes

Saves notes on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Request Body schema: application/json
required

The list of notes to save to the assessment. Duplicate aspectIds between notes are not allowed.

required
Array of objects (saveAspectTextMetadataRequest)
Array
aspectId
required
string
value
required
string

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "notes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Evidence

Evidence attached to an assessment to support the scores given.

Get evidences

Get evidences for an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects (getEvidenceResponse)
Array
id
required
string
aspectId
required
string
title
required
string
url
required
string
createdBy
required
string
createdAt
required
string
archivedBy
string
archivedAt
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Save evidences

Saves evidences on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Request Body schema: application/json
required

The list of evidences to save to the assessment.

required
Array of objects (saveEvidenceRequest)
Array
aspectId
required
string
title
required
string
url
required
string

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "evidences": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Archive evidence

Archives evidence on an assessment

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

evidenceId
required
string

The evidence id to archive on the assessment.

Responses

Response Schema: application/json
message
required
string

Response samples

Content type
application/json
{
  • "message": "string"
}

Profiles

Profiles select which subset of an assessment type applies to a business unit, including custom profiles you define yourself.

Retrieve all profiles the business unit can view

Gets all profiles the business unit can view

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

Responses

Response Schema: application/json
message
required
string
required
Array of objects (profileWithOrigin)
Array
profileId
required
string
assessmentTypeId
required
string
profileName
required
string
businessUnitOwner
required
string
subcategories
required
Array of strings
threatId
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": [
    ]
}

Create custom profile

Creates a custom profile for the given assessment type on a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string
assessmentTypeId
required
string
Request Body schema: application/json
required
profileName
required
string
threatId
string
subCategories
Array of strings

Responses

Response Schema: application/json
message
required
string
profileId
required
string

Request samples

Content type
application/json
{
  • "profileName": "string",
  • "threatId": "string",
  • "subCategories": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "profileId": "string"
}

Update custom profile

Updates an existing custom profile on a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string
assessmentTypeId
required
string
profileId
required
string
Request Body schema: application/json
required
profileName
required
string
threatId
string
subCategories
Array of strings

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "profileName": "string",
  • "threatId": "string",
  • "subCategories": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get assessment profiles

Retrieves the assessment profiles for a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment

Responses

Response Schema: application/json
message
required
string
required
object
required
Array of objects (profile)
Array
profileId
required
string
assessmentTypeId
required
string
profileName
required
string
subcategories
required
Array of strings
threatId
string
businessUnitId
required
string
assessmentId
required
string
assessmentTypeId
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Compliance Mapping

Unified Compliance Framework (UCF) control mappings for an assessment.

Retrieve matched UCF controls for the given UCF control ID

Retrieves matched UCF controls for the given UCF control id for the selected assessment and business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment to retrieve details of

ucfControlId
required
string

the ID of the matched ucf control

Responses

Response Schema: application/json
message
required
string
response
required
Array of strings

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": [
    ]
}

Retrieve UCF common control IDs for the assessment

Retrieves UCF Common Control Ids for the assessment if they've been generated

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

assessmentId
required
string

The ID of the assessment to retrieve details of

Responses

Response Schema: application/json
message
required
string
required
object (ucfMapping)
generatedAt
required
string <date-time>
generatedBy
required
string
required
Array of objects (mandateControl)
Array
ucfId
required
string
ucfControlId
required
integer
ucfReferenceId
required
string
ostrichControlId
required
string
taggedText
required
string
required
Array of objects (matchedControl)

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Scenario Families

Scenario families group related risk scenarios within a business unit.

Get scenario families

gets all the scenario families in a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

Responses

Response Schema: application/json
message
string
object
Array of objects
Array
scenarioFamilyName
string
scenarioFamilyId
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Create scenario family

Creates a new scenario family in a business unit.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

Request Body schema: application/json
required

The scenario family data to create a scenario family with.

required
object
name
required
string
description
required
string
assessmentId
string
object (scopeCategory)
name
required
string
required
Array of objects (scopeItem)
narrativeJustification
required
string
keyConsiderations
required
string
Array of objects (scenarioScopeNotes)
Array
lexiconPath
string
note
string

Responses

Response Schema: application/json
message
required
string
required
object (ApiCreateScenarioFamilyResponse)
scenarioFamilyId
required
string

The ID of the created scenario family.

Request samples

Content type
application/json
{
  • "scenarioFamily": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get scenario family

gets a specific scenario family

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

scenarioFamilyId
required
string

Unique identifier for the scenario family.

Responses

Response Schema: application/json
message
string
object
scenarioFamilyName
string
scenarioFamilyId
string
description
string
assessmentId
string
Array of objects (scopeCategory)
Array
name
required
string
required
Array of objects (scopeItem)
narrativeJustification
required
string
keyConsiderations
required
string
Array of objects (scenarioScopeNotes)
Array
lexiconPath
string
note
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Update scenario family

Updates the specified scenario family.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family to be updated.

Request Body schema: application/json
required

The scenario family data to update the specified scenario family with.

required
object (updateScenarioFamilyRequestScenarioFamily)
name
string
description
string
object (scopeCategory)
name
required
string
required
Array of objects (scopeItem)
narrativeJustification
required
string
keyConsiderations
required
string
Array of objects (scenarioScopeNotes)
Array
lexiconPath
string
note
string

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "scenarioFamily": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete scenario family

Deletes the specified scenario family.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family to be deleted.

Responses

Response Schema: application/json
message
required
string

Response samples

Content type
application/json
{
  • "message": "string"
}

Scenarios

A scenario is a FAIR risk model for one threat event, holding the frequency and magnitude factors used by the simulation.

Get scenarios

gets all the scenarios in a scenario family

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

scenarioFamilyId
required
string

Unique identifier for the scenario family.

Responses

Response Schema: application/json
message
string
object
Array of objects
Array
scenarioName
string
scenarioId
string

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Create scenario

Creates a new scenario in the specified scenario family.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family to add the scenario to.

Request Body schema: application/json
required

Supported Factors

  • PriLM - Primary Loss Magnitude, The primary loss magnitude for the event.
  • PriCA - Primary Event Loss for Competitive Advantage, The primary loss magnitude for the event.
  • PriPRO - Primary Event Loss for Productivity, The primary loss magnitude for the event.
  • PriRES - Primary Event Loss for Response, The primary loss magnitude for the event.
  • PriFAJ - Primary Event Loss for Fines and Judgements, The primary loss magnitude for the event.
  • PriREP - Primary Event Loss for Reputation, The primary loss magnitude for the event.
  • PriRPL - Primary Event Loss for Replacement, The primary loss magnitude for the event.
  • SecLM - Secondary Loss Magnitude, The monetary losses when other stakeholders become aware of the primary loss.
  • SecCA - Secondary Event Loss for Competitive Advantage, The monetary losses when other stakeholders become aware of the primary loss.
  • SecPRO - Secondary Event Loss for Productivity, The monetary losses when other stakeholders become aware of the primary loss.
  • SecRES - Secondary Event Loss for Response, The monetary losses when other stakeholders become aware of the primary loss.
  • SecFAJ - Secondary Event Loss for Fines and Judgements, The monetary losses when other stakeholders become aware of the primary loss.
  • SecREP - Secondary Event Loss for Reputation, The monetary losses when other stakeholders become aware of the primary loss.
  • SecRPL - Secondary Event Loss for Replacement, The monetary losses when other stakeholders become aware of the primary loss.
  • TEF - Threat Event Frequency, The probable frequency that a threat agent will act against an asset within a given timeframe.
  • LEF - Loss Event Frequency, The probable frequency that a threat action will result in loss within a given timeframe.
  • Suscep - Susceptibility, The probability that a threat event will become a loss event.
  • TC - Threat Capability, The probable level of force that a threat agent is capable of applying against an asset.
  • SecLEF - Secondary Event Frequency, The probable frequency that secondary loss will occur.
  • AP - Action Probability, The probability that a threat agent will act once contact occurs.
  • CF - Contact Frequency, The frequency with which the attacker comes in contact with an asset.
  • RS - Resistance Strength, The strength of a control as compared to a baseline unit of force.

Supported Factor Combinations

  • (Required) LEF
    • TEF and Suscep may be used instead of LEF
      • AP and CF may be used instead of TEF
      • TC and RS may be used instead of Suscep
  • (Required) PriLM
    • One or more of the 6 primary event loss sub factors may be used instead of PriLM
  • (Optional) SecLEF and SecLM
    • One or more of the 6 secondary event loss sub factors may be used instead of SecLM

Supported Probability Distributions

  • BetaPERT - min, mode, max, lambda
  • Lognormal - sigma (0-25), mu (0-25, -7 to 25 for SecLEF)
  • Normal - mu, sigma
  • Poisson - mu
  • Poisson Lognormal - sigma (0-23), mu (-7 to 16)
required
object
scenarioName
required
string
required
Array of objects (factor)
Array
index
integer
lambda
number
mu
number
name
string
probabilityDistribution
string (factorProbabilityDistribution)
Enum: "BetaPERT" "Lognormal" "Normal" "Poisson" "Poisson Lognormal" "LogBetaPERT"
shortName
string
nameWithUnits
string
sigma
number
units
string
description
string
min
number
max
number
mode
number
comment
string
lossMagnitudeOption
string
enabled
boolean
object

The suggested factor object can be one of four objects depending on the type of factor.

  • Loss Event Frequency (LEF) factors
    frequencyPreset: "Attack Vector: Malware"
  • Threat Event Frequency (TEF) factors
    frequencyPreset: "Industry Type: Health Care and Social Assistance"
actorType: "Actor Type: Internal - Consultant"
  • Loss Magnitude (LM) factors
    magnitudePreset: "Industry Type: Financial Services"
  • Susceptibility Assessment factors
    susceptibilityAssessment: "NIST CSF 2"
susceptibilityProfile: "Cloud Product Compromise"
useTargetScores: "assessment"
effect
string
threat
string
asset
string
scenarioPurpose
string
scenarioNarrativeAndDetail
string

Responses

Response Schema: application/json
message
required
string
required
object (ApiCreateScenarioResponse)
scenarioId
required
string

The ID of the created scenario.

Request samples

Content type
application/json
{
  • "scenario": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Get scenario

gets a specific scenario

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

scenarioFamilyId
required
string

Unique identifier for the scenario family.

scenarioId
required
string

Unique identifier for the scenario.

Responses

Response Schema: application/json
message
string
object
object (lastRun)
object (simulationResults)
object (runSimulationParameters)
Array of objects (factorStatistic)
lastRunTime
string <date-time>
userId
string
lastSavedAt
string <date-time>
lastModifiedUserId
string
object
Array of objects (scopeCategory)
Array of objects (scenarioScopeNotes)
scenarioFamilyId
string
effect
string
threat
string
asset
string
scenarioPurpose
string
scenarioNarrativeAndDetail
string
id
string
scenarioName
string
Array of objects (factor)
Array
index
integer
lambda
number
mu
number
name
string
probabilityDistribution
string (factorProbabilityDistribution)
Enum: "BetaPERT" "Lognormal" "Normal" "Poisson" "Poisson Lognormal" "LogBetaPERT"
shortName
string
nameWithUnits
string
sigma
number
units
string
description
string
min
number
max
number
mode
number
comment
string
lossMagnitudeOption
string
enabled
boolean
object

The suggested factor object can be one of four objects depending on the type of factor.

  • Loss Event Frequency (LEF) factors
    frequencyPreset: "Attack Vector: Malware"
  • Threat Event Frequency (TEF) factors
    frequencyPreset: "Industry Type: Health Care and Social Assistance"
actorType: "Actor Type: Internal - Consultant"
  • Loss Magnitude (LM) factors
    magnitudePreset: "Industry Type: Financial Services"
  • Susceptibility Assessment factors
    susceptibilityAssessment: "NIST CSF 2"
susceptibilityProfile: "Cloud Product Compromise"
useTargetScores: "assessment"

Response samples

Content type
application/json
{
  • "message": "string",
  • "response": {
    }
}

Update scenario

Updates the specified scenario.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family the updated scenario exists in.

scenarioId
required
string

The ID of the scenario to be updated.

Request Body schema: application/json
required

Supported Factors

  • PriLM - Primary Loss Magnitude, The primary loss magnitude for the event.
  • PriCA - Primary Event Loss for Competitive Advantage, The primary loss magnitude for the event.
  • PriPRO - Primary Event Loss for Productivity, The primary loss magnitude for the event.
  • PriRES - Primary Event Loss for Response, The primary loss magnitude for the event.
  • PriFAJ - Primary Event Loss for Fines and Judgements, The primary loss magnitude for the event.
  • PriREP - Primary Event Loss for Reputation, The primary loss magnitude for the event.
  • PriRPL - Primary Event Loss for Replacement, The primary loss magnitude for the event.
  • SecLM - Secondary Loss Magnitude, The monetary losses when other stakeholders become aware of the primary loss.
  • SecCA - Secondary Event Loss for Competitive Advantage, The monetary losses when other stakeholders become aware of the primary loss.
  • SecPRO - Secondary Event Loss for Productivity, The monetary losses when other stakeholders become aware of the primary loss.
  • SecRES - Secondary Event Loss for Response, The monetary losses when other stakeholders become aware of the primary loss.
  • SecFAJ - Secondary Event Loss for Fines and Judgements, The monetary losses when other stakeholders become aware of the primary loss.
  • SecREP - Secondary Event Loss for Reputation, The monetary losses when other stakeholders become aware of the primary loss.
  • SecRPL - Secondary Event Loss for Replacement, The monetary losses when other stakeholders become aware of the primary loss.
  • TEF - Threat Event Frequency, The probable frequency that a threat agent will act against an asset within a given timeframe.
  • LEF - Loss Event Frequency, The probable frequency that a threat action will result in loss within a given timeframe.
  • Suscep - Susceptibility, The probability that a threat event will become a loss event.
  • TC - Threat Capability, The probable level of force that a threat agent is capable of applying against an asset.
  • SecLEF - Secondary Event Frequency, The probable frequency that secondary loss will occur.
  • AP - Action Probability, The probability that a threat agent will act once contact occurs.
  • CF - Contact Frequency, The frequency with which the attacker comes in contact with an asset.
  • RS - Resistance Strength, The strength of a control as compared to a baseline unit of force.

Supported Factor Combinations

  • (Required) LEF
    • TEF and Suscep may be used instead of LEF
      • AP and CF may be used instead of TEF
      • TC and RS may be used instead of Suscep
  • (Required) PriLM
    • One or more of the 6 primary event loss sub factors may be used instead of PriLM
  • (Optional) SecLEF and SecLM
    • One or more of the 6 secondary event loss sub factors may be used instead of SecLM

Supported Probability Distributions

  • BetaPERT - min, mode, max, lambda
  • Lognormal - sigma (0-25), mu (0-25, -7 to 25 for SecLEF)
  • Normal - mu, sigma
  • Poisson - mu
  • Poisson Lognormal - sigma (0-23), mu (-7 to 16)
required
object
scenarioName
string
Array of objects (factor)
Array
index
integer
lambda
number
mu
number
name
string
probabilityDistribution
string (factorProbabilityDistribution)
Enum: "BetaPERT" "Lognormal" "Normal" "Poisson" "Poisson Lognormal" "LogBetaPERT"
shortName
string
nameWithUnits
string
sigma
number
units
string
description
string
min
number
max
number
mode
number
comment
string
lossMagnitudeOption
string
enabled
boolean
object

The suggested factor object can be one of four objects depending on the type of factor.

  • Loss Event Frequency (LEF) factors
    frequencyPreset: "Attack Vector: Malware"
  • Threat Event Frequency (TEF) factors
    frequencyPreset: "Industry Type: Health Care and Social Assistance"
actorType: "Actor Type: Internal - Consultant"
  • Loss Magnitude (LM) factors
    magnitudePreset: "Industry Type: Financial Services"
  • Susceptibility Assessment factors
    susceptibilityAssessment: "NIST CSF 2"
susceptibilityProfile: "Cloud Product Compromise"
useTargetScores: "assessment"
effect
string
threat
string
asset
string
scenarioPurpose
string
scenarioNarrativeAndDetail
string

Responses

Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "scenario": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete scenario

Deletes the specified scenario.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family to delete the scenario from.

scenarioId
required
string

The ID of the scenario to be deleted.

Responses

Response Schema: application/json
message
required
string

Response samples

Content type
application/json
{
  • "message": "string"
}

Simulation

Run a Monte Carlo simulation over a scenario to produce its annualized loss expectancy.

Run simulation

Runs a simulation for the specified scenario.

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit.

scenarioFamilyId
required
string

The ID of the scenario family the scenario exists in.

scenarioId
required
string

The ID of the scenario to run the simulation for.

Request Body schema: application/json
required

The request to run a simulation, includes the number of random samples to run. Accepted values for numSamples are 1000, 5000, 10000, 50000, and 100000

numSamples
integer
Enum: 1000 5000 10000 50000 100000

The number of random samples for simulation.

Responses

Response Schema: application/json
object (simulationResults)
minALE
number <float>
aveALE
number <float>
maxALE
number <float>
modeALE
number <float>
Array of objects (simulationPercentile)
Array
percentile
number
loss
number <float>
object (runSimulationParameters)
scenarioName
string
businessUnitId
string
sampleCount
integer
Array of objects (factor)
Array
index
integer
lambda
number
mu
number
name
string
probabilityDistribution
string (factorProbabilityDistribution)
Enum: "BetaPERT" "Lognormal" "Normal" "Poisson" "Poisson Lognormal" "LogBetaPERT"
shortName
string
nameWithUnits
string
sigma
number
units
string
description
string
min
number
max
number
mode
number
comment
string
lossMagnitudeOption
string
enabled
boolean
object

The suggested factor object can be one of four objects depending on the type of factor.

  • Loss Event Frequency (LEF) factors
    frequencyPreset: "Attack Vector: Malware"
  • Threat Event Frequency (TEF) factors
    frequencyPreset: "Industry Type: Health Care and Social Assistance"
actorType: "Actor Type: Internal - Consultant"
  • Loss Magnitude (LM) factors
    magnitudePreset: "Industry Type: Financial Services"
  • Susceptibility Assessment factors
    susceptibilityAssessment: "NIST CSF 2"
susceptibilityProfile: "Cloud Product Compromise"
useTargetScores: "assessment"
Array of objects (factorStatistic)
Array
factorName
string
min
number <float>
ave
number <float>
max
number <float>
mode
number <float>
Array of objects (simulationPercentile)
lastRunTime
string <date-time>
userId
string

Request samples

Content type
application/json
{
  • "numSamples": 1000
}

Response samples

Content type
application/json
{
  • "simulationResults": {
    },
  • "runSimulationParameters": {
    },
  • "factorStatistics": [
    ],
  • "lastRunTime": "2019-08-24T14:15:22Z",
  • "userId": "66c55a49-1d1d-494e-8c39-12b70fceb1dd"
}