> ## 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.

# GET /api/v1/lookup — enrich a single IOC

> Enrich a single IP, domain, URL, or file hash with AI risk scoring, MITRE ATT&CK techniques, and auto-generated Splunk and KQL hunting queries. Free tier.

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

<ParamField query="value" type="string" required>
  The indicator value to enrich (e.g. `192.0.2.1`, `evil.com`, a file hash).
</ParamField>

<ParamField query="type" 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.
</ParamField>

## Example request

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

## Response

```json theme={null}
{
  "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

<ResponseField name="value" type="string">
  The indicator value that was queried.
</ResponseField>

<ResponseField name="type" type="string">
  The detected or specified IOC type (e.g. `ipv4`, `domain`, `sha256`).
</ResponseField>

<ResponseField name="risk_score" type="string">
  AI-generated risk rating for this indicator. One of: `critical`, `high`, `medium`, `low`.
</ResponseField>

<ResponseField name="confidence" type="string">
  Confidence level assigned by the source feed(s). One of: `high`, `medium`, `low`.
</ResponseField>

<ResponseField name="mitre_techniques" type="array">
  MITRE ATT\&CK techniques associated with this indicator.

  <Expandable title="properties">
    <ResponseField name="mitre_techniques[].id" type="string">
      MITRE ATT\&CK technique ID (e.g. `T1071`).
    </ResponseField>

    <ResponseField name="mitre_techniques[].name" type="string">
      Human-readable technique name (e.g. `Application Layer Protocol`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hunting_queries" type="object">
  Auto-generated detection queries for common SIEM platforms.

  <Expandable title="properties">
    <ResponseField name="hunting_queries.splunk" type="string">
      SPL (Search Processing Language) query for Splunk.
    </ResponseField>

    <ResponseField name="hunting_queries.kql" type="string">
      KQL (Kusto Query Language) query for Microsoft Sentinel or Microsoft Defender.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sources" type="array">
  List of source feeds that have reported this indicator.

  <Expandable title="properties">
    <ResponseField name="sources[].feed_name" type="string">
      Name of the source feed (e.g. `CISA Alerts`).
    </ResponseField>

    <ResponseField name="sources[].category" type="string">
      Category of the source feed (e.g. `government`, `commercial`, `community`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

If your API key is missing or invalid, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "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](/api-reference/authentication) for the full error code reference.