openapi: 3.0.3
info:
  title: Salus API - OpenAPI 3.0
  description: |-
    The Salus API provides information about actual and potential data breaches to authenticated clients.
    This conform to the OpenAPI 3.0 specification.
    - API requirements to note:
      - does not support GET requests.
      - ```X-API-Key header required for all auth requests.```
      - JSON payload {"key","value"}
      - request type: "Content-Type: application/json"
      - utf8 expected
    - end_date cannot be before start_date
    - start_date cannot be after end_date
    - JSON must be valid
    - JSON cannot be empty
    - Email must be valid email syntax (RFC)
    - Domain must be valid domain syntax (RFC)
    - All responses from server are json payloads.
    See also:
    - [Armament8 website](https://armament8.com/)
    - [The Salus API definition document](https://github.com/Armament8/salus-api/docs/salus-api.yaml)
  termsOfService: https://armament8.com
  contact:
    email: arm8-team@armament8.com
  license:
    name: Armament8 Proprietary
    url: https://armament8.com
  version: 1.0.0
servers:
  - url: https://intel.armament8.com/
tags:
  - name: breaches
    description: Retrieve breach information by email, domain, or all known breach lists. Optional date ranges available.
  - name: monitor
    description: Add an email or domain to monitor. Enable or disable monitoring for a specific email or domain.
paths:
  /api/v1/breaches:
    post:
      summary: Get breaches information
      description: |
        Supports POST method with JSON payload {"key","value"}.

        ### Example of using curl:
        ```
        curl -X POST "https://{server}/api/v1/breaches" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"breachlist":"true"}'
        ```
        ### Example of using Python:
        ```python
        import requests

        url = "https://{server}/api/v1/breaches"
        headers = {
            "x-api-key": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        data = {
            "breachlist": "true"
        }

        response = requests.post(url, headers=headers, json=data)
        print(response.json())
        ```
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                breachlist:
                  type: string
                  description: Flag to get all breaches list
                  example: "true"
                email:
                  type: string
                  format: email
                  description: Email to get breaches for
                  example: "john@example.com"
                domain:
                  type: string
                  description: Domain to get breaches for
                  example: "example.com"
                start_date:
                  type: string
                  format: date
                  description: Start date for date range
                  example: "yyyy-mm-dd"
                end_date:
                  type: string
                  format: date
                  description: End date for date range
                  example: "yyyy-mm-dd"
            examples:
              getAllBreaches:
                summary: Get all breaches list
                value: {"breachlist":"true"}
              getBreachesByDateRange:
                summary: Get breaches list by date range
                value: {"breachlist":"true", "start_date": "2025-01-01", "end_date":"2025-01-31"}
              getBreachesByEmail:
                summary: Get breaches for email
                value: {"email":"john@example.com"}
              getBreachesByEmailDateRange:
                summary: Get breaches for email by date range
                value: {"email":"john@example.com", "start_date":"2025-01-01","end_date":"2025-01-31"}
              getBreachesByDomain:
                summary: Get breaches for domain
                value: {"domain":"example.com"}
              getBreachesByDomainDateRange:
                summary: Get breaches for domain by date range
                value: {"domain":"example.com", "start_date":"2025-01-01","end_date":"2025-01-31"}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Success"
              examples:
                successExample:
                  summary: Successful response
                  value: {
                    "email": "john33@domain.com",
                    "domain": "domain.com",
                    "breach_name":"Breac num 3",
                    "breach_title":"Breach Number 3 2019",
                    "breach_date":"2019-02-05",
                    "description":"This breach happened, and it was bad.",
                    "record_count": 48498484,
                    "record_fields": "Date of birth, Email, PHone, IP Addresss"}
                breachlistsuccessExample:
                  summary: Breachlist Successful response
                  value: {
                    "breach_name":"Breac num 3",
                    "breach_title":"Breach Number 3 2019",
                    "breach_date":"2019-02-05",
                    "description":"This breach happened, and it was bad.",
                    "record_count": 48498484,
                    "record_fields": "Date of birth, Email, PHone, IP Addresss"}
        '400':
          description: Bad query. Depends on the reason. See message returned.
        '404':
          description: Results not found

  /api/v1/monitor:
    post:
      summary: Obtain monitor status for email or domain
      description: |
        - POST: email and domain queryable: '{"domain": "example.com"}' or '{"email": "john@example.com"}'
        ### Example of using curl:
        ```
        curl -X POST "https://{server}/api/v1/monitor" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"domain": "example.com"}'
        ```
        ### Example of using Python:
        ```python
        import requests

        url = "https://{server}/api/v1/monitor"
        headers = {
            "x-api-key": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        data = {
            "domain": "example.com"
        }

        response = requests.post(url, headers=headers, json=data)
        print(response.json())
        ```
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email to query
                  example: "john@example.com"
                domain:
                  type: string
                  description: Domain to query
                  example: "example.com"
            examples:
              postEmail:
                summary: Query by email
                value: {"email": "john@example.com"}
              postDomain:
                summary: Query by domain
                value: {"domain": "example.com"}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Success"
              examples:
                successExample:
                  summary: Successful response
                  value: {
                    "email": "john33@domain.com",
                    "monitor_status": 1,
                    "created_at":"2025-04-01 16:49:04",
                    "modified_at":"2025-04-01 16:49:04"}
        '400':
          description: Bad query. Depends on the reason. See message returned.
        '404':
          description: Results not found


    put:
      summary: Add email or domain to monitor
      description: |
        Add email or domain to monitor
        ## ```NOTE: monitor flag of 1 or 0 is required.```
        ## 0 = disabled ( for monitoring )
        ## 1 - enabled ( for monitoring )
        ### Example of using curl:
        ```
        curl -X PUT "https://{server}/api/v1/monitor" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"email": "john@example.com", "monitor":"1"}'
        ```
        ### Example of using Python:
        ```python
        import requests

        url = "https://{server}/api/v1/monitor"
        headers = {
            "x-api-key": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        data = {
            "email": "john@example.com",
            "monitor": "1"
        }

        response = requests.put(url, headers=headers, json=data)
        print(response.json())
        ```
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email to add
                  example: "john@example.com"
                domain:
                  type: string
                  description: Domain to add
                  example: "example.com"
                monitor:
                  type: string
                  description: Monitor status
                  example: "1"
            examples:
              putEmail:
                summary: Add email to monitor with enable status
                value: {"email": "john@example.com", "monitor":"1"}
              putDomain:
                summary: Add domain to monitor with enables status
                value: {"domain": "example.com", "monitor":"1"}
              putEmailDisabled:
                summary: Add email to monitor without enable status
                value: {"email": "john@example.com", "monitor":"0"}
              putDomainDisabled:
                summary: Add domain to monitor without enables status
                value: {"domain": "example.com", "monitor":"0"}
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Success"
              examples:
                successExample:
                  summary: Successful response
                  value: {
                    "status": "201",
                    "message": "mary4@domain.com successfully added"}
        '400':
          description: Bad query. Depends on the reason. See message returned.
        '404':
          description: Results not found

    patch:
      summary: Change monitor status
      description: |
        Change the monitor status of email or domain. Flip the bit.
        ## ```NOTE: this does not add missing email or domain. This only changes the monitored status```
        ### Example of using curl:
        ```
        curl -X PATCH "https://{server}/api/v1/monitor" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"email": "john@example.com", "monitor":"0"}'
        ```
        ### Example of using Python:
        ```python
        import requests

        url = "https://{server}/api/v1/monitor"
        headers = {
            "x-api-key": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        data = {
            "email": "john@example.com",
            "monitor": "0"
        }

        response = requests.patch(url, headers=headers, json=data)
        print(response.json())
        ```
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email to update
                  example: "john@example.com"
                domain:
                  type: string
                  description: Domain to update
                  example: "example.com"
                monitor:
                  type: string
                  description: Monitor status
                  example: "0"
            examples:
              patchEmail:
                summary: Change email monitor status
                value: {"email": "john@example.com", "monitor":"0"}
              patchDomain:
                summary: Change domain monitor status
                value: {"domain": "example.com", "monitor":"0"}
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Success"
              examples:
                successExample:
                  summary: Successful response
                  value: {
                    "status": "201",
                    "message": "email monitor set to 0 for mary2@domain.com"}
        '400':
          description: Bad query. Depends on the reason. See message returned.
        '404':
          description: Results not found

    delete:
      summary: Remove email or domain
      description: |
        May remove this or further build it out. Simple reply for now. No action taken. Disable email or domain with PATCH and monitor 0
        ### Example of using curl:
        ```
        curl -X DELETE "https://{server}/api/v1/monitor" -H "x-api-key: YOUR_API_KEY"
        ```
        ### Example of using Python:
        ```python
        import requests

        url = "https://{server}/api/v1/monitor"
        headers = {
            "x-api-key": "YOUR_API_KEY"
        }

        response = requests.delete(url, headers=headers)
        print(response.json())
        ```
      responses:
        '200':
          description: Success and return json payload
        '400':
          description: Bad query. Depends on the reason. See message returned.
        '404':
          description: Results not found