openapi: 3.0.0
info:
  title: Cisco Cloudlock API
  description: |-
    The Cloudlock API provides data about an organization's activities, apps, incidents, and policies.
  version: "1.0.0"
  contact:
    name: Cloud Security Developer Community
servers:
  - url: https://api.cloudlock.com/api/v2
tags:
  - name: Activities
  - name: Apps
  - name: Entities
  - name: Incidents
  - name: Incident Aggregates
  - name: Incident Entities
  - name: IP Libraries
  - name: Policies
paths:
  /activities:
    get:
      tags:
      - Activities
      summary: List Activities
      description: Get the UBA (User Behavioral Analysis) activities.
      operationId: listActivities
      parameters:
      - $ref: '#/components/parameters/eventTypeParam'
      - name: ids
        schema:
          type: string
        in: query
        description: |-
          Filter the collection based on the event id or group of ids. Provide a comma-separated list of ID strings.
          The ID strings must be url encoded.
        example: "google:auth:-1595373817266362937%230,aws:CloudTrail:d891a0e2-4aaa-4cea-b237-da3d103ccbef"
      - $ref: '#/components/parameters/createdAfterParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivitiesCollection'
              examples:
                response:
                  value:
                    - client_ip: 86.176.87.160
                      client_location:
                        city: Harpenden
                        country:
                          code: GB
                          name: United Kingdom
                        lat: "51.8"
                        lng: "-0.35"
                        region:
                          code: F8
                          name: Hertford
                      created_at: '2015-06-23T15:18:09.000Z'
                      event_category: auth
                      event_id: '-6285966971996490902#0'
                      event_type: login
                      extra:
                        auth:
                          auth_type: ''
                          is_suspicious: false
                      operation_successful: true
                      origin_id: '-6285966971996490902'
                      raw:
                        actor:
                          email: yoni.fine@cloudlockdemo.com
                          profileId: '108287862377325873441'
                          etag: >-
                            "RU_ANZvud_qrxRGJHqK2w1PCmE4/mLe1pMbCGKexbLn4QBfOSNhifXY"
                        events:
                            - parameters:
                                - name: login_type
                                  value: google_password
                                - name: login_success
                                  type: login
                        id:
                          applicationName: login
                          customerId: C015wxbys
                          time: '2015-06-23T15:18:09.000Z'
                          uniqueQualifier: '-6285966971996490902'
                        ipAddress: 86.176.87.160
                        kind: admin#reports#activity
                      user:
                        user_email: yoni.fine@cloudlockdemo.com
                        vendor_id: '108287862377325873441'
                      user_agent: ''
                      vendor:
                          name: google
                          service: auth
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /apps:
    get:
      tags:
      - Apps
      description: |-
        Get all of the organization's installed applications and their current status.
        To get the uninstalled applications, use the `install_state` filter.
      # The apps endpoint applies to the Apps Firewall product.
      operationId: listApplications
      summary: List Applications for the Organization
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
        - name: classification
          schema:
            type: string
          in: query
          description: Filter based on the application classification
          example: trusted
        - name: vendor
          schema:
            type: string
          in: query
          description: Filter based on the vendor platform.
          example: google
        - name: app_category
          schema:
            type: string
          in: query
          description: The application category.
          example: CIT
        - name: detected_at_after
          schema:
            type: string
          in: query
          description: Specify a timestamp. Filter for applications detected after a given date.
          example: '2021-04-21T08:22:40'
        - name: detected_at_before
          schema:
            type: string
          in: query
          description: Specify a timestamp. Filter for applications detected before a given date.
          example: '2021-04-21T08:22:40'
        - name: app_ids
          schema:
            type: string
          in: query
          description: Filter for applications based on their id. Provide a comma-delimited string of IDs.
          example: '1,2,3'
        - name: scope_categories
          schema:
            type: string
          in: query
          description: |-
            Filter for applications based on their scope category. Provide a comma-delimited string of scope category.
          example: 'LACES,BINFO'
        - name: install_state
          schema:
            type: string
          in: query
          description: Filter for applications based on their state (installed or not installed).
          example: 'installed'
        - name: count_total
          schema:
            type: string
          in: query
          description: |-
            Determines whether the `total` field returns a valid count of the applications.
            Use the `count_total` value with the `offset` parameter to paginate the results.
            Default value is `false`. Set to `true` to return a valid apps count.
          example: 'true'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppsCollection'
              examples:
                response:
                  value:
                    - admins_count: 0
                      app:
                        category: ""
                        id: RkJx2JxK2O
                        install_type: user
                        is_revokable: true
                        name: Cloudlock
                        origin_id: |-
                          144711811583-2ra0eotmtsb3p7f48eie68d4rfeghl7q.apps.googleusercontent.com
                        trust_rating: ""
                        vendor:
                          name: google
                      classification:
                        method: ''
                        reason: ''
                        type: unclassified
                        updated_at: ""
                      detected_at: '2016-02-19T08:22:40.382224+00:00'
                      id: RkJx2JxK2O
                      scope_categories:
                        - category_id: BINFO
                          title: 'Basic information'
                      users_count: 3
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/apps/{id}/access_scopes':
    get:
      tags:
      - Apps
      description: Get all of the access scopes for a given application.
      operationId: listApplicationAccessScopes
      summary: List Application Access Scopes
      parameters:
        - description: The ID of the app.
          example: G8qz0A239V
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessScope'
              examples:
                response:
                  value:
                      - category:
                          id: BINFO
                          title: Basic Information
                        description: View your email address
                        friendly_name: Userinfo - Email
                        id: 1gk4vvW4Mq
                        url: 'https://www.googleapis.com/auth/userinfo.email'
                      - category:
                          id: LACES
                          title: Limited Access to Data and Files
                        description: Insert moments to a Google+ profile.
                        friendly_name: 'Google+ API: Moments'
                        id: ZkL4dryz1o
                        url: 'https://www.googleapis.com/auth/plus.moments.write'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/apps/{id}/classification':
    post:
      tags:
      - Apps
      description: Update the application's classification.
      summary: Update Classification for Application
      operationId: updateAppsClassification
      parameters:
        - description: The ID of the incident.
          example: 'Aj54oPkx8m'
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                other_reason: Other Custom Reason
                reason_id: 4
                type: trusted
              properties:
                other_reason:
                  type: string
                reason_id:
                  type: number
                type:
                  type: string
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppsCollection'
              examples:
                response:
                  value:
                    - app1:
                      app:
                        category: ''
                        id: Aj54oPkx8m
                        install_type: user
                        is_revokable: true
                        name: CloudLock Collaboration Security
                        origin_id: |-
                          150079143025-d1lebr0q2pdf3i9vp2o3gb9dhm6nahq1.apps.googleusercontent.com
                        vendor:
                          name: google
                      classification:
                        method: manual
                        other_reason: Other Custom Reason
                        reason: Internal reason
                        reason_id: 4
                        type: trusted
                      updated_at: '2016-01-17T20:43:08.465267+00:00'
                      detected_at: '2015-04-13T11:54:47.403000+00:00'
                      id: Aj54oPkx8m
                      scope_categories:
                        - category_id: BINFO
                      users_count: 1
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/apps/{id}/installs':
    get:
      tags:
      - Apps
      description: List the application's installations.
      operationId: listApplicationInstallations
      summary: List Installations of Application
      parameters:
        - description: The ID of the app.
          example: "G8qz0A239V"
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppsCollection'
              examples:
                response:
                  value:
                    - response:
                        app:
                          id: rNP3DKdzBy
                          install_type: user
                          name: Balsamiq Mockups 3 for Google Drive
                          origin_id: >-
                            199991064517-4p9fkqt42jbsg361b4lu8fsuob161vhn.apps.googleusercontent.com
                          access_risk: 2
                          is_revokable: true
                          category: ""
                          client_type: not_native
                          risk_level: 1
                          trust_rating: 100
                        vendor:
                          name: google
                        detection_date: "2015-04-07T07:42:11.452682+00:00"
                        domain: cloudlockplus.com
                        family_name: Admin
                        given_name: Admin
                        scope_id: 15926475
                        scope_type: user
                        scope_value: admin@cloudlockplus.com
                        state: not_installed
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/entities':
    get:
      tags:
        - Entities
      description:
        Get the data for the asset list page and asset list exports.
        This endpoint requires the Entity Cache feature. If you do not have this
        feature enabled, refer to the incident entitites endpoint as an
        alternative.
      operationId: listEntities
      summary: List Entities
      parameters:
        - name: platform
          schema:
            type: string
          in: query
          description:
            The application supplying the underlying data.
          example: 'google_document,google_site'
        - name: owners
          in: query
          schema:
            type: string
          description:
            comma delimited list of owner email addresses
        - name: exposure
          schema:
            type: string
          in: query
          description: exposure level of the document
          example: 'public, externally shared, organization-wide, internally shared, private'
        - name: asset_type
          schema:
            type: string
          in: query
          description: |-
            google_document, google_spreadsheet, google_presentation, google_form,
            google_drawing, google_site, google_plus_post (future),
            google_non_native_file, pdf, folder
        - name: mime_type
          schema:
            type: string
          in: query
          description: |-
            spreadsheet (.xlsx, application/vnd-google-apps.spreadsheet), document
            (.docx, application/vnd-google-apps.document)
        - name: updated_before
          schema:
            type: string
          description: Filters assets updated before the specified timestamp.
          in: query
        - name: updated_after
          in: query
          description: Filters assets updated after the specified timestamp.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EntitiesCollection'
              examples:
                response:
                  value:
                    - asset_type: google_document
                      collaborators:
                        - name: Admin Admin
                          role: writer
                          type: user
                          value: admin@testcloudlockdev9.com
                      collaborators_count: 1
                      created_at: '2016-03-15T14:27:33.013000+00:00'
                      direct_url: |-
                        https://docs.google.com/a/testcloudlockdev5.com/document/d/15RvNK8Ahz_kiszqfs3oLopxZyBRi5_yAIyo5ans/edit?usp=drivesdk
                      exposure: organization_wide
                      id: MxylKdo1b4
                      mime_type: application/vnd.google-apps.document
                      name: Domain-wide Share 3/15/16
                      origin_id: 15RvNK8Ahz_kiszqfs3oLopOAGUxZyBRi5_yAIyo5ans
                      origin_type: document
                      owners:
                        - type: 'user'
                          role: 'writer'
                          vaue: 'admin@testcloudlockdev9.com'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/incident_entities/{id}':
    get:
      tags:
        - Incident Entities
      description: |-
        Get the detailed entity information for an entity involved in an incident.
        There is a limit of up to 100 ACL's and the data is reflective of the last time we scanned the
        document (not when the incident was created).

        Usage:
        First get an incident/incidents. Then take the id value from the entity
        object within the incident and call the incident_entities endpoint using
        that entitys id (not the incident id).

        Example:
        You have an incident which has an ID of 528815. Lookup the entity id for
        this incident, then use this entity id to get the entity information.
      operationId: listIncidentEntities
      summary: List Incident Entities
      parameters:
        - description: The ID of the entity in the incident.
          example: 513266
          in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentEntity'
              examples:
                response:
                  value:
                    id: "513266"
                    name: 'Logins for EC2 Instances.xlsx'
                    user: ""
                    owner_name: ""
                    owner_vendor_id: ""
                    acl:
                     - created_on: '2021-02-27 20:18:38.799158'
                       id: '2823'
                       origin_id: ''
                       role: viewer
                       status: ACTIVE
                       type: public_with_link
                       value: public_with_link
                       vendor:
                        name: box
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /incidents:
    get:
      tags:
        - Incidents
      description: |-
        Incidents are a key resource in CloudLock. Incidents are
        triggered by the CloudLock policy engine when a policy's detection
        criteria results in a match in object (document, field, folder, post, or
        file).
        Incidents can be changed manually by a
        user (by updating incidents fields such as status or severity) or
        automatically as objects or events are reevaluated by the policy
        engine. Depending on the incident type, different incident information may be
        available.

        Key information about an incident:
        Summary - Basic incident information and
        status
        Details - Information about the relevant object(s) associated with this incident
        Entity - Information about the object related
        to the incident
        Matches - Matches represent the actual hits
        within the content (for content type policies)
      operationId: listIncidents
      summary: List Incidents
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
        - name: incident_type
          schema:
            type: string
          in: query
          description: 'Filter based on the incident type.'
          example: 'COMPLIANCE'
        - name: severity
          schema:
            type: string
          in: query
          description: 'Filter based on the incident severity.'
          example: 'CRITICAL'
        - name: policy_id
          schema:
            type: string
          in: query
          description: 'Filter based on the policy ID.'
          example: 'rNP3Dd3By0'
        - $ref: '#/components/parameters/createdBeforeParam'
        - $ref: '#/components/parameters/createdAfterParam'
        - name: updated_before
          in: query
          schema:
            type: string
          description: 'Filter based on incidents updated before a given date.'
          example: "2021-01-18T16:55"
        - name: updated_after
          in: query
          schema:
            type: string
          description: 'Filter based on incidents updated after a given date.'
          example: "2021-01-18T16:55"
        - name: incident_status
          schema:
            type: string
          in: query
          description: 'Filter based on the incident status.'
          example: RESOLVED
        - name: vendor
          schema:
            type: string
          in: query
          description: 'Filter based on the platform (for example: google, salesforce)'
          example: salesforce
        - name: customer_key
          schema:
            type: string
          in: query
          description: 'Filter based on the customer_key field.'
          example: '123 abc'
        - name: fields
          schema:
            type: string
          in: query
          description: |-
            Return only the selected parent fields. For example: id and entity fields.
            Provide a comma-delimited list of parent fields.
          example: "id,entity"
        - name: order
          schema:
            type: string
          in: query
          description: |-
            Sort by the date when the incident was created (A dash (`-`) denotes descending order).
          example: created_at
        - name: flat
          schema:
            type: string
          in: query
          description: |-
            If set to `true`, flatten the output to simplify ingestion of data by tabular systems.
          example: 'true'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IncidentsCollection'
              examples:
                response:
                  value:
                    - created_at: '2014-08-08T05:09:53.218594+00:00'
                      customer_key: ''
                      entity:
                        direct_url: 'https://na15.salesforce.com/00Qi00000088wrBEAQ'
                        extra:
                          origin_type_label: Lead
                          origin_type_label_plural: Leads
                      id: "GM46KpY7xO"
                      mime_type: ''
                      name: Gautum Trentson
                      origin_id: 00Qi00000088wrBEAQ
                      origin_type: document
                      owner_email: jennifer@cloudlock.com
                      owner_name: Jennifer McClain
                      vendor:
                        name: salesforce
                        id: '320831601'
                        incident_status: IN PROGRESS
                        match_count: 1
                      matches:
                        - created_at: '2014-08-08T05:09:53.218594+00:00'
                          ctx_after: can we use this on the up
                          ctx_before: ard number on an old invoice
                          field_name: Description
                          text: XXXXXXXXXXXX6966
                      policy:
                        id: eyaznBzYKv
                        name: PCI
                      severity: WARNING
                      updated_at: '2014-08-08T05:09:52.930752+00:00'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /incidents/aggregates/policies:
    get:
      tags:
        - Incident Aggregates
      description: |-
        Get the aggregations (by policies/users/status) for the incidents.
      operationId: listIncidentAggregatesPolicies
      summary: List Incident Aggregates Policies
      parameters:
        - $ref: '#/components/parameters/createdAfterParam'
        - name: vendor
          schema:
            type: string
          in: query
          description: 'Filter based on the platform (for example: google, salesforce)'
          example: google
        - name: order
          schema:
            type: string
          in: query
          description: 'Order based on the severity. Only descending severity is supported.'
          example: '-severity'
        - name: policies
          in: query
          schema:
            type: string
          description: Return aggregates by policies
        - name: users
          schema:
            type: string
          in: query
          description: Return aggregates by users
        - name: status
          schema:
            type: string
          in: query
          description: Return aggregates by status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IncidentAggregates'
              examples:
                response:
                  value:
                    - agg:
                        info: 34
                        alert: 443
                        critical: 770
                        total: 1247
                        warning: 0
                      id: G8qz0vb49V
                      name: Social Security Number
                    - agg:
                        info: 2549
                        alert: 0
                        critical: 0
                        total: 2549
                        warning: 0
                      id: GbO4Q6lxLp
                      name: Custom Regex
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /incidents/aggregates/status:
    get:
      tags:
        - Incident Aggregates
      description: List the status information for the incident aggregates.
      operationId: listIncidentAggregatesStatus
      summary: List Status for Incident Aggregates
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IncidentAggregates'
              examples:
                response:
                  value:
                    - agg:
                        info: 1433
                        alert: 0
                        critical: 0
                        total: 1433
                        warning: 0
                      id: IN PROGRESS
                      name: IN PROGRESS
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /incidents/aggregates/users:
    get:
      tags:
        - Incident Aggregates
      description: List the status information and users for the incident aggregates.
      operationId: listIncidentAggregatesUsers
      summary: List Status and Users for Incident Aggregates
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IncidentAggregates'
              examples:
                response:
                  value:
                    - agg:
                        info: 134
                        alert: 0
                        critical: 2
                        total: 2049
                        warning: 1913
                      id: administrator@testcloudlockprimary1.com
                      name: administrator@testcloudlockprimary1.com
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/incidents/{id}':
    get:
      tags:
        - Incidents
      description: Get the information about a specific incident.
      operationId: getIncident
      summary: Get Incident
      parameters:
        - description: The ID of the incident.
          example: 320831601
          in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentsCollection'
              examples:
                response:
                  value:
                    created_at: '2014-08-08T05:09:58.861954+00:00'
                    customer_key: ''
                    entity:
                      direct_url: 'https://na15.salesforce.com/0D5i000000jY0GvCAK'
                      extra:
                        origin_type_label: Feed Item
                        origin_type_label_plural: Feed Items
                      id: vXxjnWAexL
                      mime_type: ''
                      name: Feed Item by John Demo
                      origin_id: 0D5i000000jY0GvCAK
                      origin_type: document
                      owner_email: demoUser@cloudlockdemo.com
                      owner_name: John Demo
                      vendor:
                        name: salesforce
                    id: '320831601'
                    incident_status: IN PROGRESS
                    match_count: 1
                    matches:
                      - created_at: '2014-08-08T05:09:58.861954+00:00'
                        ctx_after: "638 1"
                        ctx_before: 'UPS Tracking Number: 1Z W18'
                        field_name: Body
                        policy_criteria:
                          id: "23"
                        text: XXX XX 7502
                    policy:
                      id: Bdb475zMDK
                      name: SSN
                    severity: WARNING
                    updated_at: '2014-08-08T05:09:58.572845+00:00'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    put:
      tags:
        - Incidents
      description: Update a specific incident.
      operationId: updateIncident
      summary: Update Incident
      requestBody:
        content:
          application/json:
            schema:
              example:
                incident_status: RESOLVED
              properties:
                incident_status:
                  type: string
              type: object

      parameters:
        - description: The ID of the incident.
          example: 320831601
          in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentsCollection'
              examples:
                response:
                  value:
                    created_at: '2014-08-08T05:10:00.326727+00:00'
                    customer_key: ExternalID
                    entity:
                      direct_url: 'https://na15.salesforce.com/0D5i000000XWpE0CAL'
                      extra:
                        origin_type_label: Feed Item
                        origin_type_label_plural: Feed Items
                      id: 1MxyLjlA4B
                      mime_type: ''
                      name: Feed Item by Jennifer McClain
                      origin_id: 0D5i000000XWpE0CAL
                      origin_type: document
                      owner_email: jennifer@cloudlock.com
                      owner_name: Jennifer McClain
                      vendor:
                        name: salesforce
                    id: '320831601'
                    incident_status: RESOLVED
                    match_count: 1
                    matches:
                      - created_at: '2014-08-08T05:10:00.326727+00:00'
                        ctx_after: ''
                        ctx_before: ''
                        field_name: Body
                        text: Confidential
                    policy:
                      created_at: null
                      id: ''
                      name: Confidential/Password Regular Expression24
                      state: null
                      updated_at: null
                    severity: WARNING
                    updated_at: '2015-06-16T17:29:39.697785+00:00'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /ip/suspicious:
    delete:
      tags:
        - IP Libraries
      description: |-
        Remove custom, organization-defined, or suspicious IP addresses from
        the collection.
      operationId: deleteEntriesIpSuspicious
      summary: Delete Multiple Entries
      parameters:
        - description: List of entry IDs to delete.
          in: query
          name: ids
          required: true
          schema:
            type: string
        - description: 'e.g. /ip/suspicious/?ids=J83euASvnDF,6yj3gQxaqo'
          example: '/ip/suspicious/?ids=J83euASvnDF,6yj3gQxaqo'
          in: header
          name: Location
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    get:
      tags:
        - IP Libraries
      description: List an organization's suspicious IP feeds.
      operationId: listEntriesIpSuspicious
      summary: List IP Suspicious Entries
      parameters:
        - description: 'Match string within any of: name, location, ip_address, categories'
          in: query
          name: q
          required: false
          schema:
            type: string
        - description: Match a substring within entry name
          in: query
          name: name
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IPCollection'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    post:
      tags:
        - IP Libraries
      description: Upload a file (IP feed) for review. Use a multipart/form-data request to upload and import a CSV file.
      operationId: importCsvEntriesIpSuspicious
      summary: Import CSV Entries
      parameters:
        - description: The uploaded file.
          in: query
          name: file
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/ip/suspicious/{id}':
    put:
      tags:
        - IP Libraries
      description: Update the TTL expiration date, IP address, categories, and short-description.
      operationId: updateEntryIpSuspicious
      summary: Update IP Entry
      requestBody:
        content:
          application/json:
            schema:
              properties:
                categories:
                  description: Change categories.
                  type: string
                description:
                  description: Internal short description.
                  type: string
                expires_on:
                  description: Datetime to expire the ip address.
                  type: string
                ip_address:
                  description: Change IP address.
                  type: string
              type: object
      parameters:
        - description: The ID of the entry to update.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /ip/trusted:
    delete:
      tags:
        - IP Libraries
      description: Remove the trusted IP's from the collection.
      operationId: deleteEntriesIpTrusted
      summary: Delete Trusted IPs
      parameters:
        - description: A comma-delimited string of IDs to delete.
          in: query
          name: ids
          required: true
          schema:
            type: string
        - description: A comma-delimited string of IDs.
          example: "7nLzJYxR5Z,6yj3gQxaqo"
          in: header
          name: Location
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    get:
      tags:
        - IP Libraries
      description: List an organization's trusted IP feeds.
      operationId: listEntriesTrustedIp
      summary: List IP Entries
      parameters:
        - description: 'Match string within any of: name, location, ip_address, categories.'
          in: query
          name: q
          required: false
          schema:
            type: string
        - description: Match a substring within entry name.
          in: query
          name: name
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPCollection'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    post:
      tags:
        - IP Libraries
      description: Upload a file (IP feed) for review. Use a multipart/form-data request to upload and import a CSV file.
      operationId: importCsvEntriesIpTrusted
      summary: Import CSV Entries
      parameters:
        - description: Uploaded file
          in: query
          name: file
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/ip/trusted/{id}':
    put:
      tags:
        - IP Libraries
      description: Update the name, ip address, categories, and short description for the trusted IP feed.
      operationId: updateEntryIpTrusted
      summary: Update IP Trusted by ID
      requestBody:
        content:
          application/json:
            schema:
              properties:
                categories:
                  description: Change categories.
                  type: string
                description:
                  description: Internal short description.
                  type: string
                ip_address:
                  description: Change IP address.
                  type: string
                name:
                  description: Name of entry.
                  type: string
              type: object
      parameters:
        - description: The ID of the entry to update.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/policies':
    get:
      tags:
        - Policies
      description: Get all of the organization's configured policies.
      operationId: listPolicies
      summary: List the Organization's Policies
      parameters:
        - name: state
          example: active
          in: query
          required: false
          description: Provide a string that indicates the policy state.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PoliciesCollection'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

