Tag

This documentation is currently outdated and in the process of being updated. This documentation is provided as a temporary reference to various API endpoints and output. This warning will be at the top of each outdated page. As the documentation is updated, this warning will be removed.

Tags allow users to tag vulnerability findings, hosts, web applications or databases to create a custom grouping that can be tracked through remediation. The RiskSense platform lets managers and group managers create new tags that define remediation projects with a specific duration. They may then explicitly tag host and web application vulnerabilities that will be included within the priorities and scope of remediation efforts for the project. Project owners may also choose to add new vulnerabilities dynamically to a project, automatically adding new vulnerabilities discovered for selected hosts or web applications.

Creating a Tag

Create a tag for the designated client.

API Call: POST/client/{clientId}/tag

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can create a tag are:

  • Manager
  • Group Manager
  • User

Python

Python Sample create_tag Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
tag_type = 'REMEDIATION'
tag_name = '<INSERT TAG NAME HERE>'
tag_desc = 'This is a tag description'
tag_owner = '<INSERT USER ID HERE>' # User ID, not user name.
tag_color = '#648d9f'  # Color as hex value
tag_locked = False
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "fields": [
        {
            "uid": "TAG_TYPE",
            "value": tag_type
        },
        {
            "uid": "NAME",
            "value": tag_name
        },
        {
            "uid": "DESCRIPTION",
            "value": tag_desc
        },
        {
            "uid": "OWNER",
            "value": tag_owner
        },
        {
            "uid": "COLOR",
            "value": tag_color
        },
        {
            "uid": "LOCKED",
            "value": tag_locked
        }
    ]
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag"
​
response = requests.post(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample create_tag Snippet

Copy 

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json"
  -d "{  \"fields\": [    {      \"uid\": \"TAG_TYPE\",      \"value\": \"<TAGTYPE>\"    },    {      \"uid\": \"NAME\",      \"value\": \"<TAGNAME>\"    },    {      \"uid\": \"DESCRIPTION\",      \"value\": \"<DESCRIPTION>\"    },    {      \"uid\": \"OWNER\",      \"value\": \"<OWNER>\"    },    {      \"uid\": \"COLOR\",      \"value\": \"<COLOR>\"    },    {      \"uid\": \"LOCKED\",      \"value\": <LOCKED>    }  ]}""

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
ASSESSMENTID The assessment ID to update.
APIKEY Your API key. Generating an API Token
TAGTYPE Tag Type. Options: Compliance, Location, Custom, Remediation, People, Project, Scanner, CMDB.
TAGNAME Tag name.
DESCRIPTION Tag description.
OWNER Tag owner. Use User ID.
COLOR Tag color. Use Hex value.
LOCKED Is tag locked? Options: True = Yes, False = No

Response Parameters

Sample Response

Copy 

{
  "id": <ID>,
  "created": "<CREATED>"
}

Name Description Additional Information
ID Job ID number. integer
CREATED Time/date when job was created. string($date-time)

HTTP Status Codes

Code Description
200 Job Created

200 Sample Response

Copy 

{
  "id": 0,
  "created": "2019-02-12T22:51:53.206Z"
}

Code Description
401 Unauthorized
404 Not Found

Deleting Tags in Bulk

Delete more than one tag at a time.

API Call: DELETE/client/{clientId}/tag

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can delete tags in bulk are:

  • Group Manager
  • Manager
  • User

Python

Python Sample delete_tagbulk Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "filterRequest": {
        "filters": [
            {
                "field": "id",
                "exclusive": False,
                "operator": "IN",
                "value": "1,2,3,4"
            }
        ]
    },
    "forceDeleteTicket": True
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag"
​
response = requests.delete(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token

cURL

cURL Sample delete_tagbulk Snippet

Copy 

curl -X DELETE "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json"
  -d "{  \"filterRequest\": {    \"filters\": [      {        \"field\": \"<FIELD>\",        \"exclusive\": <EXCLUSIVE>,        \"operator\": \"<OPERATOR>\",        \"value\": \"<VALUE>\"      }    ]  },  \"forceDeleteTicket\": <FORCEDELETETICKET>}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token
FIELD Filter field. Use id for tag ID number.
EXCLUSIVE Exclusive. boolean Options: True, False
OPERATOR Search operator. Depends on value.
VALUE Search value. string Separate values with commas.
FORCEDELETETICKET Force delete associated tickets? Options: True = Yes, False = No

Response Parameters

Sample Response

Copy 
{
  "id": <ID>,
  "created": "<CREATED>"
}

Name Description Additional Information
ID Job ID number. integer
Created Date/Time job created. string($date-time)

HTTP Status Codes

Code Description
200 Job Created

200 Sample Response

Copy 
{
  "id": 0,
  "created": "2019-09-17T15:54:44.296Z"
}
Code Description
401 Unauthorized
404 Not Found

Update a Tag

Update a tag for the designated client.

API Call: POST/client/{clientId}/tag/{tagId}

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID
TAGID Tag ID number.

User Roles

The user roles that can update a tag are:

  • Manager
  • Group Manager
  • User

Python

Python Sample update_tag Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
tag_id = <INSERT TAG ID HERE>
​
tag_type = 'REMEDIATION'
tag_name = '<INSERT TAG NAME HERE>'
tag_desc = 'This is a tag description'
tag_owner = '<INSERT USER ID HERE>' # User ID, not user name.
tag_color = '#648d9f'  # Color as hex value
tag_locked = False
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "fields": [
        {
            "uid": "TAG_TYPE",
            "value": tag_type
        },
        {
            "uid": "NAME",
            "value": tag_name
        },
        {
            "uid": "DESCRIPTION",
            "value": tag_desc
        },
        {
            "uid": "OWNER",
            "value": tag_owner
        },
        {
            "uid": "COLOR",
            "value": tag_color
        },
        {
            "uid": "LOCKED",
            "value": tag_locked
        }
    ]
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/" + str(tag_id)
​
response = requests.put(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token

cURL

cURL Sample update_tag Snippet

Copy 

curl -X PUT "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json" -d "{  \"fields\": [    {      \"uid\": \"TAG_TYPE\",      \"value\": \"<TAGTYPE>\"    },    {      \"uid\": \"NAME\",      \"value\": \"<TAGNAME>\"    },    {      \"uid\": \"DESCRIPTION\",      \"value\": \"<DESCRIPTION>\"    },    {      \"uid\": \"OWNER\",      \"value\": \"<OWNER>\"    },    {      \"uid\": \"COLOR\",      \"value\": \"<COLOR>\"    },    {      \"uid\": \"LOCKED\",      \"value\": <LOCKED>    }  ]}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token
TAGTYPE Tag Type. Options: Compliance, Location, Custom, Remediation, People, Project, Scanner, CMDB.
TAGNAME Tag name.
DESCRIPTION Tag description.
OWNER Tag owner. Use User ID.
COLOR Tag color. Use Hex value.
LOCKED Is tag locked? Options: True = Yes, False = No

Response Parameters

Sample Response

Copy 
{
  "id": <ID>,
  "tag": {
    "uid": "string",
    "value": {},
    "legacyLink": "string"
  }
}

Name Description Type
ID Tag ID number. integer
UID Tag UID. string
VALUE Field value. string

HTTP Status Codes

Code Description
200 Success

200 Sample Response

Copy 
{
  "id": 0,
  "tag": {
    "uid": "string",
    "value": {},
    "legacyLink": "string"
  }
}
Code Description
400 User Error

400 Sample Response

Copy 
{
  "status": 0,
  "path": "string",
  "errors": [
    {
      "field": "string",
      "code": "string"
    }
  ]
}
Code Description
401 Unauthorized
404 Not Found
409 Conflict

Deleting a Tag

Delete a tag from the client.

API Call: DELETE/client/{clientId}/tag/{tagId}

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID
TAGID Tag ID number.

User Roles

The user roles that can delete a tag are:

  • Group Manager
  • Manager
  • User

Python

Python Sample delete_tag Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
tag_id = <INSERT TAG ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "forceDeleteTicket": True
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/" + str(tag_id)
​
response = requests.delete(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample delete_tag Snippet

Copy 

curl -X DELETE "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json" -d "{  \"forceDeleteTicket\": <FORCEDELETETICKET>}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
TAGID Tag ID number.
APIKEY Your designated API key. Generating an API Token
FORCEDELETETICKET Force delete associated ticket. Options: True = Yes, False = No

HTTP Status Codes

Code Description
204 Delete request was processed without errors
401 Unauthorized

Retrieving a Paginated List of a Tag's History

Retrieve a tag's history in paginated list form.

API Call: GET/client/{clientId}/tag/{tagId}/history

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>/history

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID
TAGID Tag ID number.

User Roles

The user roles that can retrieve a tag's history in paginated list form are:

  • Group Manager
  • Manager
  • User

Python

Python Sample tag_history Snippet

Copy 

import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
tag_id = <INSERT TAG ID HERE>
​
page_num = 0
page_size = 50
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
params = {
    "size": page_size,
    "page": page_num
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/" + str(tag_id) +"/history"
​
response = requests.get(url, headers=header, params=params)

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token

cURL

cURL Sample tag_history Snippet

Copy 

curl -X GET "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/<TAGID>/history?size=<SIZE>&page=<NUMBER>"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
TAGID Tag ID number.
SIZE Page size requested. Shows how many items to display on the page.
NUMBER Page to view. Note that 0 is the first page.
APIKEY Your API key. Generating an API Token

Response Parameters

Sample Response

Copy 

{
  "_embedded": {
    "tagHistories": [
      {
        "tagId": <TAGID>,
        "log": "<LOG>",
        "created": "<CREATED>"
      }
    ]
  },
  "page": {
    "size": <SIZE>,
    "totalElements": <TOTALELEMENTS>,
    "totalPages": <TOTALPAGES>,
    "number": <NUMBER>
  }
}

Name Description Additional Information
TAGID Tag ID number. integer
LOG Tag history string
CREATED Date/time created. string($date-time)
SIZE Page size requested. integer
TOTALELEMENTS Total viewable elements. integer
TOTALPAGES Total page count. integer
NUMBER Page to view. Note that 0 is the first page.

HTTP Status Codes

Code Description
200 Success

200 Sample Response

Copy 
{
  "_embedded": {
    "tagHistories": [
      {
        "tagId": 0,
        "log": "string",
        "created": "2019-09-17T16:12:36.288Z"
      }
    ]
  },
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}
Code Description
401 Unauthorized
404 Not Found

Listing Tag Projections and Their Models

List tag projections and their models that can be requested from the search endpoint.

API Call: GET/client/{clientId}/tag/model

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/model

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can list tag projections and their models are:

  • Manager
  • Group Manager
  • User

Python

Python Sample tag_projections Snippet

Copy 

import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/model"
​
response = requests.get(url, headers=header)

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample tag_projections Snippet

Copy 

curl -X GET "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/model"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

Response Parameters

Sample Response

Copy 
{
  "subject": "tag",
  "projections": [
    {
      "name": "basic",
      "fields": [
        {
          "field": "id",
          "type": "int",
          "nested": []
        },
        {
          "field": "name",
          "type": "string",
          "nested": []
        },
        {
          "field": "type",
          "type": "string",
          "nested": []
        },
        {
          "field": "description",
          "type": "string",
          "nested": []
        },
        {
          "field": "priority",
          "type": "Object",
          "nested": []
        },
        {
          "field": "locked",
          "type": "boolean",
          "nested": []
        },
        {
          "field": "readOnly",
          "type": "boolean",
          "nested": []
        },
        {
          "field": "startDate",
          "type": "string",
          "nested": []
        },
        {
          "field": "dueDate",
          "type": "string",
          "nested": []
        },
        {
          "field": "daysRemaining",
          "type": "Object",
          "nested": []
        },
        {
          "field": "totalFindingCount",
          "type": "Object",
          "nested": []
        },
        {
          "field": "openFindingCount",
          "type": "Object",
          "nested": []
        },
        {
          "field": "percentageComplete",
          "type": "Object",
          "nested": []
        },
        {
          "field": "created",
          "type": "string",
          "nested": []
        },
        {
          "field": "updated",
          "type": "string",
          "nested": []
        }
      ]
    }
  ]
}
Name Description Additional Information
ID Tag ID number. integer
NAME Tag name. string
TYPE Tag type. string
DESCRIPTION Tag description. string
PRIORITY Tag Priority Object
LOCKED Is tag locked? boolean Options: True = Yes, False = No
READONLY Is the tag read only? boolean Options: True = Yes, False = No
STARTDATE Tag start date. string
DUEDATE Tag due date. string
DAYSREMAINING Days remaining. Object
TOTALFINDINGCOUNT Total finding count. Object
OPENFINDINGCOUNT Open finding count. Object
PERCENTAGECOMPLETE Percentage complete. Object
CREATED Created date/time. string
UPDATED Updated date/time. string

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy 
{
  "projections": [
    {
      "name": "basic",
      "fields": [
        {
          "field": "id",
          "type": "integer"
        },
        {
          "field": "name",
          "type": "string"
        }
      ]
    }
  ]
}
Code Description
401 Unauthorized
404 Not Found

Listing Filterable Tag Fields

Displays the filterable tag fields that can be used by the search endpoint.

API Call: GET/client/{clientId}/tag/filter

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/filter

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can list filterable tag fields are:

  • Manager
  • Group Manager
  • User

Python

Python Sample list_tagfields Snippet

Copy 

import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/filter"
​
response = requests.get(url, headers=header)

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample list_tagfields Snippet

Copy 

curl -X GET "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/filter"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

Response Parameters

Sample Response

Copy 

[
  {
    "name": "Application Finding Count",
    "legacyUid": "APPLICATION_FINDING_COUNT",
    "uid": "applicationFindingCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The total number of open application findings that belong to a tag."
  },
  {
    "name": "Assigned User",
    "legacyUid": "ASSIGNED_USERS",
    "uid": "ASSIGNED_USERS",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "The users assigned to any findings that belong to a tag."
  },
  {
    "name": "Created",
    "legacyUid": "CREATED",
    "uid": "created",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "date",
    "description": "The date the tag was created."
  },
  {
    "name": "Database Finding Count",
    "legacyUid": "DATABASE_FINDING_COUNT",
    "uid": "databaseFindingCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The total number of open database findings that belong to a tag."
  },
  {
    "name": "Days Remaining",
    "legacyUid": "DAYS_REMAINING",
    "uid": "daysRemaining",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The number of days remaining in the schedule for a tag."
  },
  {
    "name": "Description",
    "legacyUid": "DESCRIPTION",
    "uid": "DESCRIPTION",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "The description given to the tag."
  },
  {
    "name": "Due Date",
    "legacyUid": "DUE_DATE",
    "uid": "dueDate",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "date",
    "description": "The due date of a tag."
  },
  {
    "name": "Has Ticket",
    "legacyUid": "HAS_CONNECTOR_TICKET",
    "uid": "HAS_CONNECTOR_TICKET",
    "operators": [
      "EXACT"
    ],
    "type": "boolean",
    "description": "Does the tag have a ticket"
  },
  {
    "name": "Host Finding Count",
    "legacyUid": "HOST_FINDING_COUNT",
    "uid": "hostFindingCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The total number of open host findings that belong to a tag."
  },
  {
    "name": "Is Locked",
    "legacyUid": "LOCKED",
    "uid": "LOCKED",
    "operators": [
      "EXACT"
    ],
    "type": "boolean",
    "description": "The tag is locked to any changes."
  },
  {
    "name": "Is PCI",
    "legacyUid": "PCI",
    "uid": "PCI",
    "operators": [
      "EXACT"
    ],
    "type": "boolean",
    "description": "Determine whether tag type is PCI"
  },
  {
    "name": "Is Read Only",
    "legacyUid": "READ_ONLY",
    "uid": "READ_ONLY",
    "operators": [
      "EXACT"
    ],
    "type": "boolean",
    "description": "The tag is read only."
  },
  {
    "name": "Is System Locked",
    "legacyUid": "SYSTEM_LOCKED",
    "uid": "SYSTEM_LOCKED",
    "operators": [
      "EXACT"
    ],
    "type": "boolean",
    "description": "Determine whether tag is locked by system"
  },
  {
    "name": "Name",
    "legacyUid": "NAME",
    "uid": "name",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "The name of the tag."
  },
  {
    "name": "Open Finding Count",
    "legacyUid": "OPEN_FINDING_COUNT",
    "uid": "openFindingCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The number of open findings that belong to a tag."
  },
  {
    "name": "Owner",
    "legacyUid": "OWNER",
    "uid": "OWNER",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "The user who owns the tag."
  },
  {
    "name": "Priority",
    "legacyUid": "PRIORITY",
    "uid": "priority",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The priority given to the tag."
  },
  {
    "name": "Schedule Earned Value",
    "legacyUid": "SCHEDULE_EARNED_VALUE",
    "uid": "SCHEDULE_EARNED_VALUE",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The current number of closed findings for a tag."
  },
  {
    "name": "Schedule Percent Complete",
    "legacyUid": "SCHEDULE_PERCENTAGE_COMPLETE",
    "uid": "percentageComplete",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "double",
    "description": "The completion percentage for a tag, based on total number of closed findings versus total findings for the tag."
  },
  {
    "name": "Schedule Performance Index",
    "legacyUid": "SCHEDULE_PERFORMANCE_INDEX",
    "uid": "SCHEDULE_PERFORMANCE_INDEX",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "double",
    "description": "The ratio of the earned value to planned value for a tag."
  },
  {
    "name": "Schedule Planned Value",
    "legacyUid": "SCHEDULE_PLANNED_VALUE",
    "uid": "SCHEDULE_PLANNED_VALUE",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The expected number of closed findings for a tag."
  },
  {
    "name": "Schedule Variance",
    "legacyUid": "SCHEDULE_VARIANCE",
    "uid": "SCHEDULE_VARIANCE",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The variance of the current status from the project status for a tag."
  },
  {
    "name": "Start Date",
    "legacyUid": "START_DATE",
    "uid": "startDate",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "date",
    "description": "The start date of a tag."
  },
  {
    "name": "Tag Connector ID",
    "legacyUid": "TAG_CONNECTOR_ID",
    "uid": "TAG_CONNECTOR_ID",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "Tag Connector ID"
  },
  {
    "name": "Tag Connector Name",
    "legacyUid": "TAG_CONNECTOR_NAME",
    "uid": "TAG_CONNECTOR_NAME",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "Name of the Connector associated with the tag"
  },
  {
    "name": "Tag Type",
    "legacyUid": "TAG_TYPE",
    "uid": "type",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "The type of the tag."
  },
  {
    "name": "Ticket ID",
    "legacyUid": "TICKET_ID",
    "uid": "TICKET_ID",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "Ticket ID"
  },
  {
    "name": "Ticket Status",
    "legacyUid": "TICKET_STATUS",
    "uid": "TICKET_STATUS",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "status of ticket"
  },
  {
    "name": "Total Finding Count",
    "legacyUid": "TOTAL_FINDING_COUNT",
    "uid": "totalFindingCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "integer",
    "description": "The total number of findings tha belong to a tag."
  },
  {
    "name": "Updated",
    "legacyUid": "UPDATED",
    "uid": "updated",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "date",
    "description": "The date the core information about the tag was last updated."
  }
]

Name Description Additional Information
APPLICATIONFINDINGCOUNT The total number of open application findings that belong to a tag. Operators: Exact, In, Range
ASSIGNEDUSER The users assigned to any findings that belong to a tag. Operators: Exact, In, Like, Wildcard
CREATED The date the tag was created. Operators: Exact, In, Like, Wildcard
DATABASEFINDINGCOUNT The total number of open database findings that belong to a tag. Operators: Exact, In, Range
DAYSREMAINING The number of days remaining in the schedule for a tag. Operators: Exact, In, Range
DESCRIPTION Tag description. Operators: Exact, In, Like, Wildcard
DUEDATE Tag due date. Operators: Exact, In, Like, Wildcard
HASTICKET Does the tag have a ticket? Operators: Exact
HOSTFINDINGCOUNT Total number of open host findings belonging to a tag. Operators: Exact, In, Range
ISLOCKED Is the tag locked? Operators: Exact
ISPCI Is the tag a PCI tag? Operators: Exact
ISREADONLY Is the tag read only? Operators: Exact
ISSYSTEMLOCKED Is the tag system locked? Operators: Exact
NAME Tag name. Operators: Exact, In, Like, Wildcard
OPENFINDINGCOUNT Number of open findings belonging to a tag. Operators: Exact, In, Range
OWNER User who owns the tag. Operators: Exact, In, Like, Wildcard
PRIORITY Tag priority. Operators: Exact, In, Range
SCHEDULEEARNEDVALUE The current number of closed findings for a tag. Operators: Exact, In, Range
SCHEDULEPERCENTCOMPLETE The completion percentage for a tag, based on total number of closed findings versus total findings for the tag. Operators: Exact, In, Range
SCHEDULEPERFORMANCEINDEX The ratio of the earned value to planned value for a tag. Operators: Exact, In, Range
SCHEDULEPLANNEDVALUE The expected number of closed findings for a tag. Operators: Exact, In, Range
SCHEDULEVARIANCE The variance of the current status from the project status for a tag. Operators: Exact, In, Range
STARTDATE Tag start date. Operators: Exact, In, Like, Wildcard
TAGCONNECTORID Tag connector ID. Operators: Exact, In, Like, Wildcard
TAGCONNECTORNAME Tag connector name. Operators: Exact, In, Like, Wildcard
TAGTYPE Tag type. Operators: Exact, In, Like, Wildcard
TICKETID Ticket ID. Operators: Exact, In, Like, Wildcard
TICKETSTATUS Ticket status. Operators: Exact, In, Like, Wildcard
TOTALFINDINGCOUNT The total number of findings belonging to a tag. Operators: Exact, In, Range
UPDATED The date the core information about the tag was last updated. Operators: Exact, In, Like, Wildcard

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy 
[
  {
    "name": "id",
    "uid": "id",
    "operator": [
      "EXACT",
      "IN"
    ],
    "type": "integer",
    "description": "The id"
  }
]
Code Description
401 Unauthorized
404 Not Found

Suggesting Filter Values for Tag Filtering

Displays suggested filter values when filtering tags.

API Call: POST/client/{clientId}/tag/suggest

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/suggest

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can view suggested filter values for tags are:

  • Manager
  • Group Manager
  • User

Python

Python Sample filter_tagvalues Snippet

Copy 

import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "filters": [
        {
            "field": "id",
            "exclusive": True,
            "operator": "IN",
            "value": "1,2,3,4"
        }
    ]
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/suggest"
​
response = requests.post(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample filter_tagvalues Snippet

Copy 

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/suggest"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json"
  -d "{  \"filters\": [    {      \"field\": \"<FIELD>\",      \"exclusive\": <EXCLUSIVE>,      \"operator\": \"<OPERATOR>\",      \"value\": \"<VALUE>\"    }  ],  \"filter\": {    \"field\": \"<FIELD>\",    \"exclusive\": <EXCLUSIVE>,    \"operator\": \"<OPERATOR>\",    \"value\": \"<VALUE>\"  }}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.  
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token
FIELD Filter field. string
EXCLUSIVE Exclusive. boolean Options: True, False
OPERATOR Search operator. Depends on value.
VALUE Search value. string

Response Parameters

Sample Response

Copy 

[
  {
    "key": "string",
    "count": 0
  }
]

Name Description Additional Information
KEY Value for the field the suggestion was requested for. string
COUNT Count. integer($int64)

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy 
[
  {
    "key": "string",
    "count": 0
  }
]
Code Description
400 Bad Request
401 Unauthorized
404 Not Found

Searching for a Tag

Search for a tag within the designated client.

API Call: POST/client/{clientId}/tag/search

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/search

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can search for a tag are:

  • Manager
  • Group Manager
  • User

Python

Python Sample search_tag Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "filters": [
        {
            "field": "id",
            "exclusive": False,
            "operator": "IN",
            "value": "1,2,3,4"
        }
    ],
    "projection": "basic",
    "sort": [
        {
            "field": "id",
            "direction": "ASC"
        }
    ],
    "page": 0,
    "size": 20
}
​
url = platform + "/api/v1/client/" + str(client_id) + "/tag/search"
​
response = requests.post(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token

cURL

cURL Sample search_tag Snippet

Copy 

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/search"
  -H "accept: application/json"
  -H "x-api-key: <APIKEY>"
  -H "Content-Type: application/json"
  -d "{ \"projection\": \"<PROJECTION>\", \"sort\": [ { \"field\": \"<SORTFIELD>\", \"direction\": \"<SORTDIRECTION>\" } ], \"page\": <PAGENUMBER>, \"size\": <PAGESIZE>}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your API key. Generating an API Token
PROJECTION Projection type. Options: basic, detailed
SORTFIELD Field to sort.
SORTDIRECTION Sort direction. Options: ASC, DESC
PAGENUMBER Page number to view.
PAGESIZE Number of entries per page.

Response Parameters

Sample Response

Copy 

{
  "errors": [],
  "page": {
    "size": <PAGESIZE>,
    "totalElements": <TOTALELEMENTS>,
    "totalPages": <TOTALPAGES>,
    "number": <PAGENUMBER>
  },
  "_links": {
    "self": {
      "href": "http://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/applicationUniqueFinding/search?page=<PAGENUMBER>&size=<PAGESIZE>&sort=<SORT>,<SORTDIRECTION>"
    }
  }
}

Name Description Additional Information
PAGESIZE Page size requested. Shows how many items to display on the page.
TOTALELEMENTS Total elements on pages.
TOTALPAGES Total amount of pages.
PAGENUMBER Page to view. Note that 0 is the first page.
PLATFORM Platform number.
CLIENTID Client ID number.
SORT Field to sort by.
SORTDIRECTION Direction to sort. Options: ASC, DESC

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy 
{
  "_embedded": {
    "strings": [
      {}
    ]
  },
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  },
  "errors": [
    {
      "id": "string",
      "errorRefId": "string",
      "code": 0,
      "cause": "string"
    }
  ]
}
Code Description
400 Bad Request
401 Unauthorized
404 Not Found

Initiating a Tag Export Job

Initiate tag export job.

API Call: POST/client/{clientId}/tag/export

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/export

URL Parameters

Name Description Additional Information
PLATFORM Platform number. If you are on platform 1, you do not need to put a number.
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can initiate a tag export job are:

  • Group Manager
  • Manager
  • User

Python

Python Sample tag_export Snippet

Copy 

import json
import requests
​
platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>
​
file_type = "CSV"
file_name = "<INSERT FILE NAME HERE>"
comment = "This is a comment."
​
header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
​
body = {
    "filterRequest": {
        "filters": [
            {
                "field": "id",
                "exclusive": False,
                "operator": "IN",
                "value": "1,2,3,4"
            }
        ]
    },
    "fileType": file_type,
    "comment": comment,
    "fileName": file_name
}

url = platform + "/api/v1/client/" + str(client_id) + "/tag/export"
​
response = requests.post(url, headers=header, data=json.dumps(body))

Make sure to replace the angle bracket parameters here with your own values.

Python Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token

cURL

cURL Sample tag_export Snippet

Copy 

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/tag/export"
  -H  "accept: application/json"
  -H  "x-api-key: <APIKEY>"
  -H  "Content-Type: application/json" -d "{  \"filterRequest\": {    \"filters\": [      {        \"field\": \"<FIELD>\",        \"exclusive\": <EXCLUSIVE>,        \"operator\": \"<OPERATOR>\",        \"value\": \"<VALUE>\"      }    ]  },  \"fileType\": \"<FILETYPE>\",  \"comment\": \"<COMMENT>\",  \"fileName\": \"<FILENAME>\"}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Additional Information
PLATFORM Platform number.
CLIENTID Client ID number. Finding Your Client ID
APIKEY Your designated API key. Generating an API Token
FIELD Filter field. string
EXCLUSIVE Exclusive. boolean Options: True, False
OPERATOR Search operator. Depends on value.
VALUE Search value. string
COMMENT Comment. string
FILENAME File name. string

Response Parameters

Sample Response

Copy 

{
  "id": <ID>,
  "created": "<CREATED>"
}

Name Description Additional Information
ID Job ID number. integer
Created Date/Time job created. string($date-time)

HTTP Status Codes

Code Description
201 Success

201 Sample Response

Copy 
{
  "id": 0,
  "created": "2019-09-17T14:56:02.463Z"
}
Code Description
400 Bad Request
401 Unauthorized
404 Not Found