API docs by Redocly

Guardian API (v2)

Download OpenAPI specification:Download

License: Guardian Terms and Conditions

For information on using the API, please refer to our guide on Using the API.

Accounts

Index

This method returns a list of organization accounts that the provided user is a member of.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
user_id
required
integer

The User ID that belongs under the organization(s).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change Report

Index

This method allows you to retrieve a detailed change report for your organization.

path Parameters
format
required
string
Enum: "csv" "json"

The output format of the response.

query Parameters
weeks
integer
Default: 1

The time span, in weeks, from which to retrieve changes from now.

environment_id
integer
Example: environment_id=1

The environment to retrieve changes for.

node_group_id
integer
Example: node_group_id=1

The node group to retrieve changes for

node_id
int
Example: node_id=1

The node to retrieve changes for

date_from
date
Example: date_from=2012-01-13

Start date to retrieve changes (ISO 8601 format)

date_to
date
Example: date_to=2012-01-13

End date to retrieve changes (ISO 8601 format)

show_ignored
bool
Default: false

Whether or not to include ignored items.

limit
integer
Default: 4000

The number of entries to return. If used with 'page', the number of entries to return per page.

page
integer
Default: 0

Allows pagination of a report, with ‘limit’ controlling the number of records per page.

Responses

Response samples

Content type
{
  • "diff_counts": [
    ],
  • "diff_items": [
    ]
}

Aggregate

This method allows you to receive a CSV report of changes aggregated by node. Each node with changes has an individual entry in the CSV, with fields summarizing the old and new values of its attributes.

path Parameters
format
required
string
Value: "csv"

The output format of the response.

query Parameters
environment_id
integer
Example: environment_id=1

The environment to retrieve changes for.

node_group_id
integer
Example: node_group_id=2

The node group to retrieve changes for.

node_id
integer
Example: node_id=3

The node to retrieve changes for.

date_from
datetime
Default: "1 week ago"
Example: date_from=2014-01-01

Start date to retrieve changes (ISO 8601 format).

date_to
datetime
Default: "now"
Example: date_to=2014-03-31

End date to retrieve changes (ISO 8601 format).

show_ignored
boolean
Default: false
Example: show_ignored=true

Whether or not to include ignored items.

limit
integer
Default: 4000
Example: limit=4000

The number of change records to return on each call.

page
integer
Default: 0
Example: page=1

Allows pagination of a report, with ‘limit’ controlling the number of records per page and is zero indexed.

Responses

Response samples

Content type
text/csv
"ID","Node","Old_Summary","New_Summary"
"1","node02","[{""id"":1,""name"":""agent_version"",...}]","[...]"
"2","node04","[{""id"":2,""name"":""agent_version"",...}]","[...]"

Change Requests

Index

This method allows you to retrieve a list of change requests for your organization. For data to exist, you must have established a ServiceNow Integration.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Show

This method returns details of the change request specified by the change request ID in the URL. The data returned for this change request record is retrieved from ServiceNow records.

path Parameters
format
required
string
Value: "json"

The output format of the response.

change_request_id
required
integer

The ID of the change request.

Responses

Response samples

Content type
application/json
{}

CIS Benchmarks

Index

This method returns a list of the latest CIS benchmark results for your organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method returns CIS benchmark results, filtered by a particular CIS Benchmark determined by the cis_benchmark_id.

path Parameters
format
required
string
Value: "json"

The output format of the response.

cis_benchmark_id
required
integer

The ID of the CIS Benchmark.

query Parameters
environment_id
integer

Filter results by nodes in the environment specified by this Environment ID.

node_group_id
integer

Filter results by nodes in the node group specified by this Node Group ID.

node_id
integer

Filter results for the node specified by the Node ID.

timespan
integer

Limit results to only include those that occurred within this number of weeks back from today.

page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "specific": false,
  • "benchmark": {
    }
}

Benchmarks

This method returns active CIS benchmarks. Active benchmarks are those that are the most recent and have not been superseded.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
active_only
boolean
Default: true

Set this to false to return only active CIS benchmarks, not superseded ones.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Benchmark Result Summary

This method returns a summary of all the CIS benchmark results that are active for the specified time period.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
timespan
integer

Limit results to only include those that occurred within this number of weeks back from today.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Benchmark Results

This method returns the CIS benchmark results that are active for the specified node group, environment or node id. Note that you must provide exactly one of either environment_id, node_group_id or node_id. Combinations are not allowed.

path Parameters
format
required
string
Enum: "csv" "json"

The output format of the response.

cis_benchmark_id
required
integer

The ID of the CIS Benchmark.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

environment_id
integer

Filter results by nodes in the environment specified by this Environment ID.

node_group_id
integer

Filter results by nodes in the node group specified by this Node Group ID.

node_id
integer

Filter results for the node specified by the Node ID.

date_from
string

Filter to only show results after the given timestamp. If omitted, all results back to the first will be included.

date_to
string

Filter to only show results before the given timestamp. If omitted, results will be given up to the present time.

Responses

Response samples

Content type
[
  • {
    }
]

Benchmark Rules

This method returns a list of CIS benchmark rules that correspond to a given benchmark ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
benchmark_id
required
string
Example: benchmark_id=xccdf_org.cisecurity.benchmarks_rule_1.1.1_L1_Set_Enforce_password_history_to_24_or_more_passwords

The Benchmark ID to retrieve rules for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Connection Managers

Index

This method returns a list of connection managers within the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Connection Manager Groups

Index

This method returns a list of connection manager groups within the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method creates a new connection manager group and returns its ID, name, and the API key used for registering connection managers in the newly created group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
name
required
string

The desired name of the connection manager group to be created

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Windows Connection Managers",
  • "api_key": "12345667890125018190284sixtyfourcharacterlongapikey1259181721234"
}

Show

This method returns details of the connection manager group specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

connection_manager_group_id
required
integer

The ID of the connection manager group.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2016-04-13T11:27:09-07:00",
  • "id": 1,
  • "name": "Windows Connection Managers",
  • "organisation_id": 2,
  • "ssh_public_key": "ssh-rsa AAAA....xyz guardian",
  • "status": 1,
  • "updated_at": "2017-03-16T22:19:53-07:00"
}

Delayed Jobs

Index

This method returns a list of delayed jobs for the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

search
string

The search query to use in the format column_name = search value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method returns details of the delayed job specified by a given ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

delayed_job_id
required
integer

The ID of the job.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "priority": 22,
  • "attempts": 3,
  • "handler": "generate_report",
  • "run_at": "2012-10-30T16:16:52-07:00",
  • "created_at": "2012-10-30T16:16:52-07:00",
  • "updated_at": "2012-10-30T16:16:57-07:00",
  • "last_error": "Appliance not ready"
}

Destroy

This method allows you to delete a delayed job.

path Parameters
format
required
string
Value: "json"

