screen.yml

swagger: '2.0'
info:
  description: A programmatic gateway to securing your app with Sqreen.
  version: 'v1'
  title: Sqreen API
  contact:
    name: "Sqreen API Team"
    email: "[email protected]"
host: api.sqreen.io
basePath: /v1
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: X-API-Key
    
definitions:
  email:
    type: object
    required:
      - email
      - risk_score
    properties:
      email:
        type: string
        description: The email address queried.
      risk_score:
        type: number
        description: The assessed risk that this email address is being used by a malevolent actor.
        minimum: 0
        maximum: 100
      is_email_harmful:
        type: boolean
        description: Does the email address itself pose a direct security risk? E.g., does the email address contain embedded JavaScript?
      is_known_attacker:
        type: boolean
        description: Was this email address used as part of a security attack?
      high_risk_security_events_count:
        type: number
        description: The number of high-risk security events (e.g. SQL injection attacks) involving this email address.
      security_events_count:
        type: number
        description: The number of all security events (both high-risk and low-risk) involving this email address.
      is_disposable:
        type: boolean
        description: Does this email's domain belong to a known vendor of disposable, temporary, or anonymized email addresses?
      is_email_malformed:
        type: boolean
        description: Is the email malformed according to RFC 5322?
        
  geo:
    type: object
    description: A geographical location
    properties:
      latitude:
        type: number
        description: The latititude of the location
      longitude:
        type: number
        description: The longitude of the location
      city:
        type: string
        description: The city name associated with the location
      country_code:
        type: string
        description: The ISO ALPHA-3 Code for the country that this location exists within
        
  ip:
    type: object
    required:
      - ip
      - ip_version
      - risk_score
    properties:
      ip:
        type: string
        description: The IP address queried.
      ip_version:
        type: number
        description: The version of the IP address queried.
        enum: [4, 6]
      risk_score:
        type: number
        description: The assessed risk that this IP address is being used by a malevolent actor.
        minimum: 0
        maximum: 100
      is_known_attacker:
        type: boolean
        description: Was this IP address used as part of a security attack?
      high_risk_security_events_count:
        type: number
        description: The number of high-risk security events (e.g. SQL injection attacks) involving this IP address.
      security_events_count:
        type: number
        description: The number of all security events (both high-risk and low-risk) involving this IP address.
      ip_geo:
        $ref: "#/definitions/geo"
      is_datacenter:
        type: boolean
        description: Does this IP address belong to a known datacenter, such as AWS or Google Cloud?
      is_vpn:
        type: boolean
        description: Does this IP address belong to a known VPN?
      is_proxy:
        type: boolean
        description: Does this IP address belong to a known proxy server?
      is_tor:
        type: boolean
        description: Is this IP address a known Tor exit point?
        
  bad_request:
    type: object
    required:
      - code
    properties:
      code:
        type: number
        description: The HTTP status code.
      details:
        type: string
        description: A brief description of the error.
      message:
        type: string
        description: An error message that might provide more detail on what went wrong.


paths:
  '/emails/{email}':
    get:
      summary: Discover whether an email address presents a security risk.
      security:
        - api_key: []
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/email"
    parameters:
      - name: email
        in: path
        required: true
        type: string
  '/ips/{ip}':
    get:
      summary: Discover whether an IP address presents a security risk.
      security:
        - api_key: []
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/ip"
        400:
          description: We couldn't parse the IP address.
          schema:
            $ref: "#/definitions/bad_request"
    parameters:
      - name: ip
        in: path
        required: true
        type: string