openapi: 3.2.0
info:
  description: Cybersec API documentation
  version: 1.0.0
  title: Cybersec URLS API
servers:
- url: https://cybersec.nordstellar.com
security:
- ApiKeyAuth: []
tags:
- name: Urls
  description: ''
paths:
  /v2/cybersec/urls/allowed-domains:
    get:
      tags:
      - Urls
      summary: Get Allowed Domains lists
      description: 'This endpoint returns a 302 to an AWS bucket containing the domain whitelist and url exception list. The returned data might depend on the user''s country.

        '
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowedDomains'
              example:
                whitelist:
                - url: smilevideo.jp
                  categories:
                  - 1
                - url: google.com
                  categories:
                  - 1
                exceptions:
                - url: https://docs.google.com/uc?id=1aPn-jlUT6D56WTZ0ayqEYqQk8XVE2qX
                  categories:
                  - 2
                - url: https://sites.google.com/site/loaded0208/bmZHtAWpNa.zip
                  categories:
                  - 2
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authorization header not provided:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Authorization%20header%20not%20provided'
                Invalid authorization header:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Invalid%20authorization%20header'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/ServiceForbidden'
        '503':
          $ref: '#/components/responses/AuthServiceUnavailable'
  /v2/cybersec/urls/allowed-domains/hashed:
    get:
      tags:
      - Urls
      summary: Get Hashed Allowed Domains list
      description: 'This endpoint returns a 302 to an AWS bucket containing an hashed version of the domain whitelist and url exception list. The returned data might depend on the user''s country.

        '
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowedDomainsHashed'
              example:
                whitelist:
                - 44MD2UXWIkE
                - a278JTAr0Jo
                - h22jbkSq6KY
                exceptions:
                  3zz-Iz-TceA: 2
                  Cf7m5GkuRi0: 2
                  Uowuo71OmrE: 2
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authorization header not provided:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Authorization%20header%20not%20provided'
                Invalid authorization header:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Invalid%20authorization%20header'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/ServiceForbidden'
        '503':
          $ref: '#/components/responses/AuthServiceUnavailable'
  /v2/cybersec/urls/categories:
    get:
      operationId: urlCategories
      tags:
      - Urls
      summary: Get URL categories
      description: This endpoint returns URL category list for category ID mapping. Each entry contains category ID with it's description and whether it should be blocked on client side.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UrlCategoriesResponse'
              example:
                categories:
                - category: 0
                  name: unknown
                  block: false
                  subcategories: []
                - category: 1
                  name: safe
                  block: false
                  subcategories: []
                - category: 2
                  name: malware
                  block: true
                  subcategories: []
                - category: 3
                  name: phishing
                  block: true
                  subcategories: []
                - category: 4
                  name: spam
                  block: true
                  subcategories: []
                - category: 5
                  name: pua
                  block: true
                  subcategories: []
                - category: 6
                  name: puse
                  block: true
                  subcategories: []
                - category: 7
                  name: scam
                  block: true
                  subcategories:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
                  - 7
                  - 8
                  - 9
                  - 10
                  - 11
                  - 12
                  - 13
                  - 14
                  - 15
                  - 16
          headers:
            X-Correlation-ID:
              $ref: '#/components/schemas/X-Correlation-ID'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authorization header not provided:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Authorization%20header%20not%20provided'
                Invalid authorization header:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Invalid%20authorization%20header'
          headers:
            X-Correlation-ID:
              $ref: '#/components/schemas/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/ServiceForbidden'
        '503':
          $ref: '#/components/responses/AuthServiceUnavailable'
  /v2/cybersec/urls/check:
    post:
      operationId: urlCheck
      tags:
      - Urls
      summary: Perform an URL check
      description: This endpoint returns performs a query on provided url list for fraudulent content. Returned list contains category array for each url and status code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlCheckRequest'
            example:
              urls:
              - https://www.foo.bar/
              - https://drive.google.com/uc?export=download&id=1BZuTEOoNJlLtZrtxLkl-QvKMmwZb3-3M
              - https://google.com/q
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UrlCheckResponse'
              example:
                urls:
                - url: https://www.foo.bar/
                  status: 2
                  categories:
                  - 0
                  category_details: []
                - url: https://drive.google.com/uc?export=download&id=1BZuTEOoNJlLtZrtxLkl-QvKMmwZb3-3M
                  status: 0
                  categories:
                  - 2
                  category_details:
                  - 1
                  - 2
                  - 3
                - url: https://google.com/q
                  status: 0
                  categories:
                  - 1
                  category_details: []
                cache:
                - domain: google.com
                  ttl: 3039
                  categories:
                  - 1
          headers:
            X-Correlation-ID:
              $ref: '#/components/schemas/X-Correlation-ID'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Urls parameter is missing:
                  value:
                    errors:
                      code: 905155
                      message: '''urls'' parameter is missing'
                Invalid url:
                  value:
                    errors:
                      code: 905162
                      message: '''urls'' parameter contains an invalid url'
                Authorization header not provided:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Authorization%20header%20not%20provided'
                Invalid authorization header:
                  $ref: '#/paths/~1v2~1cybersec~1lists/get/responses/400/content/application~1json/examples/Invalid%20authorization%20header'
          headers:
            X-Correlation-ID:
              $ref: '#/components/schemas/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/ServiceForbidden'
        '413':
          $ref: '#/components/responses/ContentTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/AuthServiceUnavailable'