The output format of the response.

delayed_job_id
required
integer

The ID of the job.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy All

This method allows you to delete all delayed jobs or those matching a search query.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
search
string

The search query to use in the format column_name = search value.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Diffs

Index

This method allows you to retrieve a list of node scan item diffs for your organization.

path Parameters
format
required
string
Enum: "csv" "json"

The output format of the response.

query Parameters
environment_id
integer
Example: environment_id=1

The ID of the environment to retrieve diffs for.

node_group_id
integer
Example: node_group_id=1

The ID of the node group to retrieve diffs for.

node_id
integer
Example: node_id=1

The ID of the node to receive diffs for.

date_from
datetime
Example: date_from=2018-07-07 12:34:56

If specified, only retrieve difference data at or after this date, otherwise retrieve all data back to the first recorded difference.

date_to
datetime
Example: date_to=2018-07-07 12:34:56

If specified, only retrieve difference data at or before this date, otherwise retrieve all data up until the present time.

include_ignored
boolean
Default: false

Whether or not to include ignored items.

page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 500

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "diff_items_count": 2,
  • "ignored_items_count": 1,
  • "total_items_count": 3,
  • "diff_items": [
    ],
  • "ignored_items": [
    ]
}

Environments

New

This method returns a skeleton payload format that can subsequently be submitted to create a new environment.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "name": null,
  • "short_description": null,
  • "node_rules": null
}

Index

This method returns a list of environments created by the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create a new environment.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object (EnvironmentWithoutId)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 123,
  • "organisation_id": 2,
  • "name": "Production",
  • "short_description": "string",
  • "description": "string",
  • "updated_by": 0,
  • "created_by": 0,
  • "updated_at": null,
  • "created_at": null,
  • "node_rules": "string",
  • "weight": 0
}

Show

This method returns the details of the environment specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

environment_id
required
integer

The ID of the environment.

Responses

Response samples

Content type
application/json
{
  • "id": 30,
  • "organisation_id": 123,
  • "name": "Production",
  • "short_description": "ForEx Trading Production",
  • "node_rules": "",
  • "created_by": 1,
  • "updated_by": 2,
  • "created_at": null,
  • "updated_at": null
}

Update

This method allows you to update properties of an environment.

path Parameters
format
required
string
Value: "json"

The output format of the response.

environment_id
required
integer

The ID of the environment.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete an environment from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

environment_id
required
integer

The ID of the environment.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Look Up

This method allows you to lookup the Environment ID by name.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
name
required
string

The name of the environment.

Responses

Response samples

Content type
application/json
{
  • "environment_id": 123
}

Nodes

This method allows you to list all nodes within an environment.

path Parameters
format
required
string
Value: "json"

The output format of the response.

environment_id
required
integer

The ID of the environment.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Report

This method allows you to retrieve the last scheduled scan report for the environment (i.e. the data you get sent by email showing added/removed/changed counts).

path Parameters
format
required
string
Value: "json"

The output format of the response.

environment_id
required
integer

The ID of the environment.

Responses

Response samples

Content type
application/json
{
  • "date": "2014-04-15T00:08:02-07:00",
  • "dashboard": "https://app.cloudhouse.com/dashboard?env=6",
  • "user_tasks": "https://app.cloudhouse.com/user_tasks",
  • "report": {
    }
}

Event Actions

New

This method returns a skeleton payload format that can subsequently be submitted to create a new event action.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Send Email",
  • "action_type": 2,
  • "variables": {
    },
  • "event_view_id": 0
}

Index

This method allows you to extract events from views, or using an ad hoc query.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create a new event action.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Send Email",
  • "action_type": 2,
  • "variables": {
    },
  • "event_view_id": 0,
  • "updated_by": 178,
  • "created_by": 178,
  • "updated_at": "2012-10-30T16:16:57-07:00",
  • "created_at": "2012-10-30T16:16:52-07:00"
}

Show

This method returns the details of the event action specified by the ID given in the URL.

path Parameters
event_action_id
required
integer

The ID of the event action.

format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Send Email",
  • "status": "enabled",
  • "type": "slack",
  • "variables": {
    },
  • "view": "User Logins."
}

Update

This method allows you to update properties of an Event Action.

path Parameters
format
required
string
Value: "json"

The output format of the response.

event_action_id
required
integer

The ID of the event action.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete an event action from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

event_action_id
required
integer

The ID of the event action.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Event Views

New

This method returns a skeleton payload format that can subsequently be submitted to create a new event view.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "User Logins",
  • "query": "type=User Logged In",
  • "view_type": 2
}

Index

This method returns a list of the available event views.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create a new event view. Note that you cannot create a Global Event View.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "User Logins",
  • "query": "type=User Logged In",
  • "view_type": 2,
  • "updated_by": 178,
  • "created_by": 178,
  • "updated_at": "2012-10-30T16:16:57-07:00",
  • "created_at": "2012-10-30T16:16:52-07:00"
}

Show

This method returns the details of the event view specified by the ID given in the URL.

path Parameters
event_view_id
required
integer

The ID of the event view.

format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "User Logins",
  • "query": "type=User Logged In",
  • "view_type": 2
}

Update

This method allows you to update properties of an Event View. Note that Global Event Views cannot be updated.

path Parameters
format
required
string
Value: "json"

The output format of the response.

event_view_id
required
integer

The ID of the event view.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete an event view from your account. Note that Global Event Views cannot be deleted.

path Parameters
format
required
string
Value: "json"

The output format of the response.

event_view_id
required
integer

The ID of the event view.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Events

Index

This method allows you to extract events from views, or using an ad hoc query. You must specify either view_name or query.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
view_name
string

Name of the event view you’d like to extract events from. (At least either view_name or query must be provided).

query
string

Query you’d like to use to extract events. (At least either view_name or query must be provided).

date_from
datetime

Start date to retrieve events from.

date_to
datetime

End date to retrieve events until.

last_event_id
integer

When making multiple requests you can ensure you do not retrieve the same event twice by specifying this value (request will only retrieve events with an event ID higher than this value).

helper_variables
string
Example: helper_variables=node_scan_url,node_id,success

Comma delimited list of helper variables you would like included in the returned data. This can only be used with the view_name parameter rather than the query parameter. Some common variables are 'job_id', 'node', 'node_id', 'node_type', 'scheduled', 'status', 'success'.

email
string
Example: email=me@example.com

Results can be generated offline and then emailed on completion. If this option is used then report_format is also required.

report_format
string
Enum: "csv" "json"
Example: report_format=csv

When using the email option then a report_format is also required.

page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 500

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create an “External Event” within Guardian, containing custom information.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
user_id
integer
Example: user_id=1

An ID representing a user within Guardian to associate with the event.

node_id
integer
Example: node_id=1

An ID representing a node within Guardian.

ip_address
string
Example: ip_address=1.2.4.5

