openapi: 3.1.0
info:
  title: phishunt API
  description: |
    Real-time phishing intelligence data. All endpoints are free and require no authentication.

    The detection pipeline monitors multiple threat intelligence sources (OpenPhish, PhishTank, TweetFeed, urlscan.io, Google Safe Browsing) and Certificate Transparency logs to detect active suspicious phishing sites.

    **Rate limiting:** 10 requests/second per IP with burst allowance of 20. Exceeding this returns HTTP 429.

    **Caching:** All responses are cached for 5 minutes. Data is refreshed every hour by the detection pipeline.
  version: "1.0"
  contact:
    name: phishunt
    url: https://phishunt.io/contact/
    email: info@phishunt.io
  license:
    name: Free to use
    url: https://phishunt.io/tos/

servers:
  - url: https://phishunt.io
    description: Production

paths:
  /api/v1/domains:
    get:
      operationId: getDomains
      summary: Get domains
      description: |
        Returns a list of active suspicious phishing domains with full enrichment data including IP geolocation, TLS certificate information, and detection verdicts from multiple threat intelligence sources.
      parameters:
        - name: limit
          in: query
          description: Number of results to return.
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
        - name: offset
          in: query
          description: Number of results to skip (for pagination).
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 10000
        - name: format
          in: query
          description: Response format.
          required: false
          schema:
            type: string
            enum: [json, csv, txt]
            default: json
        - name: company
          in: query
          description: Filter by targeted brand (e.g. `amazon`, `paypal`, `microsoft`).
          required: false
          schema:
            type: string
        - name: since
          in: query
          description: Only return entries detected after this date.
          required: false
          schema:
            type: string
            format: date
            example: "2026-03-01"
      responses:
        "200":
          description: List of suspicious phishing domains.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainsResponse"
              example:
                count: 2
                offset: 0
                limit: 100
                results:
                  - url: "https://amazon.example-phish.com/signin"
                    domain: "amazon.example-phish.com"
                    company: "amazon"
                    date: "2026-03-27T14:30:00+00:00"
                    first_seen: "2026-03-25T09:12:00+00:00"
                    uuid: "54889cb5-146d-484f-8b94-7a0b7385bff7"
                    ip: "198.51.100.42"
                    country: "United States"
                    asn: "64496"
                    org: "Example Hosting Inc."
                    cert: "Let's Encrypt R3"
                    malicious_google: false
                    malicious_openphish: true
                    malicious_phishtank: false
                    malicious_tweetfeed: false
                    malicious_urlscan: true
        "400":
          description: Bad request — invalid parameter value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: "Invalid 'since' parameter. Use ISO 8601 format (e.g. 2026-03-01)."
        "429":
          description: Rate limited (max 10 requests/second).

  /feed.json:
    get:
      operationId: getFeedJson
      summary: Feed (JSON)
      description: Download the complete active suspicious phishing feed in JSON format. Updated every hour.
      responses:
        "200":
          description: JSON array of all active suspicious phishing sites.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Site"

  /feed.csv:
    get:
      operationId: getFeedCsv
      summary: Feed (CSV)
      description: Download the complete active suspicious phishing feed in CSV format. Updated every hour.
      responses:
        "200":
          description: CSV file with headers.
          content:
            text/csv:
              schema:
                type: string

  /feed.txt:
    get:
      operationId: getFeedTxt
      summary: Feed (TXT)
      description: Download all active suspicious phishing URLs, one per line. Updated every hour.
      responses:
        "200":
          description: Plain text, one URL per line.
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    DomainsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Number of results returned.
        offset:
          type: integer
          description: Current offset (for pagination).
        limit:
          type: integer
          description: Current limit (for pagination).
        results:
          type: array
          items:
            $ref: "#/components/schemas/Site"

    Site:
      type: object
      properties:
        url:
          type: string
          description: Full URL of the suspicious site.
        domain:
          type: string
          description: Domain name including subdomains.
        company:
          type: string
          description: Targeted brand identifier.
        date:
          type: string
          format: date-time
          description: Last check timestamp (ISO 8601).
        first_seen:
          type: string
          format: date-time
          description: When the site was first detected (ISO 8601).
        uuid:
          type: string
          format: uuid
          description: Unique identifier for this entry (UUID v4).
        ip:
          type: string
          description: Resolved IPv4 address.
        country:
          type: string
          description: Hosting country name.
        asn:
          type: string
          description: Autonomous System Number.
        org:
          type: string
          description: Hosting organization.
        cert:
          type: string
          description: TLS certificate issuer.
        malicious_google:
          type: boolean
          description: "true if flagged by Google Safe Browsing."
        malicious_openphish:
          type: boolean
          description: "true if present in OpenPhish feed."
        malicious_phishtank:
          type: boolean
          description: "true if present in PhishTank feed."
        malicious_tweetfeed:
          type: boolean
          description: "true if present in TweetFeed."
        malicious_urlscan:
          type: boolean
          description: "true if flagged by urlscan.io."
