> ## 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 — list indicators of compromise

> Retrieve a paginated list of IOCs filtered by type, category, confidence, industry, and time range. Returns JSON with meta and data fields. Free tier.

The `/api/v1/iocs` endpoint returns a paginated list of indicators of compromise from the SOC Defenders feed. You can narrow results by IOC type, confidence level, source category, industry sector, and time range. Use the `since` parameter for delta polling to retrieve only indicators added after a given timestamp — useful for keeping your SIEM or TIP synchronized without re-fetching the full feed.

## Request

**Method:** `GET`\
**URL:** `https://socdefenders.ai/api/v1/iocs`\
**Auth:** Required — `Authorization: Bearer sk_live_YOUR_KEY`\
**Tier:** Free (up to 100 results per request; Pro raises this to 10,000)

## Query parameters

<ParamField query="type" type="string">
  Filter by IOC type. One of: `ipv4`, `ipv6`, `domain`, `url`, `md5`, `sha1`, `sha256`, `cve`, `mitre-attack`, `email`.
</ParamField>

<ParamField query="confidence" type="string">
  Filter by confidence level. One of: `high`, `medium`, `low`.
</ParamField>

<ParamField query="category" type="string">
  Filter by source category. Common values: `government`, `commercial`, `community`.
</ParamField>

<ParamField query="industry" type="string">
  Filter by CISA sector name (e.g. `energy`, `healthcare`, `financial-services`).
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Returns only IOCs added or updated after this time. Use for delta polling (e.g. `2024-01-01T00:00:00Z`).
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum number of results to return. Free tier: 100. Pro tier: up to 10,000.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination. Use with `limit` to page through large result sets.
</ParamField>

## Example request

```bash theme={null}
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/iocs?type=ipv4&confidence=high&limit=100"
```

## Response

```json theme={null}
{
  "meta": { "total": 1523, "limit": 100, "offset": 0 },
  "data": [
    {
      "type": "ipv4",
      "value": "192.168.1.100",
      "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 IOCs matching the applied filters, regardless of `limit`.
    </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 query.

  <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 (e.g. an IP address, domain name, or file hash).
    </ResponseField>

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

    <ResponseField name="data[].source.feed_name" type="string">
      Name of the source feed that reported this indicator (e.g. `CISA Alerts`).
    </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.