An IP representing the device associated with the event.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "associated_id": 1,
  • "associated_type": "string",
  • "audit_id": 0,
  • "auditable_id": 0,
  • "auditable_type": "string",
  • "created_at": "2016-07-07 12:34:56",
  • "environment_id": 0,
  • "id": 11854346,
  • "metric_type_id": 1000024,
  • "node_groups": "string",
  • "organisation_id": 0,
  • "source_system": "string",
  • "user_id": 43,
  • "variables": "{\"type\":\"ssh_login\"}"
}

Types

This method allows you to extract event types (use to get event type names from type IDs returned by index).

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Events (Legacy)

Create

This method allows you to create new events that will display on the timeline.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Show

This method returns details of the legacy event, specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

event_id
required
integer

The ID of the legacy event.

Responses

Response samples

Content type
application/json
{
  • "organisation_id": 123,
  • "sub_categoery": "build process",
  • "action_taken": "started",
  • "status": 0,
  • "extra": "Process started successfully"
}

Ignore

Index

This method allows you to look up all Ignore items on a node group or individual node. You must specify either 'node_group_id' or 'node_id'.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_group_id
integer
Example: node_group_id=1

If selecting ignores for a particular node group, the node group's ID.

node_id
integer
Example: node_id=2

If selecting ignores for a particular node, the node's ID.

category
integer
Default: 1
Enum: 1 3

1 for node group ignore list, 3 for node group diff ignore list. Only used with the 'node_group_id' parameter.

Responses

Response samples

Content type
application/json
Example
{ }

Create

This method allows you to create Ignore items for a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_group_id
required
integer

Creates an ignore item for an entire node group.

category
integer
Default: 1
Enum: 1 3
  • `1` for node group ignore list
  • `3` for node group diff ignore list
Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

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

Incidents

Index

This method allows you to retrieve a list of incidents for your organization. For data to exist, you must have established a ServiceNow Integration.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Show

This method returns details of the incident specified by the incident ID in the URL. The data returned for this incident record is retrieved from ServiceNow records.

path Parameters
format
required
string
Value: "json"

The output format of the response.

incident_id
required
integer

The ID of the incident.

Responses

Response samples

Content type
application/json
{}

Integrations

Index

This method returns a list of all integrations in an organization. The selected organization is determined by the API key and secret specified in the Authorization header.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Batch Delete

This method deletes one or more integrations.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
ids
Array of arrays (ids)

An array containing the IDs of the integrations to be deleted.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "1 item deleted"
}

Batch Create

This method creates one or more integrations.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
Array
Any of
name
string
category
integer
settings
object (settings_ad)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Definitions

This method returns a list of all supported integration types and their associated IDs.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Jobs

Index

This method returns a list of jobs for the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to initiate and execute a new job. Depending on the type a different type of job can be initiated.

Type: Node

This method kicks off a delayed job to check all CIS benchmarks that are currently linked to the specified node through its node group. If the specified node has no CIS benchmarks assigned, the job will not be created, and will return a 400 status code.

Type: Node Group

This method kicks off a delayed job to check all CIS benchmarks that are currently linked to the specified node group. If the specified node group has no CIS benchmarks linked, the job will not be created, and will return a 400 status code.

Type: Environment

This method kicks off a delayed job to check all CIS benchmarks that are currently linked to the specified environment. If the specified environment has no CIS benchmarks linked, the job will not be created, and will return a 400 status code.

Type: Node Scan

This method kicks off a job to scan the specified node. After the scan is complete, it also checks all custom policies that are currently linked to the specified node through its node group and executes them on the resulting scan.

Type: Node Group Node Scan

This method kicks off a job to scan the specified node group if there are less than 15 nodes in the node group, and a delayed job otherwise. It also checks all custom policies that are currently linked to the specified node group and executes them post scan.

Type: Environment Node Scan

This method kicks off a job to scan the specified environment if there are less than 15 nodes in the environment, and a delayed job otherwise. It also checks all custom policies that are currently linked to the specified nodes in the environment and executes them.

Type: Policy Version

This method kicks off a delayed job to run a CIS benchmark version against either a node or a node group. If the benchmark version specified is not a CIS benchmark version, the job will not be created, and will return a 400.

Type: Policy

This method kicks off a delayed job to run the latest benchmark version of the specified CIS benchmark against either a node or a node group. If the benchmark specified is not a CIS benchmark, the job will not be created, and will return a 400.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
type
required
integer

The code of the type of job you would like to initiate.

CodeType
3Policy
4Node
5Environment
6Policy Version
7Node Group
11Node Scan
12Environment Node Scan
13Node Group Node Scan

type_id
required
integer

The ID of the resource associated with the type.

TypeType ID
NodeThe ID of the node to initiate CIS benchmarks on.
Node GroupThe ID of the node group to initiate CIS benchmarks on.
EnvironmentThe ID of the environment you want to run CIS benchmarks against.
Node ScanThe ID of the node you want to scan.
Node Group Node ScanThe ID of the node group containing nodes you want to scan.
Environment Node ScanThe ID of the environment containing nodes you want to scan.
Policy VersionThe ID of the CIS benchmark version you want to execute against a given node or node group.
PolicyThe ID of the CIS benchmark you want to execute against a given node or node group.

node_id
integer

The ID of the node to execute a policy-based job against.

  • Note This parameter only applies when the Policy and Policy Version types are used.
  • Note Either the node_id or node_group_id is required, but not both.

node_group_id
integer

The ID of the node group to execute a policy-based job against.

  • Note This parameter only applies when the Policy and Policy Version types are used.
  • Note Either the node_id or node_group_id is required, but not both.

Responses

Response samples

Content type
application/json
{
  • "job_id": 1,
  • "delayed_job": true
}

Show

This method returns details of the job specified by a given ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

job_id
required
integer

The ID of the job.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2012-10-30T16:16:52-07:00",
  • "created_by": 178,
  • "id": 1,
  • "scheduled_job_id": 3,
  • "source_id": 22,
  • "source_name": "Cluster Node 1",
  • "source_type": 11,
  • "status": 2,
  • "updated_at": "2012-10-30T16:16:57-07:00",
  • "updated_by": 178
}

Tasks

This methods allows you to list tasks under a given job. An optional ‘status’ parameter can be supplied to filter for tasks with a given status.

path Parameters
format
required
string
Value: "json"

The output format of the response.

job_id
required
integer
Example: 1

The ID of the job.

query Parameters
status
string
Enum: "pending" "processing" "success" "assigned" "failure" "offline" "cancelled" "timeout" "error" "exception"
Example: status=success

A Task's status can be one of the following values:

