{
  "openapi": "3.1.0",
  "info": {
    "title": "Cyber Threat Intelligence API",
    "description": "This API allows you to retrieve malicious domain detections",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.nameshield.net/cti",
      "description": "Production environment"
    },
    {
      "url": "https://ote-api.nameshield.net/cti",
      "description": "OTE environment"
    }
  ],
  "tags": [
    {
      "name": "v2",
      "description": "best way to use the API"
    }
  ],
  "paths": {
    "/v2/events": {
      "get": {
        "tags": [
          "v2"
        ],
        "summary": "List threat events",
        "description": "Search for threat events",
        "operationId": "search_1",
        "parameters": [
          {
            "name": "startedAt",
            "in": "query",
            "description": "Search for events emitted after this datetime (UTC). Format : yyyy-MM-dd HH:mm:ss",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-11-18 13:39:42"
          },
          {
            "name": "endedAt",
            "in": "query",
            "description": "Search for events emitted before this datetime (UTC). Format : yyyy-MM-dd HH:mm:ss",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-11-18 13:39:42"
          },
          {
            "name": "domain",
            "in": "query",
            "description": "Search for events with a domain containing this",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "criticality",
            "in": "query",
            "description": "Event criticality",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "NONE",
                "LOW",
                "MEDIUM",
                "HIGH"
              ]
            }
          },
          {
            "name": "customerId",
            "in": "query",
            "description": "Customer identifier",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Zero-based page index (0..N)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "The size of the page to be returned",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
            "required": false,
            "schema": {
              "type": "array",
              "default": [
                "date,ASC"
              ],
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedThreatEvent"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "403": {
            "description": "Access forbidden",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          }
        },
        "security": [
          {
            "JwtAuthentication": []
          }
        ]
      }
    },
    "/v2/events/{id}": {
      "get": {
        "tags": [
          "v2"
        ],
        "summary": "Get a specific threat event",
        "description": "Get a specific threat event",
        "operationId": "get",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "UUID of event to be searched",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ThreatEvent"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json;charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRepresentation"
                }
              }
            }
          }
        },
        "security": [
          {
            "JwtAuthentication": []
          }
        ]
      }
    }
  },
  "components": {
      "schemas": {
          "AutonomousSystemInfo": {
              "description": "Dns record asn",
              "properties": {
                  "as_number": {
                      "type": "string",
                      "description": "AS Number"
                  },
                  "as_organization": {
                      "type": "string",
                      "description": "AS Organization"
                  }
              }
          },
          "Brand": {
              "description": "Brand associated to the event",
              "properties": {
                  "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Brand id"
                  },
                  "name": {
                      "type": "string",
                      "description": "Brand name"
                  },
                  "monitored_since": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Monitoring creation date"
                  }
              }
          },
          "Comment": {
              "properties": {
                  "content": {
                      "type": "string",
                      "description": "Comment content"
                  },
                  "date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Comment publication date"
                  }
              }
          },
          "Criticality": {
              "description": "Event criticality",
              "properties": {
                  "level": {
                      "type": "string",
                      "description": "Criticality level"
                  },
                  "name": {
                      "type": "string",
                      "description": "Criticality name"
                  }
              }
          },
          "DnsRecord": {
              "description": "Dns records of the domain observed",
              "properties": {
                  "country_code": {
                      "type": "string",
                      "description": "Dns record country code"
                  },
                  "ip": {
                      "type": "string",
                      "description": "Dns record ip"
                  },
                  "name": {
                      "type": "string",
                      "description": "Dns record name"
                  },
                  "type": {
                      "type": "string",
                      "description": "Dns record type"
                  },
                  "origin": {
                      "type": "string",
                      "description": "Dns record origin"
                  },
                  "autonomous_system_info": {
                      "$ref": "#/components/schemas/AutonomousSystemInfo"
                  }
              }
          },
          "PaginatedThreatEvent": {
              "description": "Paginated thread events",
              "properties": {
                  "data": {
                      "type": "array",
                      "items": {
                          "$ref": "#/components/schemas/ThreatEvent"
                      }
                  },
                  "current_page": {
                      "type": "integer",
                      "format": "int32"
                  },
                  "total_pages": {
                      "type": "integer",
                      "format": "int32"
                  },
                  "total_items": {
                      "type": "integer",
                      "format": "int64"
                  },
                  "page_size": {
                      "type": "integer",
                      "format": "int32"
                  },
                  "has_next": {
                      "type": "boolean"
                  },
                  "has_previous": {
                      "type": "boolean"
                  }
              }
          },
          "ThreatEvent": {
              "description": "Represents a threat event",
              "properties": {
                  "id": {
                      "type": "string",
                      "description": "Event identifier"
                  },
                  "date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date of the event (UTC). Format : yyyy-MM-dd'T'HH:mm:ss.SSSXXX",
                      "example": "2024-11-18T13:39:42Z"
                  },
                  "type": {
                      "type": "string",
                      "description": "Event type"
                  },
                  "customer_id": {
                      "type": "integer",
                      "format": "int32",
                      "description": "Customer id related to the event"
                  },
                  "brand": {
                      "$ref": "#/components/schemas/Brand"
                  },
                  "domain": {
                      "type": "string",
                      "description": "The domain related to the event"
                  },
                  "observed_data": {
                      "$ref": "#/components/schemas/ThreatEventObservedData"
                  },
                  "criticality": {
                      "$ref": "#/components/schemas/Criticality"
                  },
                  "comments": {
                      "type": "array",
                      "items": {
                          "$ref": "#/components/schemas/Comment"
                      }
                  }
              }
          },
          "ThreatEventObservedData": {
              "description": "Payload of a domain threat event",
              "properties": {
                  "dns_records": {
                      "type": "array",
                      "description": "Dns records of the domain observed",
                      "items": {
                          "$ref": "#/components/schemas/DnsRecord"
                      }
                  },
                  "whois": {
                      "$ref": "#/components/schemas/Whois"
                  },
                  "website": {
                      "$ref": "#/components/schemas/Website"
                  }
              }
          },
          "Website": {
              "description": "Website information of the domain observed",
              "properties": {
                  "page_title": {
                      "type": "string",
                      "description": "Webiste page title"
                  },
                  "page_description": {
                      "type": "string",
                      "description": "Website page description"
                  },
                  "origin_url": {
                      "type": "string",
                      "description": "Website origin url"
                  },
                  "final_url": {
                      "type": "string",
                      "description": "Website final url"
                  },
                  "redirection_types": {
                      "type": "array",
                      "description": "Redirection types",
                      "items": {
                          "type": "string",
                          "description": "Redirection types"
                      },
                      "uniqueItems": true
                  },
                  "screenshot_resource_id": {
                      "type": "string",
                      "writeOnly": true
                  },
                  "screenshot_resource_url": {
                      "type": "string"
                  },
                  "source_resource_id": {
                      "type": "string",
                      "writeOnly": true
                  },
                  "source_resource_url": {
                      "type": "string"
                  }
              }
          },
          "Whois": {
              "description": "Whois of the domain observed",
              "properties": {
                  "owner_name": {
                      "type": "string",
                      "description": "Whois owner name"
                  },
                  "owner_email": {
                      "type": "string",
                      "description": "Whois owner email"
                  },
                  "owner_organisation": {
                      "type": "string",
                      "description": "Whois owner organisation"
                  },
                  "admin_name": {
                      "type": "string",
                      "description": "Whois admin name"
                  },
                  "admin_email": {
                      "type": "string",
                      "description": "Whois admin email"
                  },
                  "admin_organisation": {
                      "type": "string",
                      "description": "Whois admin organisation"
                  },
                  "registrar_name": {
                      "type": "string",
                      "description": "Whois registrar name"
                  },
                  "statuses": {
                      "type": "array",
                      "description": "Whois statuses",
                      "items": {
                          "type": "string",
                          "description": "Whois statuses"
                      }
                  },
                  "expiration_date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Whois domain expiration date"
                  },
                  "creation_date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Whois domain creation date"
                  },
                  "updated_date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Whois update date"
                  },
                  "resource_url": {
                      "type": "string"
                  },
                  "resource_id": {
                      "type": "string"
                  }
              }
          },
          "ErrorResponseRepresentation": {
              "description": "Represents the API error response",
              "properties": {
                  "timestamp": {
                      "type": "integer",
                      "format": "int64"
                  },
                  "status": {
                      "type": "integer",
                      "format": "int32"
                  },
                  "error": {
                      "type": "string"
                  },
                  "exception": {
                      "type": "string"
                  },
                  "message": {
                      "type": "string"
                  },
                  "path": {
                      "type": "string"
                  },
                  "errors": {
                      "type": "array",
                      "description": "List of errors",
                      "items": {
                          "type": "object",
                          "description": "List of errors"
                      }
                  }
              }
          }
      },
      "securitySchemes": {
          "JwtAuthentication": {
              "type": "http",
              "scheme": "bearer"
          }
      }
  }
}