UpGuard vendors API

openapi: 3.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
servers:
- url: https://cyber-risk.upguard.com/api/public
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:
      - 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
        schema:
          type: integer
          format: int64
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          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
        schema:
          type: array
          items:
            type: string
      - description: Filter by vendor tier. Only vendors in the specified tiers will be returned.
        name: tier
        in: query
        schema:
          type: array
          items:
            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
        schema:
          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
        schema:
          type: integer
          format: int64
      - 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
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFourthPartiesV1RespBody'
        '403':
          description: Your API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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:
      - example: 12345
        description: The ID of the onboarding request (survey ID)
        name: id
        in: query
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Onboarding request details response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRequestDetail'
        '403':
          description: Account does not have access to requested entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: The vendor was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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:
      - example: 100
        description: Number of results per page (1-2000)
        name: page_size
        in: query
        schema:
          type: integer
          format: int64
      - description: Token for the next page of results
        name: page_token
        in: query
        schema:
          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
        schema:
          type: string
          enum:
          - vendor_name
          - status
          - created_at
          - completed_at
          - progress
          - submitted_by
      - example: true
        description: Sort in descending order, sorts in ascending order if unset
        name: sort_desc
        in: query
        schema:
          type: boolean
      - 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
        schema:
          type: string
      - example: false
        description: Filter by archived status
        name: archived
        in: query
        schema:
          type: boolean
      - example: acme
        description: Text to search for in vendor name or submitter name
        name: filter_text
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of onboarding requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRequestsListRespBody'
        '403':
          description: Account does not have access to requested entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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:
      - example: 123456789
        description: The ID of the vendor for which to return vendor data. e.g. 123456789
        name: id
        in: query
        schema:
          type: integer
          format: int64
      - 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
        schema:
          type: string
      - 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
        schema:
          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
        schema:
          type: boolean
      - 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
        schema:
          type: array
          items:
            type: string
      - 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
        schema:
          type: integer
          format: int64
      - description: Flag indicating whether the request should wait for scan results on new unknown vendors
        name: wait_for_scan
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Vendor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '404':
          description: The vendor was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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'
      tags:
      - vendors
      summary: Retrieve (one or more) vendor additional evidence documents by id
      operationId: additional_evidence
      parameters:
      - description: a comma-separated list of one or more additional evidence instances (by unique id)
        name: evidence_ids
        in: query
        schema:
          type: array
          items:
            type: integer
            format: int64
      - description: indicates that for multiple additional evidence requests, the files should be returned as a multi-file zip
        name: zip
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Vendors additional evidence
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/GetVendorAdditionalEvidenceResponsePayload'
            image/png:
              schema:
                $ref: '#/components/schemas/GetVendorAdditionalEvidenceResponsePayload'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/GetVendorAdditionalEvidenceResponsePayload'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/GetVendorAdditionalEvidenceResponsePayload'
        '300':
          description: Request requires multipart receipt ability
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            image/png:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpoint300Error'
        '403':
          description: Account does not have access to requested entities
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/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:
      - description: The primary hostname of the vendor to show additional evidence for.
        name: vendor_primary_hostname
        in: query
        schema:
          type: string
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          type: string
      - 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
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Vendor additional evidences list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVendorAdditionalEvidencesResponsePayload'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        '204':
          description: ' Successful response is empty'
        '403':
          description: Your API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVendorAttributesV1RequestBody'
  /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:
      - description: The id of the vendor contact to retrieve.
        name: id
        in: query
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Returns the vendor contact details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '403':
          description: Your API key does not have permission to perform this action, or the contact does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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:
      - description: The id of the vendor to retrieve contacts for.
        name: vendor_id
        in: query
        schema:
          type: integer
          format: int64
      - description: The primary hostname of the vendor to retrieve contacts for.
        name: vendor_primary_hostname
        in: query
        schema:
          type: string
      - description: The `page_token` from a previous request, use this to get the next page of results.
        name: page_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Returns a list of contacts for a vendor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContactList'
        '403':
          description: Your API key does not have permission to perform this action, or the contact does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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'
      tags:
      - vendors
      summary: Retrieve (one or more) vendor documents by id
      operationId: document
      parameters:
      - description: a comma-separated list of one or more documents (by unique id)
        name: document_ids
        in: query
        schema:
          type: array
          items:
            type: integer
            format: int64
      - description: indicates that for multiple document requests, the files should be returned as a multi-file zip
        name: zip
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Vendors document
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/GetVendorDocumentResponsePayload'
            image/png:
              schema:
                $ref: '#/components/schemas/GetVendorDocumentResponsePayload'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/GetVendorDocumentResponsePayload'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/GetVendorDocumentResponsePayload'
        '300':
          description: Request requires multipart receipt ability
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            image/png:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpoint300Error'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpoint300Error'
        '403':
          description: Account does not have access to requested entities
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/endpointError'
            image/png:
              schema:
                $ref: '#/components/schemas/endpointError'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/endpointError'
            'Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)':
              schema:
                $ref: '#/components/schemas/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:
      - description: The primary hostname of the vendor to show documents for.
        name: vendor_primary_hostname
        in: query
        schema:
          type: string
      - description: 'The token of the page to be returned.

          Will return the first page if left blank.'
        name: page_token
        in: query
        schema:
          type: string
      - 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
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Vendor documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVendorDocumentsResponsePayload'
        '422':
          description: An invalid parameter was supplied or a mandatory parameter was missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '429':
          description: Too many requests have been made to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endpointError'
        '500':
          description: An internal system error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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:
      - description: The primary hostname of the vendor to show the domain detail for.
        name: vendor_primary_hostnam

# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upguard/refs/heads/main/openapi/upguard-vendors-api-openapi.yml