CodeStatusDescription
0 pending The task has been created and is yet to be picked up for processing.
1 processing The task is currently being executed.
2 success The task has completed with a successful result.
3 assigned The task has been assigned to a specific agent in a multi-agent setup, but is yet to be picked up for processing.
9 failure The task has completed with an unsuccessful result.
10 offline The task tried to run, but the target node or connection manager was offline.
20 cancelled The task was cancelled before it finished executing.
55 timeout The task took too long to execute and hit a timeout before it could complete.
88 error The task failed to complete in either a success or failure state due to either a user error, a lack of information or other known way a test cannot definitively say if a test is true or false.
99 exception Similar to the Error status, but usually not one of the common types of errors that can occur.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Node Groups

Index

This method returns a list of node groups registered to the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Create

This method allows you to create a new node group group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "organisation_id": 123,
  • "name": "IIS",
  • "description": "All IIS Servers",
  • "node_rules": "^IIS"
}

Show

This method returns details of the node group, specified by a given ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2015-08-18T13:53:59-11:00",
  • "description": "All IIS Servers",
  • "diff_notify": false,
  • "external_id": "string",
  • "id": 1,
  • "name": "IIS",
  • "node_rules": "^IIS",
  • "organisation_id": 123,
  • "scan_options": {
    },
  • "search_query": [
    ],
  • "status": 1,
  • "updated_at": "2016-05-25T03:53:28-11:00"
}

Update

This method allows you to update attributes of a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete a node group from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Lookup

This method allows you to lookup the Node Group ID by name.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
name
required
string

The name of the node group to search for.

Responses

Response samples

Content type
application/json
{
  • "node_group_id": 123
}

Add Node

This method allows you to add a node to a given node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
node_id
required
integer

The node ID you want to remove from this node group.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-12-18T14:48:31-08:00",
  • "id": 34,
  • "node_group_id": 1,
  • "node_id": 45,
  • "updated_at": "2013-12-18T14:48:31-08:00"
}

Add Nodes

This method allows you to add nodes to the node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
node_ids
required
Array of arrays

A list of one or more node IDs to add to this node group. e.g. /api/v2/node_groups/{node_group_id}/add_nodes.json?node_ids[]=1&node_ids[]=2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Compare Nodes

This method allows you to compare the nodes in the node group to each other.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
node_id
integer

The id of the node you wish to use as the base. If none given it will select the first in the group.

Responses

Response samples

Content type
application/json
{
  • "node_group_id": 1,
  • "nodes": [
    ],
  • "totals": {
    }
}

Nodes

This method returns a list of nodes in the node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Remove Node

This method allows you to remove a node from the node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
node_id
required
integer

The node ID you want to remove from this node group.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Add Policy Version

This method allows you to add a policy version to the node group. Acceptable parameter combinations are:

  • policy_version_id
  • policy_id and version

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
policy_version_id
integer

The ID of the policy version you want to attach to this node group.

policy_id
integer

The ID of the policy you want to attach to this node group.

version
integer

The version number of the policy you want to attach to this node group. This parameter also accepts the string "latest" for the most recent version of the specified policy.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-12-18T14:48:31-08:00",
  • "id": 123,
  • "node_group_id": 1,
  • "policy_version_id": 17,
  • "updated_at": "2013-12-18T14:48:31-08:00"
}

Policy Versions

This method allows you to list all policy versions attached to this node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
[]

Remove Policy Version

This method allows you to remove a policy version assigned to the node group. Acceptable parameter combinations are:

  • policy_version_id
  • policy_id and version

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
policy_version_id
integer

The ID of the policy version you want to attach to this node group.

policy_id
integer

The ID of the policy you want to attach to this node group.

version
integer

The version number of the policy you want to attach to this node group. This parameter also accepts the string "latest" for the most recent version of the specified policy.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Node Group Configuration

This method allows you to view the current configuration for the node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
{
  • "ignore_items": {
    },
  • "scan_options": {
    },
  • "policies": [ ]
}

Set Scan Options

This method allows you to update the scan options for a specified node group by its ID. This method accepts only one scan option key at a time for updating the scan options. The submitted request body is echoed back on successful application of the endpoint to please refer to the sample request body examples for examples of response bodies.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Request Body schema: application/json
required
option_name
string
Enum: "connectivity" "database_schemas" "etcd_keys" "scan_directory_options" "scan_diff_excluded_text" "scan_nmap" "scan_sections" "registry_keys" "group_policy_objects" "sql_queries" "powershell_queries" "preprocessors" "scripts" "scan_ports" "web" "cis_ignore"

Defines the scan option key that you will be setting.

option_object_array
Array of arrays

Array of objects or strings depending on the option_name selected. (Please refer to the request examples.)

Responses

Request samples

Content type
application/json
Example
{
  • "option_name": "connectivity",
  • "connectivity": [
    ]
}

Response samples

Content type
application/json
{
  • "option_name": "connectivity",
  • "option_object_array": [ ]
}

Scan

This method allows you to trigger a scan of a node group by specifying the node group’s ID.

path Parameters
node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2012-10-30T16:16:52-07:00",
  • "created_by": 178,
  • "id": 1,
  • "scheduled_job_id": 3,
  • "source_id": 22,
  • "source_name": "Cluster Node 1",
  • "source_type": 11,
  • "status": 2,
  • "updated_at": "2012-10-30T16:16:57-07:00",
  • "updated_by": 178
}

Add Users

This method allows you to add a user to be a member of a node group. Account level members must be added to a node group to be able to see and interact with nodes in that node group. For more information on Account level and Node Group level user access controls, please visit our guide on User Access.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
user_id
required
integer

The ID of the user you want to add to the node group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Users

This method allows you to list users assigned to a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove User

This method allows you to unassign a user from a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_group_id
required
integer

The ID of the node group.

query Parameters
user_id
integer

The ID of the user you want to unassign from the node group.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Node Scans

Index

This method allows you to retrieve a list of node scans.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_id
required
integer

The ID of the node to retrieve scans for.

latest
boolean

Retrieve the latest node scan for the node.

date_from
string

The start date to query scans from. Must be used with the date_to parameter. Must be in the date format YYYY-MM-DD.

date_to
string

The end date to query scans to. Must be used with the date_from parameter. Must be in the date format YYYY-MM-DD.

page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method allows you to view a node scan referenced by its ID in the request URL path. You may also reference this method from the Index method, as shown in the url key value of each node scan for a specified node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_scan_id
required
integer

The ID of the node scan to show.

Responses

Response samples

Content type
application/json
{
  • "id": 9,
  • "node_id": 3,
  • "data": "{\"EnvVars\":{\"Linux\":{\"PATH\":{...}...}...}...}",
  • "scan_options": "\"scan_ports\":{\"tcp\":\"1-1024\",\"udp\":\"1-1024\"}",
  • "created_at": "2016-08-04T15:03:21-07:00",
  • "updated_at": "2016-08-05T15:06:42-07:00",
  • "task_id": 6,
  • "associated_id": 0,
  • "category": 0,
  • "label": "Authorized change 2001",
  • "tsv": "string"
}

