> ## 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/iocs/search — search for a specific IOC

> Search for a specific indicator value across the entire SOC Defenders IOC feed. Returns matching entries with enrichment data. Free tier.

The `/api/v1/iocs/search` endpoint lets you look up a specific indicator value — such as an IP address, domain, or file hash — across the entire SOC Defenders feed. Unlike the list endpoint, which filters by attributes, this endpoint matches against the indicator value itself. Use it when you have a specific observable and want to know whether the feed has seen it, and if so, with what confidence and from which sources.

## Request

**Method:** `GET`\
**URL:** `https://socdefenders.ai/api/v1/iocs/search`\
**Auth:** Required — `Authorization: Bearer sk_live_YOUR_KEY`\
**Tier:** Free

## Query parameters

<ParamField query="q" type="string" required>
  The IOC value to search for. For example, an IP address (`1.2.3.4`), a domain (`evil.com`), or a file hash (`abc123...`).
</ParamField>

<ParamField query="type" type="string">
  Narrow the search to a specific IOC type. One of: `ipv4`, `ipv6`, `domain`, `url`, `md5`, `sha1`, `sha256`, `cve`, `mitre-attack`, `email`. Useful when a value could be interpreted as more than one type.
</ParamField>

## Example request

```bash theme={null}
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/iocs/search?q=evil-domain.com"
```

## Response

The response uses the same structure as `GET /api/v1/iocs`, filtered to entries that match the queried value:

```json theme={null}
{
  "meta": { "total": 1, "limit": 100, "offset": 0 },
  "data": [
    {
      "type": "domain",
      "value": "evil-domain.com",
      "confidence": "high",
      "source": {
        "feed_name": "CISA Alerts",
        "category": "government"
      }
    }
  ]
}
```

### Response fields

<ResponseField name="meta" type="object">
  Pagination metadata for the response.

  <Expandable title="properties">
    <ResponseField name="meta.total" type="integer">
      Total number of matching IOC entries across all sources.
    </ResponseField>

    <ResponseField name="meta.limit" type="integer">
      The `limit` value applied to this response.
    </ResponseField>

    <ResponseField name="meta.offset" type="integer">
      The `offset` value applied to this response.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  Array of IOC objects matching the queried value.

  <Expandable title="properties">
    <ResponseField name="data[].type" type="string">
      IOC type. One of: `ipv4`, `ipv6`, `domain`, `url`, `md5`, `sha1`, `sha256`, `cve`, `mitre-attack`, `email`.
    </ResponseField>

    <ResponseField name="data[].value" type="string">
      The indicator value that was matched.
    </ResponseField>

    <ResponseField name="data[].confidence" type="string">
      Feed confidence rating: `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="data[].source.feed_name" type="string">
      Name of the source feed that reported this indicator.
    </ResponseField>

    <ResponseField name="data[].source.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.