UpGuard Core API (v2)

Download OpenAPI specification:Download

For information on using the API, please refer to our guide on Using the API. Please refer to the CyberRisk API documentation if you are looking to interface with UpGuard CyberRisk.

Authentication

AuthorizationHeader

The Authorization header should be used to authenticate requests to the API.

The format is: Authorization: Token token="<api_key><api_secret>".

For more information on where to find your API key and secret and how to use it, please refer to our guide on the API Authorization Header.

Security scheme type: API Key
Header parameter name: Authorization

BasicAuth

HTTP Basic Auth can also be used to autheticate with the API. To use Basic Auth, submit the API Key as the username and submit the API Secret Key as the password.

Security scheme type: HTTP
HTTP Authorization Scheme basic

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

200

OK

401

Unauthorized

get /api/v2/accounts.{format}
https://you.upguard.com/api/v2/accounts.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Remove User

This method allows you to remove a user from an account.

path Parameters
account_id
required
integer

The ID of the account.

format
required
string
Value: "json"

The output format of the response.

query Parameters
email
required
string

The email associated with the user account.

new_owner
required
integer

When removing a user from an account, the ownership of policies created by the to-be-removed user must be transfered to another user. This parameter is the ID of the user that will take ownership.

Responses

204

No Content

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

put /api/v2/accounts/{account_id}/remove_user.{format}
https://you.upguard.com/api/v2/accounts/{account_id}/remove_user.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": "No authorization method found"
}

Update User Role

This method allows you to modify a user's role within a particular account.

path Parameters
account_id
required
integer

The ID of the account.

format
required
string
Value: "json"

The output format of the response.

query Parameters
email
required
string

The email associated with the user account.

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

The role of the user in this account.

Responses

204

No Content

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

put /api/v2/accounts/{account_id}/update_user_role.{format}
https://you.upguard.com/api/v2/accounts/{account_id}/update_user_role.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": "No authorization method found"
}

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

200

OK

401

Unauthorized

403

Forbidden

get /api/v2/change_report.{format}
https://you.upguard.com/api/v2/change_report.{format}

Response samples

Content type
Copy
Expand all Collapse all
{
  • "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:

Start date to retrieve changes (ISO 8601 format).

date_to
datetime
Default: "now"
Example:

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

200

OK

401

Unauthorized

get /api/v2/change_report/aggregate.{format}
https://you.upguard.com/api/v2/change_report/aggregate.{format}

Response samples

Content type
text/csv
Copy
"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

200

OK

401

Unauthorized

get /api/v2/change_requests.{format}
https://you.upguard.com/api/v2/change_requests.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[]

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

200

OK

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

get /api/v2/change_requests/{change_request_id}.{format}
https://you.upguard.com/api/v2/change_requests/{change_request_id}.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

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

200

OK

401

Unauthorized

get /api/v2/connection_managers.{format}
https://you.upguard.com/api/v2/connection_managers.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

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

200

OK

401

Unauthorized

get /api/v2/connection_manager_groups.{format}
https://you.upguard.com/api/v2/connection_manager_groups.{format}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

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

201

Created