Compare

This method allows you to compare the differences between that of the specified node_scan_id against another node scan specified by the source id. The differences shown between the two node scans are those of the most current node scan of the source node scan against the node_scan_id.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_scan_id
required
integer

The ID of the node scan to show.

query Parameters
source_id
required
integer

The ID of the node scan to compare against.

Responses

Response samples

Content type
application/json
{
  • "packages": {
    },
  • "__diff_stats": {
    }
}

Search

This method allows you to search your previous node scans for key words and return a JSON result.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
query
required
string

The query string you wish to search for.

type
string

The type name (eg Packages, Users) you wish to restrict the query to.

environment_id
integer

The id of the environment you wish to restrict the query to.

node_group_id
integer

The id of the node group you wish to restrict the query to.

exact_match
boolean

Whether or not the results should exactly match the search text or can just be a subset of the text.

Responses

Response samples

Content type
application/json
{
  • "node_id": 6,
  • "node_name": "SERVER_XYZ",
  • "scan_date": "2014-06-28T21:24:24-07:00",
  • "data": {
    }
}

Nodes

New

This method returns a skeleton payload format that can subsequently be submitted to create a new node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "alternate_password": "string",
  • "connection_manager_group_id": 1,
  • "description": "The prod node we use to serve the main content from our website. One sunny day...",
  • "environment_id": 2,
  • "external_id": "i-12345",
  • "mac_address": "00:00:00:00:00:00",
  • "medium_hostname": "jenkins.company.com",
  • "medium_info": "string",
  • "medium_password": "string",
  • "medium_port": 22,
  • "medium_type": 1,
  • "medium_username": "guardian",
  • "name": "prod01",
  • "node_type": "SV",
  • "operating_system_family_id": 1,
  • "operating_system_id": 123,
  • "public": true,
  • "short_description": "The main prod website node",
  • "url": "https://www.cloudhouse.com"
}

Create

This method allows you to register a new node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "alternate_password": "string",
  • "connection_manager_group_id": 1,
  • "description": "The prod node we use to serve the main content from our website. One sunny day...",
  • "environment_id": 2,
  • "external_id": "i-12345",
  • "id": 311,
  • "ip_address": "192.168.1.1",
  • "mac_address": "00:00:00:00:00:00",
  • "medium_hostame": "jenkins.company.com",
  • "medium_info": "string",
  • "medium_port": 22,
  • "medium_type": 1,
  • "medium_username": "guardian",
  • "name": "prod01",
  • "node_type": "SV",
  • "online": true,
  • "operating_system_family_id": 1,
  • "operating_system_id": 123,
  • "public": true,
  • "short_description": "The main prod website node",
  • "url": "https://www.cloudhouse.com"
}

Index

This method returns a list of nodes registered to the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
last_scan_status
string
Default: "all"
Enum: "pending" "processing" "success" "assigned" "actioned" "failure" "offline" "cancelled" "timeout" "error" "exception" "all_failures"

List nodes based on the status of their last node scan.

page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

status
string
Enum: "active" "deleted" "detected"

Only show nodes of a particular status

name
string

Filter down to nodes that contain this substring in their name. (case insensitive).

external_id
string

Filter down to nodes that contain this substring in their external ID. (case insensitive).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method returns details of the node specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

Responses

Response samples

Content type
application/json
{
  • "alternate_password": "string",
  • "connection_manager_group_id": 1,
  • "description": "The prod node we use to serve the main content from our website. One sunny day...",
  • "environment_id": 2,
  • "external_id": "i-12345",
  • "id": 311,
  • "ip_address": "192.168.1.1",
  • "mac_address": "00:00:00:00:00:00",
  • "medium_hostame": "jenkins.company.com",
  • "medium_info": "string",
  • "medium_port": 22,
  • "medium_type": 1,
  • "medium_username": "guardian",
  • "name": "prod01",
  • "node_type": "SV",
  • "online": true,
  • "operating_system_family_id": 1,
  • "operating_system_id": 123,
  • "public": true,
  • "short_description": "The main prod website node",
  • "url": "https://www.cloudhouse.com"
}

Update

This method allows you to update properties of a node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

Request Body schema: application/json
required
object

The node object you would like to update. If a field is missing from the node object, the it will not be updated. Please note that submitting a value as null will be interpreted as an empty string.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete a node from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Look Up

This method allows you to look up the Node ID of a registered node based on either the name, external_id or a combination of SSH connection details. Valid parameter usages are:

  • ?name=[node_name]
  • ?external_id=[external_id]
  • ?ssh_hostname=[hostname]&ssh_username=[username]
  • ?ssh_hostname=[hostname]&ssh_username=[username]&ssh_port=[port] .
path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
name
string

The name of the node to look up.

external_id
string

The external ID of the node to look up.

ssh_hostname
string

The SSH hostname of the node to look up.

ssh_username
string

The SSH username of the node to look up.

ssh_port
integer

The SSH port of the node to look up. If missing and ssh_hostname and ssh_username are supplied, defaults to 22.

Responses

Response samples

Content type
application/json
{
  • "node_id": 123
}

Add to Node Group

This method allows you to add the node to a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

query Parameters
node_group_id
required
integer

The ID of the node group the node is being added to.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-12-18T14:48:31-08:00",
  • "id": 87,
  • "node_id": 199,
  • "node_group_id": 101,
  • "updated_at": "2013-12-18T14:48:31-08:00"
}

Remove from Node Group

This method allows you to remove the node from a node group.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

query Parameters
node_group_id
required
integer

The ID of the node group the node is being removed from.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Node Groups

This method returns a list of node groups the node belongs to.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Status Counts

This method returns the total, failing and unmanaged status counts, either for your whole account, a particular node group or a particular environment. If both the node_group_id and environment_id parameter are specified, only the environment_id parameter will be considered and the node_group_id will be ignored.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_group_id
integer

Show only status counts for nodes in the given node group.

environment_id
integer

Show only status counts for nodes in the given environment.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "failed": 0,
  • "unmanaged": 0
}

Start Scan

This method allows you to initiate a Node Scan against this node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to initiate a scan on.

query Parameters
label
string

The label you wish to tag a scan with (can include spaces).

Responses

Response samples

Content type
application/json
{
  • "job_id": 1337
}

Scan Details

This method allows you to retrieve scan details from the latest Node Scan for the node. If neither scan_id or scan_label are given, the most recent scan for this node is retrieved.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to retrieve a scan for.

query Parameters
scan_id
integer

The ID of the scan you would like to retrieve.

scan_label
string

The label of the scan you would like to retrieve (if there are multiple matches it will return the most recent).

Responses

Response samples

Content type
application/json
{
  • "id": 1337,
  • "label": "Change 2001",
  • "status": 0,
  • "data": "{\"packages\":{...}}",
  • "created_at": "2015-09-14T05:02:12Z"
}