components:
  schemas:
    AllowedDomainsItem:
      type: object
      properties:
        url:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/UrlCategory'
    AllowedDomains:
      type: object
      properties:
        whitelist:
          type: array
          items:
            $ref: '#/components/schemas/AllowedDomainsItem'
        exceptions:
          type: array
          items:
            $ref: '#/components/schemas/AllowedDomainsItem'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: integer
              example: 123
            message:
              type: string
              example: Some error
    UrlCategories:
      type: array
      items:
        $ref: '#/components/schemas/UrlCategory'
    UrlCheckStatus:
      type: number
      enum:
      - 0
      - 1
      - 2
      description: "Codes:\n * `0` - Check performed successfully\n * `1` - URL check failed. URL is either malformed or an unknown error has occurred\n * `2` - Check is pending in backend, repeat a request for this url later\n"
    UrlCheckResult:
      type: object
      properties:
        url:
          type: string
          format: uri
        status:
          $ref: '#/components/schemas/UrlCheckStatus'
        categories:
          $ref: '#/components/schemas/UrlCategories'
        category_details:
          $ref: '#/components/schemas/UrlCategoryDetails'
    UrlCategory:
      type: number
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      description: "Category identifiers:\n * `0` - Unknown URL category\n * `1` - Either the URL is missing from the database, or it is known to be clean\n * `2` - Malware\n * `3` - Phishing\n * `4` - Spam\n * `5` - Potentially Unwanted Application / Web page containing PUAs\n * `6` - Potentially Unwanted Search Engine\n * `7` - Scam\n"
    AllowedDomainsHashed:
      type: object
      properties:
        whitelist:
          type: array
          items:
            type: string
        exceptions:
          type: object
        additionalProperties:
          $ref: '#/components/schemas/UrlCategory'
    X-Correlation-ID:
      type: string
      format: uuid
      example: ddd58a90-57c3-4bd1-a9ed-649a9451f0a7
      description: Unique identifier for correlating requests, responses and logs across distributed services
    UrlCheckRequest:
      type: object
      required:
      - urls
      properties:
        urls:
          type: array
          items:
            type: string
            format: uri
    UrlCategoryDetails:
      type: object
      properties:
        '7':
          type: array
          description: Scam
          items:
            type: number
            description: "Scam subcategory identifiers:\n * `1` B2B scam\n * `2` Chargeback money recovery scam\n * `3` Cryptocurrency scam\n * `4` Dating and romance scam\n * `5` Employment scam\n * `6` Fake IT and tech support scam\n * `7` Illegal products and services scam\n * `8` Intellectual property violation scam\n * `9` Investment scam\n * `10` Malware scam\n * `11` Online shopping scam\n * `12` Phishing scam\n * `13` Fake website scam\n * `14` Spam and abuse scam\n * `15` Subscription scam\n * `16` Other scam\n"
    UrlCategoriesResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            type: object
            properties:
              category:
                $ref: '#/components/schemas/UrlCategory'
              name:
                type: string
              block:
                type: boolean
              subcategories:
                $ref: '#/components/schemas/UrlCategoryDetails'
    UrlCheckResponse:
      type: object
      properties:
        urls:
          type: array
          items:
            $ref: '#/components/schemas/UrlCheckResult'
        cache:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                format: uri-reference
              ttl:
                type: number
              categories:
                $ref: '#/components/schemas/UrlCategories'
  responses:
    AuthServiceUnavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Service unavailable:
              value:
                errors:
                  code: 904178
                  message: Service temporary unavailable
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Internal server error:
              value:
                errors:
                  code: 904177
                  message: An unexpected condition is encountered
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
    InvalidCredentials:
      description: Invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Invalid credentials:
              value:
                errors:
                  code: 100104
                  message: Invalid credentials
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
    ServiceForbidden:
      description: Service is forbidden for the user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Service is forbidden for the user:
              value:
                errors:
                  code: 100166
                  message: Service is forbidden for the user
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Content too large:
              value:
                errors:
                  code: 904175
                  message: Exceeded the limit of 20 records to check in a batch
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
    ContentTooLarge:
      description: Content too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Content too large:
              value:
                errors:
                  code: 904168
                  message: Url requested is too large. Limit is 65535
      headers:
        X-Correlation-ID:
          $ref: '#/components/schemas/X-Correlation-ID'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Set token with a prefix like this: `token:69405a802dba4f57804e5fff11061946a579d159d1a51760d19a50aec241adc9`'