API docs by Redocly

Ostrich Birdseye API (1.0.0)

Download OpenAPI specification:Download

API for Ostrich Birdseye

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

Request samples

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

Response samples

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

Get Business Units

Retrieves summary info for all business units for the authenticated token

Authorizations:
Bearer

Responses

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 samples

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

Retrieves 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 samples

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

Get Assessments

Retrieves summaries of the assessments for a business unit

Authorizations:
Bearer
path Parameters
businessUnitId
required
string

The ID of the business unit

Responses

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

Responses

Request samples

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

Response samples

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

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 samples

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

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 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)

Responses

Request samples

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

Response samples

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

Archive evidences

Archives 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 evidence ids to archive on the assessment.

required
Array of objects (archiveEvidenceRequest)

Responses

Request samples

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

Response samples

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

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 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)

Responses

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 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)

Responses

Request samples

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

Response samples

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

Get 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 samples

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

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 samples

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

Save Scores

Save scores on as 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 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.

required
Array of objects (saveScoreRequest)

Responses

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)

Responses

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)

Responses

Request samples

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

Response samples

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

Get User

Retrieves the details of a user

Authorizations:
Bearer
path Parameters
userId
required
string

The ID of the user

Responses

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 samples

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

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 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

Responses

Request samples

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

Response samples

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

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 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

Responses

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 samples

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

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 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

Responses

Request samples

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

Response samples

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

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 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

Responses

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 samples

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

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

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"
}

Retrieves 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 samples

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

Retrieves 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 samples

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