Last Scan Status

This method allows you to look up the task status and task report of the last node scan run on this node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to retrieve the last node scan's status for.

Responses

Response samples

Content type
application/json
Example
{
  • "status": 2,
  • "status_string": "success",
  • "report": "[{\"generate_node_scan\":{\"number_of_packages_found\":\"96\",\"number_of_files_found\":\"5\",\"number_of_services_found\":\"153\",\"number_of_users_found\":\"2\",\"number_of_groups_found\":\"25\",\"number_of_ports_found\":\"64\",\"number_of_environment_variables_found\":\"34\",\"result\":\"success\",\"messages\":[]}},{\"upload_node_scan\":{\"result\":\"success\",\"node_id\":\"174\",\"http_response_code\":\"201\",\"http_response_body\":\"\",\"messages\":[]}}]\""
}

Last Successful Scan

This method allows you to look up the details of the last successful scan job that was run against the specified node. Note that this will not retrieve the raw data of the actual scan.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to retrieve details for.

Responses

Response samples

Content type
application/json
Example
{
  • "status": 2,
  • "status_string": "success",
  • "report": "[{\"detect_os\":{\"messages\":[],\"result\":\"success\"}},{\"generate_blueprint\":{\"messages\":[],\"result\":\"success\"}},{\"upload_blueprint\":{\"messages\":[],\"result\":\"success\"}}]",
  • "created_at": "2015-06-09T10:14:52-07:00",
  • "updated_at": "2015-06-09T10:15:19-07:00"
}

Last Node Scan Details

This method allows you to retrieve information about the last scan that was performed on the specified node.

path Parameters
format
required
string
Enum: "csv" "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to retrieve details for.

query Parameters
with_data
boolean
Default: true

If true, will retrieve verbose output from the last scan.

Responses

Response samples

Content type
application/json
{
  • "associated_id": 0,
  • "category": 0,
  • "created_at": "2016-08-04T15:03:21-07:00",
  • "id": 9,
  • "label": "Authorized change 2001",
  • "node_id": 3,
  • "scan_options": "\"scan_ports\":{\"tcp\":\"1-1024\",\"udp\":\"1-1024\"}",
  • "status": 1,
  • "task_id": 6,
  • "updated_at": "2016-08-05T15:06:42-07:00"
}

Diff

This method allows you to perform differencing operations against nodes and specific node scans. There are three types of diffs you can perform with this endpoint.

Diff StyleExample URL
Diff Last/api/v2/nodes/diff.json?node_id=50
Node to Node/api/v2/nodes/diff.json?node_id=50&compare_node_id=60
Scan to Scan/api/v2/nodes/diff.json?scan_id=100&compare_scan_id=200
Note Diffs are returned in "diff only" format. This means only the changed items will be returned with the relevant diff information, not the entire scan.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_id
integer

The ID of the node to be used for diff (last scan will be used by default).

compare_node_id
integer

The id of the node to be used for comparing to node_id (last scan will be used by default).

scan_id
integer

The ID of the scan to be used for diff.

compare_scan_id
integer

The ID of the scan to be used for comparing to the scan indicated by scan_id.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Group Diff

This method allows you to perform group diff operations against nodes, or node groups. There are 2 types of diffs you can perform using the parameters listed above. 1. A “grouped nodes” style diff where you supply any number of node id’s and the most recent scan for those nodes will be compared 2. A “node group to node group” style diff where you supply any number of node group id’s and the most recent scan for those node groups will be compared. Some example usages are

Diff StyleExample URL
Diff Between Nodes/api/v2/nodes/group_diff.json?node_ids=1,2,3,4,5,6
Diff Between Node Groups/api/v2/nodes/group_diff.json?node_group_ids=2,4
Ignored Items/api/v2/nodes/group_diff.json?node_group_ids=2&show_ignored=true
Show differences only/api/v2/nodes/group_diff.json?node_group_ids=2&show_difference=true

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
node_ids
Array of integers

The IDs of the nodes to be used for differencing (latest node scan will be used).

node_group_ids
Array of integers

The IDs of the node groups to be used for differencing (latest node group scan will be used).

show_ignored
boolean

If true, includes ignored items in the resulting difference.

show_difference
boolean

Only show where differences exist and discard any common attributes between all scans considered.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "group_hash": "string",
  • "ignored_items": {
    },
  • "lookup": [
    ],
  • "name": "Group Diff",
  • "node_count": 2
}

Node Configuration

This method allows you to view the scan configuration of a node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node you wish to retrieve the node scan configuration for.

Responses

Response samples

Content type
application/json
{
  • "ignore_items": {
    },
  • "scan_options": {
    },
  • "policies": [ ]
}

CI Data

This method allows you to retrieve a subsection of the latest node scan for the specified node.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

query Parameters
ci_type
required
string

The CI type of the section to retrieve. Some examples include files, ports, users.

Responses

Response samples

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

Raw Files

This method allows you to retrieve a list of all raw files which correspond to a node scan of the specified node types above. Note The raw file endpoints only apply to node types that are Firewalls, Switches, or Routers.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

Responses

Response samples

Content type
application/json
[]

Raw File

This method allows you to retrieve the most recent raw file which corresponds to its equivalent node scan for the specified node types above Firewalls, Switches, or Routers. If no parameters are supplied, this method will return the most recent raw file in the stored category by default. Note The parameters raw_file_id and category should not be used together.

path Parameters
format
required
string
Value: "json"

The output format of the response.

node_id
required
integer

The ID of the node.

query Parameters
raw_file_id
integer

The ID of the raw file that you wish to retrieve.

category
integer
Default: 0
Enum: 0 1 2

The category from which the node scan ids will be retrieved from.

  • 0 denotes stored config
  • 1 denotes running config
  • 2 denotes merged config

Responses

Response samples

Content type
application/json
{
  • "id": 125,
  • "data": "...",
  • "node_scan_id": 9
}

Operating System Families

Index

This method returns a list of recognized operating system families. An operating system family is a grouping of operating systems.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method allows you to access a specific Operating System Family given its ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

operating_system_family_id
required
integer

The ID of the operating system family.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Windows"
}

Operating Systems

Index

This method returns a list of recognized operating system types.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show

This method allows you to access a specific Operating System given it's ID.

path Parameters
format
required
string
Value: "json"

The output format of the response.

operating_system_id
required
integer

The ID of the operating system.

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "Windows",
  • "operating_system_family_id": 1,
  • "description": "Windows 2012 Server"
}

Lookup

This method allows you to lookup the ID of an Operating System registered with Guardian based on a query string.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
query
required
string

A search query of the general name of the operating system you want to lookup.

Responses

Response samples

Content type
application/json
{
  • "operating_system_family_id": 1,
  • "operating_system_family": "Windows",
  • "operating_system_id": 123,
  • "operating_system_name": "Windows 2012 Server"
}

