Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.socdefenders.ai/llms.txt

Use this file to discover all available pages before exploring further.

The /api/v1/lookup endpoint enriches a single indicator of compromise with contextual threat intelligence. For a given IP address, domain, URL, or file hash, it returns an AI-generated risk score, associated MITRE ATT&CK techniques, the source feeds that have reported the indicator, and auto-generated detection queries ready to deploy in Splunk or Microsoft Sentinel. Use this endpoint for on-demand triage during an investigation or to enrich alerts in your SOAR playbook.

​
Request

Method: GET
URL: https://socdefenders.ai/api/v1/lookup
Auth: Required — Authorization: Bearer sk_live_YOUR_KEY
Tier: Free

​
Query parameters

​
value
string
required
The indicator value to enrich (e.g. 192.0.2.1, evil.com, a file hash).
​
type
string
IOC type hint for disambiguation. One of: ipv4, ipv6, domain, url, md5, sha1, sha256, cve, mitre-attack, email. Providing this speeds up resolution when a value is ambiguous.

​
Example request

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/lookup?value=192.0.2.1&type=ipv4"

​
Response

{
  "value": "192.0.2.1",
  "type": "ipv4",
  "risk_score": "high",
  "confidence": "high",
  "mitre_techniques": [
    {
      "id": "T1071",
      "name": "Application Layer Protocol"
    },
    {
      "id": "T1041",
      "name": "Exfiltration Over C2 Channel"
    }
  ],
  "hunting_queries": {
    "splunk": "index=* dest_ip=\"192.0.2.1\" | stats count by src_ip, dest_ip, dest_port | sort -count",
    "kql": "NetworkCommunicationEvents | where RemoteIP == \"192.0.2.1\" | summarize count() by LocalIP, RemoteIP, RemotePort"
  },
  "sources": [
    {
      "feed_name": "CISA Alerts",
      "category": "government"
    },
    {
      "feed_name": "Emerging Threats",
      "category": "community"
    }
  ]
}

​
Response fields

​
value
string
The indicator value that was queried.
​
type
string
The detected or specified IOC type (e.g. ipv4, domain, sha256).
​
risk_score
string
AI-generated risk rating for this indicator. One of: critical, high, medium, low.
​
confidence
string
Confidence level assigned by the source feed(s). One of: high, medium, low.
​
mitre_techniques
array
MITRE ATT&CK techniques associated with this indicator.
​
hunting_queries
object
Auto-generated detection queries for common SIEM platforms.
​
sources
array
List of source feeds that have reported this indicator.

​
Error responses

If your API key is missing or invalid, the API returns a 401 Unauthorized response: 
{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in the Authorization header as \"Bearer sk_live_...\" or in the X-API-Key header.",
    "request_id": "req_..."
  }
}
See Authentication for the full error code reference.