components:
  parameters:
    createdAfterParam:
      name: created_after
      schema:
        type: string
      in: query
      description: Filter the collection by the creation date.
      example: "2021-01-01"
    createdBeforeParam:
      name: created_before
      in: query
      schema:
        type: string
      description: Filter based on incidents created before a given date.
      example: "2021-01-18T16:55"
    eventTypeParam:
      name: event_type
      schema:
        type: string
      in: query
      description: |-
        Filter based on the event type. For example: login, user_settings, or other.
      example: user_settings
    offsetParam:
      name: offset
      schema:
        type: string
      in: query
      description: A number that represents the index into the collection.
      required: false
    limitParam:
      name: limit
      in: query
      description: The maximum number of records to return in the collection.
      required: false
      schema:
        type: string
  schemas:
    PoliciesCollection:
      type: object
      properties:
        id:
          type: string
          description: This is CloudLock Internal Identifier for a policy.
          example: "G8qz0vb49V"
        name:
          type: string
          description: The name of the policy.
          example: "PCI - Alert"
        state:
          type: string
          description: Indicates if the policy is active or inactive.
          example: "Active, Inactive"
        description:
          type: string
          description: The description of the policy.
          example: Apps whose authorized access scopes present potential security risks
        created_at:
          type: string
          description: The policy creation time, specified as a timestamp in UTC.
          example: "2015-03-19T09:00:17.602482+00:00"
        updated_at:
          type: string
          description: The policy updated time, specified as a timestamp in UTC.
          example: "2015-03-19T09:00:17.602482+00:00"
        severity:
          type: string
          description: The severity assigned to incidents of this policy.
          example: "CRITICAL,WARNING,INFO,ALERT"
    Vendor:
      type: object
      properties:
        name:
          type: string
          description: 'The name of the vendor. For example: google.'
    Classification:
      type: object
      properties:
        method:
          type: string
          description: 'The method where the classification was changed. Possible values are: manual, policy.'
        reason:
          type: string
          description: The reason for the classification.
        type:
          type: string
          description: |-
            Application's classification type. Possible values are: unclassified, trusted, restricted, banned.
        updated_at:
          type: string
          description: The classification's last update time, specified as a timestamp in UTC.
      description: The application's classification resource.
    App:
      type: object
      description: The information about the application.
      properties:
        category:
          type: string
          description: The app's category.
        id:
          type: string
          description: The internal Cloudlock id for the application.
        install_type:
          type: string
          description: 'A string that describes the installation type (across the domain or by a user). Possible values are: domain_wide, user.'
        is_revokable:
          type: boolean
          description: Indicates whether the app can be revoked.
        name:
          type: string
          description: 'The name of the application, for example: Google Drive.'
        origin_id:
          type: string
          description: The location where the app was installed.
        trust_rating:
          type: string
          description: The community trust rating score.
        vendor:
          $ref: '#/components/schemas/Vendor'
    AppsCollection:
      type: object
      properties:
        id:
          type: string
          description: The application's internal CloudLock ID.
        app:
          $ref: '#/components/schemas/App'
        scope_categories:
          type: array
          items:
            $ref: '#/components/schemas/ScopeCategory'
          description: The list of application scope category.
        classification:
          $ref: '#/components/schemas/Classification'
        detected_at:
          type: string
          description: The time when the app was detected, specified as a timestamp in UTC.
        users_count:
          type: integer
          description: The number of users that have the application installed.
        admins_count:
          type: integer
          description: The number of administrators that have the application installed.
    EntitiesCollection:
      type: object
      properties:
        id:
          type: string
          description: The unique internal identifier for the asset.
        vendor:
          $ref: '#/components/schemas/Vendor'
        origin_id:
          type: string
          description: The unique identifier for the asset provided by the origin platform/vendor.
        origin_type:
          type: string
          description: The equivalent to vendor_type.
          example: "document, post, event, app, site"
        asset_type:
          type: string
          description: "google_document, google_spreadsheet, google_form, google_drawing"
          example: "google_presentation, google_site, folder, non_native_file, pdf"
        owners:
          type: array
          items:
            $ref: '#/components/schemas/PermissionResource'
        mime_type:
          type: string
        exposure:
          type: string
          description: The exposure level of the document.
          example: "public, externally shared, organization-wide, internally shared, private"
        collaborators_count:
          type: integer
          description: The total number of collaborators on an asset.
        name:
          type: string
          description: The title, name of the asset.
        size:
          type: integer
          description: The size of the asset in bytes.
        updated_at:
          type: string
          description: The last time the asset has been modified, specified as a timestamp in UTC.
        created_at:
          type: string
          description: The time at which the asset was created, specified as a timestamp in UTC.
        direct_url:
          type: string
          description: The URL for the asset.
        collaborators:
          type: array
          items:
            $ref: '#/components/schemas/PermissionResource'
    PermissionResource:
      type: object
      description: The permissions corresponding to the owners of the asset.
      properties:
        type:
          type: string
          description: The type of permission.
          example: (current values are Google specific)
        role:
          type: string
          description: The role associated with the permission (current values are Google specific).
          example: "reader, writer, owner"
        value:
          type: string
          description: The email address or domain address for the permission.
          example: "admin@domain.com"
    IncidentAggregates:
      type: object
      properties:
        agg:
          type: object
          description: The aggregates object.
          properties:
            info:
              type: integer
              description: The number of `info` severity incidents.
            total:
              type: integer
              description: The overall number of incidents.
            warning:
              type: integer
              description: The number of `warning` severity incidents.
            critical:
              type: integer
              description: The number of `critical` severity incidents.'
            alert:
              type: integer
              description: The number of `alert` severity incidents.
        id:
          type: string
          description: The ID of the policy/status/user.
        name:
          type: string
          description: The name of the policy/status/user.
    IncidentEntity:
      type: object
      description: The information about the object relating to this incident.
      properties:
        acl:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              value:
                type: string
              role:
                type: string
              type:
                type: string
              status:
                type: string
              created_on:
                type: string
              vendor:
                $ref: '#/components/schemas/Vendor'
              origin_id:
                type: string
        entity:
          $ref: '#/components/schemas/Entity'
    Policy:
      type: object
      description: The policy that triggered the incident.
      properties:
        id:
          type: string
          description: The Cloudlock Internal Identifier for a policy.
        name:
          type: string
          description: 'The name of the policy. Possible values: SSN, PCI or any policy name.'
    Match:
      type: object
      description: |-
        A Match represents an occurrence of a content pattern in an object (such as a file).
        The content pattern is defined in a policy.
      properties:
        created_at:
          type: string
          description: The time when this match was detected. Time expressed as a timestamp in UTC.
        ctx_after:
          type: string
          description: The characters after the match.
        ctx_before:
          type: string
          description: The characters before the match.
        field_name:
          type: string
          description: The field or object for this match.
        text:
          type: string
          description: |-
            Provide string to identify object. Relevant for content detection criteria='Custom regex criteria' only.
        policy_criteria:
          type: object
          description: A description of the policy criteria.
          properties:
            id:
              type: string

    ScopeCategory:
      type: object
      description: |-
        The scope categories resource returns information on the access scopes, which exist per each category.
        Scope category strings: `FDATA` (full data access), `BINFO` (basic info), `LACES` (limited access to data and files),
        `PINFO` (payment information), and `INBO`X (access inbox or contact information).
      properties:
        title:
          type: string
          description: |-
            The categories title, for example: `Basic Information`.
        category_id:
          type: string
          description: |-
            The category id. For example: `FDATA`, `BINFO`, `LACES`, and `PINFO`.
          example: FDATA

    AccessScope:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ScopeCategory'
        id:
          type: string
          description: The internal Cloudlock ID for the access scope.
        description:
          type: string
          description: |-
            A verbose description of the access scope, for example: `View your email address`.
        friendly_name:
          type: string
          description: |-
            The name of the access scope. In the UI this is the `ACCESS SCOPE` in the Access Scopes table. For example: `Userinfo - Email`.
        url:
          type: string
          description: |-
            The url to the access scope. For example: 'https://www.googleapis.com/auth/userinfo.email'.

    Entity:
      type: object
      description: The information about the object relating to this incident.
      properties:
        direct_url:
          type: string
          description: The URL to the object.
        extra:
          type: object
          description: The additional information related to the incident.
          properties:
            origin_type_label:
              type: string
              description: |-
                This field gives additional info regarding the scanned object that triggered the policy violation.
            origin_type_label_plural:
              type: string
              description: "Similar to the origin_type_label but for a plural label"
        id:
          type: string
          description: This is Cloudlock Internal Identifier for an entity.
        mime_type:
          type: string
          description: "The mime type of the object/document (if any)"
        name:
          type: string
          description: "The name of the underlying object represented by this entity."
        origin_id:
          type: string
          description: "This is the identifier of the object in the vendor system."
        origin_type:
          type: string
          description: "The object type (i.e. document, post, app, event)."
        owner_email:
          type: string
          description: "Object owner's email address (e.g. user@cloudlock.com)."
        owner_name:
          type: string
          description: "Object owner's name (i.e. John Q. User)."
        vendor:
          $ref: '#/components/schemas/Vendor'
    IncidentsCollection:
      type: object
      properties:
        id:
          type: string
          description: |-
            The internal CloudLock incident ID, which can be used to
            call or update a specific incident.
        customer_key:
          type: string
          description: "An empty field to be used as a system ID (a customer can set this or leave it empty)."
        incident_status:
          type: string
          description: "The status of the incident. Possible values: NEW, RESOLVED, IN PROGRESS, DISMISSED."
        severity:
          type: string
          description: "The severity of the incident. Possible values: INFO, WARNING, CRITICAL, ALERT."
        created_at:
          type: string
          description: "The incident creation time, in UTC."
        updated_at:
          type: string
          description: "The incident last upate time, in UTC."
        match_count:
          type: integer
          description: The total number of matches."
        entity:
          $ref: '#/components/schemas/Entity'
        policy:
          $ref: '#/components/schemas/Policy'
        matches:
          description: The list of matches for the incident.
          type: array
          items:
            $ref: '#/components/schemas/Match'
    ActivitiesCollection:
      type: object
      properties:
        event_id:
          type: string
          description: This is CloudLock Internal Identifier for an activity.
          example: "-6285966971996490902#0"
        client_ip:
          type: string
          description: The client's IP address.
          example: "86.176.87.160"
        event_type:
          type: string
          description: The type of the event.
          example: "login, other, user_settings"
        created_at:
          type: string
          description: "When the activity took place, in UTC."
          example: "2015-03-19T09:00:17.602482+00:00"
        operation_successful:
          type: boolean
          description: Specifies whether the activity succeeded.
          example: true
        client_location:
          type: object
          properties:
            city:
              type: string
            country:
              type: object
              properties:
                code:
                  type: string
                name:
                  type: string
            lat:
              type: string
            lng:
              type: string
            region:
              type: object
              properties:
                code:
                  type: string
                name:
                  type: string
          description: The client location information.
        event_category:
          type: string
          description: The event category type.
          example: "auth"
        origin_id:
          type: string
          description: The origin ID.
          example: "-6285966971996490902"
        user:
          type: object
          properties:
            user_email:
              type: string
              description: ""
            vendor_id:
              type: string
              description: ""
          description: The user information.
        user_agent:
          type: string
        vendor:
          type: object
          properties:
            name:
              type: string
              description: ""
            service:
              type: string
              description: The vendor description.
          description: The platform information.
        extra:
          type: object
          properties:
            auth:
              type: object
              properties:
                auth_type:
                  type: string
                  description: The type of authentication.
                is_suspicious:
                  type: boolean
                  description: Indicates whether the activity is flagged as being suspicious.
          description: "Additional information related to the activity"
        raw:
          type: object
          description: The raw information for the activity.
    IPCollection:
      type: object
      properties:
        name:
          type: string
          description: The library item name.
          example: "Safe IP"
        description:
          type: string
          description: The library item description.
          example: "trusted"
        ip_address:
          type: string
          description: The IP address in the library.
          example: "172.255.255.0"
        location:
          type: string
          description: The location of the item.
          example: "Regional Office"
        type:
          type: string
          description: The item type.
          example: "trusted"
        categories:
          type: string
          description: The item categories.
          example: "offices, locations"
        updated_on:
          type: string
          description: The last update date specified as a timestamp in UTC.
          example: "2016-06-20T13:05:23.034264+00:00"
        created_on:
          type: string
          description: The creation date specified as a timestamp in UTC.
          example: "2016-06-20T13:05:23.034264+00:00"
  responses:
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    401Error:
      description: Unauthorized request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    500Error:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