Pluggables

New

This method returns a skeleton payload format that can subsequently be submitted to create a new pluggable.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
{
  • "name": null,
  • "operating_system_family_id": null,
  • "script": null
}

Index

This method returns a list of pluggables created by the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create a new pluggable.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object (PluggableWithoutId)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "operating_system_id": 123,
  • "operating_system_family_id": 2,
  • "name": "Production",
  • "script": "showall config"
}

Show

This method returns the details of the pluggable specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

operating_system_id
required
integer

The Operating System ID of the pluggable.

Responses

Response samples

Content type
application/json
{
  • "operating_system_id": 30,
  • "operating_system_family_id": 123,
  • "name": "NewOS",
  • "script": ""
}

Update

This method allows you to update properties of an pluggable.

path Parameters
format
required
string
Value: "json"

The output format of the response.

operating_system_id
required
integer

The Operating System ID of the pluggable.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete an pluggable from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

operating_system_id
required
integer

The Operating System ID of the pluggable.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Policies

New

This method returns a skeleton payload format that can subsequently be submitted to create a new policy.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

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

Index

This method returns a list of policies for the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[]

Create

This method allows you to create a new policy.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Basic user permissions.",
  • "description": "A basic policy used to enforce User Permissions.",
  • "created_by": 10,
  • "updated_by": 11,
  • "created_at": "2016-04-14T18:03:29-07:00",
  • "updated_at": "2016-04-14T18:03:29-07:00",
  • "operating_system_family_id": 2,
  • "operating_system_id": 211
}

Show

This method returns details of the policy specified by the ID given in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Basic user permissions.",
  • "description": "A basic policy used to enforce User Permissions.",
  • "created_by": 10,
  • "updated_by": 11,
  • "created_at": "2016-04-14T18:03:29-07:00",
  • "updated_at": "2016-04-14T18:03:29-07:00",
  • "operating_system_family_id": 2,
  • "operating_system_id": 211,
  • "data": "[{\"EnvVars\": [{\"linux\": [{\"name\": \"BASH\", \"checks\": {\"value\": [{\"check\": \"equals\", \"expected\": \"/bin/bash\"}]}, \"EnvVars\": {\"name\": \"BASH\"}, \"ci_path\": [\"EnvVars\", \"linux\", \"BASH\"], \"check_type\": \"envvars\"}]}]}]",
  • "tag": "string",
  • "is_latest": true,
  • "version": 1
}

Update

This method allows you to update the properties of a policy.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete a policy from your account.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Look Up

This method allows you to lookup the Policy ID of a created policy in your account based on either the name of the policy or the description fields of the policy. This method will return the first result of the policy that matches the lookup parameters.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
name
string

The text to search for in the names of policies to locate a policy.

short_description
string

The text to search for in the dscriptions of policies to locate a policy.

Responses

Response samples

Content type
application/json
{
  • "policy_id": 14
}

SummaryResults

This method returns a summary of policy results for the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Target Nodes

This method returns you the list of Node IDs that is targeted by the Policy specified by the ID in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

Responses

Response samples

Content type
application/json
"[53,61,62]"

Versions

This method returns you the list of versions of the policy, each version different from the previous due to updates performed to the policy data.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add File Check

This method allows you to add a file type check to the given policy. If the check already existed in the policy, then a new policy version will not be created and a 204 response will be returned. If a new check was added to the policy, a new policy version will be created and the details of that new version returned with a 201 response code.

path Parameters
format
required
string
Value: "json"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
section
required
string
Example: section=Production Files

The policy section the check should live under. A policy consists of sections, which contain checks.

file_path
required
string
Example: file_path=/etc/application.conf

The absolute file path for the file check to be added.

attr
required
string
Example: attr=checksum

The attribute of the configuration object you want to check. Examples include present, content, checksum, value, etc.

check
required
string
Enum: "equals" "includes" "excludes" "conditional" "version_comparison" "time_comparison" "regex" "regex_excludes" "allow" "xpath" "present"
Example: check=present

The type of attribute check.

expected
required
string
Example: expected=true

The expected value for the policy check.

absent_pass
boolean

A check will fail by default if the value the check is to be run on is missing. Set this value to true to pass the check if the value is absent.

Responses

Response samples

Content type
application/json
{
  • "policy_version_id": 44,
  • "tag": "string",
  • "version": 1
}

Latest Results (failed_only=true)

This method returns the latest result details of the policy specified by the ID given in the URL. Note Policy results are displayed for each node that the policy is applied to. The policy_result_id can be queried against the results provided by the include_policy_results parameter to display further policy result details.

path Parameters
format
required
string
Enum: "json" "pdf"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
failed_only
boolean

If true, only failed policy results will be returned.

include_policy
boolean

Display policy meta data.

include_policy_versions
boolean

Display previous policy versions.

include_type_stats
boolean

Display the overall result of a policy across all nodes.

include_policy_results
boolean

Display detailed policy results. The data element allows you retrieve expected and actual node scan results.

all_data
boolean

Display results for all parameters listed here (not including node_id).

node_id
integer

Optionally narrow down policy results to a specific node given by this node_id.

Responses

Response samples

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

Latest Results (include_policy=true)

This method returns the latest result details of the policy specified by the ID given in the URL. Note Policy results are displayed for each node that the policy is applied to. The policy_result_id can be queried against the results provided by the include_policy_results parameter to display further policy result details.

path Parameters
format
required
string
Enum: "json" "pdf"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
failed_only
boolean

If true, only failed policy results will be returned.

include_policy
boolean

Display policy meta data.

include_policy_versions
boolean

Display previous policy versions.

include_type_stats
boolean

Display the overall result of a policy across all nodes.

include_policy_results
boolean

Display detailed policy results. The data element allows you retrieve expected and actual node scan results.

all_data
boolean

Display results for all parameters listed here (not including node_id).

node_id
integer

Optionally narrow down policy results to a specific node given by this node_id.

Responses

Response samples

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

Latest Results (include_policy_versions=true)

This method returns the latest result details of the policy specified by the ID given in the URL. Note Policy results are displayed for each node that the policy is applied to. The policy_result_id can be queried against the results provided by the include_policy_results parameter to display further policy result details.

path Parameters
format
required
string
Enum: "json" "pdf"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
failed_only
boolean

If true, only failed policy results will be returned.

include_policy
boolean

Display policy meta data.

include_policy_versions
boolean

Display previous policy versions.

include_type_stats
boolean

Display the overall result of a policy across all nodes.

include_policy_results
boolean

Display detailed policy results. The data element allows you retrieve expected and actual node scan results.

all_data
boolean

Display results for all parameters listed here (not including node_id).

node_id
integer

Optionally narrow down policy results to a specific node given by this node_id.

Responses

Response samples

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

Latest Results (include_type_stats=true)

