API Documentation

Beta

The IOC.FYI API is in beta. It provides programmatic access to IOC lookups with no authentication required. Rate limits and availability are subject to change.

Base URL

https://ioc.fyi/api/v1/

Authentication

No authentication is required. The API is public and free to use.

Rate Limits

Rate limiting is applied per IP address. Exact thresholds are subject to change during the beta period. When rate limited, the API returns HTTP 429 Too Many Requests.

Endpoints

GET /api/v1/

Returns API information and available endpoints.

Example Request

curl https://ioc.fyi/api/v1/

Example Response

{
  "success": true,
  "data": {
    "name": "ioc.fyi API",
    "version": "1.0",
    "endpoints": {
      "ioc_lookup": "/api/v1/ioc/<value>/"
    },
    "rate_limits": {
      "per_minute": 60,
      "per_day": 1000
    }
  },
  "meta": {
    "api_version": "1.0",
    "timestamp": "2026-01-27T12:00:00+00:00"
  }
}

GET /api/v1/ioc/<value>/

Look up an IOC and return matching threat intelligence sources.

Supported IOC Types

Defanged formats are automatically handled (e.g., 8[.]8[.]8[.]8).

Example Request

curl https://ioc.fyi/api/v1/ioc/8.8.8.8/

Example Response (IOC Found)

{
  "success": true,
  "data": {
    "value": "8.8.8.8",
    "ioc_type": "ipv4",
    "ioc_type_display": "IPv4 Address",
    "found": true,
    "is_in_cidr": true,
    "sources": [
      {
        "name": "List of known IPv4 public DNS resolvers",
        "description": "Known public DNS servers",
        "url": "https://github.com/MISP/...",
        "matched_cidrs": []
      }
    ],
    "threat_intel_sources": [...],
    "contextual_sources": [...],
    "matching_cidrs": [...]
  },
  "meta": {
    "api_version": "1.0",
    "timestamp": "2026-01-27T12:00:00+00:00"
  }
}

Example Response (IOC Not Found)

{
  "success": true,
  "data": {
    "value": "192.0.2.1",
    "ioc_type": "ipv4",
    "ioc_type_display": "IPv4 Address",
    "found": false,
    "is_in_cidr": false,
    "sources": [],
    "threat_intel_sources": [],
    "contextual_sources": [],
    "matching_cidrs": []
  },
  "meta": {
    "api_version": "1.0",
    "timestamp": "2026-01-27T12:00:00+00:00"
  }
}

Response Fields

Field Type Description
success boolean Whether the request was successful
data.value string The normalized IOC value
data.ioc_type string Detected IOC type (ipv4, ipv6, domain, md5, etc.)
data.found boolean Whether the IOC was found in any source
data.is_in_cidr boolean Whether the IOC falls within a listed CIDR range
data.sources array All matching sources (combined)
data.threat_intel_sources array Sources categorized as threat intelligence
data.contextual_sources array Sources providing contextual information
data.matching_cidrs array CIDR ranges containing the IP (for IP lookups)

Error Responses

Invalid IOC (400)

{
  "success": false,
  "error": {
    "code": "INVALID_IOC",
    "message": "Unable to detect IOC type for the provided value"
  },
  "meta": {...}
}

Empty Value (400)

{
  "success": false,
  "error": {
    "code": "EMPTY_VALUE",
    "message": "IOC value cannot be empty"
  },
  "meta": {...}
}

Rate Limited (429)

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later."
  },
  "meta": {...}
}

HTTP Status Codes

Code Description
200 Successful lookup (IOC found or not found)
400 Invalid or empty input
405 Method not allowed (only GET is supported)
429 Rate limit exceeded
500 Internal server error

Code Examples

Python

import requests

response = requests.get("https://ioc.fyi/api/v1/ioc/8.8.8.8/")
data = response.json()

if data["success"] and data["data"]["found"]:
    print(f"IOC found in {len(data['data']['sources'])} sources")
else:
    print("IOC not found")

JavaScript

fetch("https://ioc.fyi/api/v1/ioc/8.8.8.8/")
  .then(res => res.json())
  .then(data => {
    if (data.success && data.data.found) {
      console.log(`Found in ${data.data.sources.length} sources`);
    }
  });

Bash / cURL

curl -s "https://ioc.fyi/api/v1/ioc/8.8.8.8/" | jq '.data.found'