UpGuard vendors API
The vendors API from UpGuard — 32 operation(s) for vendors.
OpenAPI Specification
swagger: '2.0'
info:
description: 'Access information from the CyberRisk platform programmatically using this API.
You can find or generate an API key to access this API in your CyberRisk Account Settings.
Please authorize all requests by setting the "Authorization" header to your api key.
The base url for all public endpoints is https://cyber-risk.upguard.com/api/public'
title: UpGuard CyberRisk breaches vendors API
version: 1.13.2
host: cyber-risk.upguard.com
basePath: /api/public
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- API key in header: []
tags:
- name: vendors
paths:
/fourth_party/list:
get:
description: 'Returns a paginated list of fourth party (supply chain / concentration risk) vendors and their products
for the watched vendors in your organisation.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List fourth party vendors
operationId: fourth_parties_params
parameters:
- type: integer
format: int64
description: 'The number of results to return per page.
Valid values range from 10 to 2000.
Defaults to 500 if unset.'
name: page_size
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- type: array
items:
type: string
description: Filter by label names. Only vendors with all of the provided labels will be returned. If a label does not exist, 422 will be returned.
name: labels
in: query
- type: array
items:
type: integer
format: int64
description: Filter by vendor tier. Only vendors in the specified tiers will be returned.
name: tier
in: query
- type: integer
format: int64
description: 'Filter by watched vendor score. Only fourth party vendors used by watched vendors with a
score greater than or equal to this value will be returned.
Valid range: 0-950.'
name: min_score
in: query
- type: integer
format: int64
description: 'Filter by watched vendor score. Only fourth party vendors used by watched vendors with a
score less than or equal to this value will be returned.
Valid range: 0-950.'
name: max_score
in: query
- type: array
items:
type: string
description: Filter by portfolio names. Only vendors in these portfolios will be returned. If a portfolio does not exist, 422 will be returned.
name: portfolios
in: query
responses:
'200':
description: ''
schema:
$ref: '#/definitions/GetFourthPartiesV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/onboarding_request:
get:
description: 'Returns detailed information about a specific vendor onboarding request, including vendor data and assessment links.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Get onboarding request details
operationId: onboardingRequestGet
parameters:
- type: integer
format: int64
example: 12345
description: The ID of the onboarding request (survey ID)
name: id
in: query
required: true
responses:
'200':
description: Onboarding request details response
schema:
$ref: '#/definitions/OnboardingRequestDetail'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'404':
description: The vendor was not found.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/onboarding_request/list:
get:
description: 'Returns a paginated list of vendor onboarding requests for the organization.
Note: The id of the onboarding request is also the survey_id of the corresponding onboarding request questionnaire.
You can download the question and answers of the onboarding request questionnaire using Get questionnaire questions and answers
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List onboarding requests
operationId: onboardingRequestsList
parameters:
- type: integer
format: int64
example: 100
description: Number of results per page (1-2000)
name: page_size
in: query
- type: string
description: Token for the next page of results
name: page_token
in: query
- enum:
- vendor_name
- status
- created_at
- completed_at
- progress
- submitted_by
type: string
example: created_at
description: 'Field to sort by
Sort order for status is: Complete, Sent, In Progress, In Review, Assessment Underway, Awaiting Review
Sort by submitted_by sorts by the name of the submitter'
name: sort_by
in: query
- type: boolean
example: true
description: Sort in descending order, sorts in ascending order if unset
name: sort_desc
in: query
- type: string
example: Assessment Underway,Complete
description: 'Comma-separated list of statuses to filter by
Valid values: Complete,Sent,In Progress,In Review,Assessment Underway,Awaiting Review'
name: status
in: query
- type: boolean
example: false
description: Filter by archived status
name: archived
in: query
- type: string
example: acme
description: Text to search for in vendor name or submitter name
name: filter_text
in: query
responses:
'200':
description: List of onboarding requests
schema:
$ref: '#/definitions/OnboardingRequestsListRespBody'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor:
get:
description: 'The following assertions are evaluated (in order) to determine whether you are licensed to view the vendor data (as soon as one assertion returns "true", the vendor data will be returned):
1. You are currently monitoring the vendor in CyberRisk
2. You have set "start_monitoring" to "true" AND are not currently monitoring all the vendors you are licensed for in CyberRisk
3. You have set "generate_ad_hoc_report" to "true" and have not currently used your monthly allocation of ad-hoc reports in CyberRisk.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Get vendor details
operationId: vendor
parameters:
- type: integer
format: int64
example: 123456789
description: The ID of the vendor for which to return vendor data. e.g. 123456789
name: id
in: query
- type: string
example: upguard.com
description: 'The hostname for which to return vendor data. e.g. "upguard.com".
Required when id is not specified. When id is specified this field will be ignored.'
name: hostname
in: query
- type: boolean
description: 'When set to true, if you haven''t already used your monthly allocation of ad-hoc reports,
generate an ad-hoc report for the given vendor, and return the vendor data.'
name: generate_ad_hoc_report
in: query
- type: boolean
description: 'NOTE: deprecated (use vendor/monitor instead).
When set to true, if the vendor is not already being monitored,
and if you are not already monitoring all the vendors your are licensed for,
start monitoring the vendor, and return the vendor data.'
name: start_monitoring
in: query
- type: array
items:
type: string
description: 'NOTE: deprecated (use vendor/monitor instead).
The labels to assign to the vendor if start monitoring set to true.
If you want to update the labels for an already monitored vendor use the /vendor/labels endpoint.'
name: labels
in: query
- type: integer
format: int64
description: 'NOTE: deprecated (use vendor/monitor instead).
The tier to assign to the vendor if start monitoring is set to true.'
name: tier
in: query
- type: boolean
default: false
description: Flag indicating whether the request should wait for scan results on new unknown vendors
name: wait_for_scan
in: query
responses:
'200':
description: Vendor details
schema:
$ref: '#/definitions/vendor'
'202':
description: The vendor does not currently exist in the system and has been scheduled for addition
'402':
description: You are not allowed to access the vendor for licensing reasons.
schema:
$ref: '#/definitions/endpointError'
'404':
description: The vendor was not found.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/additionalevidence:
get:
description: 'Returns the body of one or more additional evidence documents that have been attached to a specific vendor.
If multiple additional evidence documents are requested, then by default the files are returned as a multi-part mime response.
Alternately, the zip option can be used to return multiple files as a single zip archive'
produces:
- image/jpeg
- image/png
- application/octet-stream
- 'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Retrieve (one or more) vendor additional evidence documents by id
operationId: additional_evidence
parameters:
- type: array
items:
type: integer
format: int64
description: a comma-separated list of one or more additional evidence instances (by unique id)
name: evidence_ids
in: query
- type: boolean
description: indicates that for multiple additional evidence requests, the files should be returned as a multi-file zip
name: zip
in: query
responses:
'200':
description: Vendors additional evidence
schema:
$ref: '#/definitions/GetVendorAdditionalEvidenceResponsePayload'
'300':
description: Request requires multipart receipt ability
schema:
$ref: '#/definitions/endpoint300Error'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/additionalevidence/list:
get:
description: 'Returns a list of additional evidence instances that have been uploaded against this vendor in chronological order of when they were uploaded.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List vendor additional evidence instances
operationId: additional_evidences_list
parameters:
- type: string
description: The primary hostname of the vendor to show additional evidence for.
name: vendor_primary_hostname
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- type: integer
format: int64
description: 'The number of results to return per page.
Valid values range from 10 to 2000.
Defaults to 1000 if unset.'
name: page_size
in: query
responses:
'200':
description: Vendor additional evidences list
schema:
$ref: '#/definitions/GetVendorAdditionalEvidencesResponsePayload'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/attributes:
put:
description: 'Assign or update the attributes for a vendor. To remove an attribute use null as its value in the payload.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Assign or update the attributes for a vendor
operationId: vendor_update_attributes
parameters:
- name: UpdateVendorAttributesV1RequestBody
in: body
schema:
$ref: '#/definitions/UpdateVendorAttributesV1RequestBody'
responses:
'204':
description: ' Successful response is empty'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/contact:
get:
description: 'Returns the vendor contact details for the given contact ID.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Get a vendor contact by ID
operationId: vendor_contact_get
parameters:
- type: integer
format: int64
description: The id of the vendor contact to retrieve.
name: id
in: query
required: true
responses:
'200':
description: Returns the vendor contact details.
schema:
$ref: '#/definitions/VendorContact'
'403':
description: Your API key does not have permission to perform this action, or the contact does not exist.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/contact/list:
get:
description: 'Returns a list of vendor contacts for a given vendor.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List vendor contacts
operationId: vendor_contact_list
parameters:
- type: integer
format: int64
description: The id of the vendor to retrieve contacts for.
name: vendor_id
in: query
- type: string
description: The primary hostname of the vendor to retrieve contacts for.
name: vendor_primary_hostname
in: query
- type: string
description: The `page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
responses:
'200':
description: Returns a list of contacts for a vendor.
schema:
$ref: '#/definitions/VendorContactList'
'403':
description: Your API key does not have permission to perform this action, or the contact does not exist.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/document:
get:
description: 'Returns the body of one or more documents that have been attached to a specific vendor.
If multiple documents are requested, then by default the files are returned as a multi-part mime response.
Alternately, the zip option can be used to return multiple files as a single zip archive'
produces:
- image/jpeg
- image/png
- application/octet-stream
- 'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Retrieve (one or more) vendor documents by id
operationId: document
parameters:
- type: array
items:
type: integer
format: int64
description: a comma-separated list of one or more documents (by unique id)
name: document_ids
in: query
- type: boolean
description: indicates that for multiple document requests, the files should be returned as a multi-file zip
name: zip
in: query
responses:
'200':
description: Vendors document
schema:
$ref: '#/definitions/GetVendorDocumentResponsePayload'
'300':
description: Request requires multipart receipt ability
schema:
$ref: '#/definitions/endpoint300Error'
'403':
description: Account does not have access to requested entities
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/documents:
get:
description: 'Returns a list of documents that have been uploaded against this vendor in chronological order of when they were uploaded.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List vendor documents
operationId: documents
parameters:
- type: string
description: The primary hostname of the vendor to show documents for.
name: vendor_primary_hostname
in: query
- type: string
description: 'The token of the page to be returned.
Will return the first page if left blank.'
name: page_token
in: query
- type: integer
format: int64
description: 'The number of results to return per page.
Valid values range from 10 to 2000.
Defaults to 1000 if unset.'
name: page_size
in: query
responses:
'200':
description: Vendor documents
schema:
$ref: '#/definitions/GetVendorDocumentsResponsePayload'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/domain:
get:
description: 'Returns the details for a domain. It will return 422 when requesting details of an inactive domain.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Retrieve details for a domain
operationId: vendor_domain_details
parameters:
- type: string
description: The primary hostname of the vendor to show the domain detail for.
name: vendor_primary_hostname
in: query
required: true
- type: string
description: The hostname for which to return the details, e.g. "upguard.com"
name: hostname
in: query
required: true
responses:
'200':
description: Domain details
schema:
$ref: '#/definitions/GetDomainDetailsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/domain/labels:
put:
description: 'Assign labels to a domain. To remove all labels pass an empty list.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Assign labels to a domain
operationId: vendor_domain_update_labels
parameters:
- type: string
description: The primary hostname of the vendor to update the domain labels for.
name: vendor_primary_hostname
in: query
required: true
- type: string
description: The hostname to update labels for
name: hostname
in: query
required: true
- type: array
items:
type: string
description: The labels to assign to the domain. You can pass an empty array to remove all labels.
name: labels
in: query
required: true
responses:
'204':
description: ' Successful response is empty'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/domains:
get:
description: 'Returns a list of domains for a vendor.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List vendor domains
operationId: vendor_domains
parameters:
- type: string
description: The primary hostname of the vendor to show domains for.
name: vendor_primary_hostname
in: query
required: true
- type: boolean
default: true
description: Retrieve active domains
name: active
in: query
- type: boolean
default: true
description: Retrieve inactive domains
name: inactive
in: query
- type: array
items:
type: string
description: Filter result by the provided labels
name: labels
in: query
- type: string
description: The `page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
- maximum: 2000
minimum: 10
type: integer
format: int64
default: 1000
description: The number of results to return per page.
name: page_size
in: query
- enum:
- domain
- active
- automated_score
- scanned_at
type: string
default: domain
description: 'The value to sort the domains by
If not specified will default to `domain` and set `sort_desc` to `true`'
name: sort_by
in: query
- type: boolean
default: false
description: Whether or not to sort the results in descending order
name: sort_desc
in: query
responses:
'200':
description: A list of domains
schema:
$ref: '#/definitions/GetDomainsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/ip:
get:
description: 'Returns the details of the IP address. It will return 422 when requesting details of an inactive IP address.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Retrieve details for an IP address
operationId: vendor_ip_details
parameters:
- type: string
description: The primary hostname of the vendor to show the IP detail for.
name: vendor_primary_hostname
in: query
required: true
- type: string
description: The IP address to get details for
name: ip
in: query
required: true
responses:
'200':
description: IP details
schema:
$ref: '#/definitions/GetIpDetailsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/ip/labels:
put:
description: 'Assign labels to an IP. To remove all labels pass an empty list.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: Assign labels to an IP
operationId: vendor_ip_update_labels
parameters:
- type: string
description: The primary hostname of the vendor to update the IP labels for.
name: vendor_primary_hostname
in: query
required: true
- type: integer
format: int64
description: The IP to update labels for
name: ip
in: query
required: true
- type: array
items:
type: string
description: The labels to assign to the IP. You can pass an empty array to remove all labels.
name: labels
in: query
required: true
responses:
'204':
description: ' Successful response is empty'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/vendor/ips:
get:
description: 'Returns a list of ips for a vendor.
Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)'
tags:
- vendors
summary: List vendor ips
operationId: vendor_ips
parameters:
- type: string
description: The primary hostname of the vendor to show ips for.
name: vendor_primary_hostname
in: query
required: true
- type: array
items:
type: string
description: Filter result by the provided labels
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upguard/refs/heads/main/openapi/upguard-vendors-api-openapi.yml