This method returns the latest result details of the policy specified by the ID given in the URL. Note Policy results are displayed for each node that the policy is applied to. The policy_result_id can be queried against the results provided by the include_policy_results parameter to display further policy result details.

path Parameters
format
required
string
Enum: "json" "pdf"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
failed_only
boolean

If true, only failed policy results will be returned.

include_policy
boolean

Display policy meta data.

include_policy_versions
boolean

Display previous policy versions.

include_type_stats
boolean

Display the overall result of a policy across all nodes.

include_policy_results
boolean

Display detailed policy results. The data element allows you retrieve expected and actual node scan results.

all_data
boolean

Display results for all parameters listed here (not including node_id).

node_id
integer

Optionally narrow down policy results to a specific node given by this node_id.

Responses

Response samples

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

Latest Results (include_policy_results=true)

This method returns the latest result details of the policy specified by the ID given in the URL. Note Policy results are displayed for each node that the policy is applied to. The policy_result_id can be queried against the results provided by the include_policy_results parameter to display further policy result details.

path Parameters
format
required
string
Enum: "json" "pdf"

The output format of the response.

policy_id
required
integer

The ID of the policy.

query Parameters
failed_only
boolean

If true, only failed policy results will be returned.

include_policy
boolean

Display policy meta data.

include_policy_versions
boolean

Display previous policy versions.

include_type_stats
boolean

Display the overall result of a policy across all nodes.

include_policy_results
boolean

Display detailed policy results. The data element allows you retrieve expected and actual node scan results.

all_data
boolean

Display results for all parameters listed here (not including node_id).

node_id
integer

Optionally narrow down policy results to a specific node given by this node_id.

Responses

Response samples

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

Scheduled Jobs

Index

This method returns a list of scheduled jobs for the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create

This method allows you to create a new Scheduled Job.

path Parameters
format
required
string
Value: "json"

The output format of the response.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "2s",
  • "organization_id": 2,
  • "source_id": 2,
  • "source_name": "Default",
  • "source_type": 12,
  • "status": 2,
  • "url": "/api/v2/scheduled_jobs/2.json",
  • "data": "{}"
}

Show

This method returns details of the scheduled job specified by the job ID in the URL.

path Parameters
format
required
string
Value: "json"

The output format of the response.

scheduled_job_id
required
integer

The ID of the scheduled job.

Responses

Response samples

Content type
application/json
{
  • "id": "2s",
  • "organization_id": 2,
  • "source_id": 2,
  • "source_name": "Default",
  • "source_type": 12,
  • "status": 2,
  • "url": "/api/v2/scheduled_jobs/2.json",
  • "data": "{}"
}

Update

This method allows you to update the specified scheduled job.

path Parameters
format
required
string
Value: "json"

The output format of the response.

scheduled_job_id
required
integer

The ID of the scheduled job.

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Destroy

This method allows you to delete the specified scheduled job.

path Parameters
format
required
string
Value: "json"

The output format of the response.

scheduled_job_id
required
integer

The ID of the scheduled job.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Cancel Jobs

This method allows you to stop running and pending jobs associated with the specified scheduled job.

path Parameters
format
required
string
Value: "json"

The output format of the response.

scheduled_job_id
required
integer

The ID of the scheduled job.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Scores

Index

This method returns a list of Scores created by the organization.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
page
integer >= 1
Default: 1

Displays results based on specified page number.

per_page
integer >= 1
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

System Metrics

Index

This endpoint reports disk usage percentages. (This endpoint is only applicable to on-premise accounts.).

path Parameters
format
required
string
Value: "json"

The output format of the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Text Files

Show

This method allows you to retrieve a text file.

path Parameters
format
required
string
Value: "json"

The output format of the response.

text_file_id
required
integer

The ID of the text file.

Responses

Response samples

Content type
application/json
{
  • "category": 1,
  • "checksum": "0fcc7e5d846da8b3079bd56d5eaea6cc",
  • "created_at": "2015-03-10T15:37:09-07:00",
  • "data": "This is sample content from a text file",
  • "id": 20,
  • "name": null,
  • "updated_at": "2015-03-10T15:37:09-07:00"
}

Users

Index

This method returns a list of all users in an organization. The selected organization is determined by the API key and secret specified in the Authorization header.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
invited
bool
Default: false

If set to true, also return users who have been invited to the organization.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Invite

This method allows a caller to invite a user to an organization via their email address. If a user does not have an account with Guardian yet, they will be sent an invite link to sign up. If the user already has an account they are immediately added to this organization.

Responses are:

  • 201 Existing user was successfully invited to a new account.
  • 201 New user has been sent an invite to register with the appliance and join the account.
  • 204 User is already part of the account.
  • 204 User already has a valid invite with them to this account.
  • 422 Missing email address in query.
  • 422 Role specified is not member or analyst
.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
email
required
string
Example: email=c.m.burns@snpp.com

The email address of the user to invite. Note, if the email address contains a plus symbol (+) please replace it with the URL encoded form (%2B).

role
required
string
Enum: "member" "analyst"

The role to invite the user as. Note you cannot invite new users as the Administrator (admin) role via the API. Once a user has accepted an invite and logged into the system, you can use the Update Role endpoint to update their role to admin.

Responses

Response samples

Content type
application/json
Example
{
  • "email": "c.m.burns@snpp.com",
  • "organisation_id": 12,
  • "role": "member"
}

Update

This method allows you to update properties of a user.

path Parameters
format
required
string
Value: "json"

The output format of the response.

user_id
required
integer

The ID of the user.

Request Body schema: application/json
required
name
string (_properties_name-10)

The first name of the user, set during registration.

surname
string (surname)

The surname of the user, set during registration.

external_id
string (_properties_external_id)

An extra, free-text external ID field that can be stored and viewed against user records. This is only available via a feature toggle.

Responses

Request samples

Content type
application/json
{
  • "name": "Charles",
  • "surname": "Burns",
  • "external_id": "987654321"
}

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Update Role

This method updates a user's role within the selected organization. The selected organization is determined by the API key and secret specified in the Authorization header. The selected user is determined by the email value specified in the request parameters.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
email
required
string

The email of the user whose role will be updated. Note, if the email address contains a plus symbol (+) please replace it with the URL encoded form (%2B).

role
required
string
Enum: "member" "analyst" "admin"

The new role to switch the user to.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}

Remove

This method removes a user from the selected organization. The selected organization is determined by the API key and secret specified in the Authorization header. The selected user is determined by the email value specified in the request parameters.

path Parameters
format
required
string
Value: "json"

The output format of the response.

query Parameters
email
required
string
Default: false

The email of the user that will be removed from the organization. Note, if the email address contains a plus symbol (+) please replace it with the URL encoded form (%2B).

new_owner
number
Default: false

The id of the user that will own the removed user's existing policies.

Responses

Response samples

Content type
application/json
{
  • "error": "No authorization method found"
}