> ## 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. # List IOCs (Indicators of Compromise) > The primary IOC export endpoint. Returns indicators of compromise — IPs, domains, URLs, file hashes, email addresses, CVEs, and MITRE ATT&CK technique IDs — extracted from articles and ingested from threat feeds (URLhaus, Feodo Tracker, ThreatFox). ## What's an IOC? An *Indicator of Compromise* is a forensic artifact that suggests a system has been compromised. The feed mixes: - **Article-extracted IOCs**: pulled out of writeups by our extraction pipeline (`source.origin: "article"`) - **Feed-sourced IOCs**: ingested directly from threat-intel feeds (`source.origin: "feed"`) ## Common use cases ### 1. SIEM block-list ingestion (recent IPs) ``` GET /api/v1/iocs?type=ipv4&confidence=high&since=2026-05-16T00:00:00Z&format=txt ``` Returns one IP per line — perfect for piping into a firewall block-list. ### 2. Hash IOCs for EDR detection ``` GET /api/v1/iocs?type=sha256&confidence=high&limit=1000 ``` ### 3. APT-tagged IOCs for threat hunting ``` GET /api/v1/iocs?industry=finance&since=2026-05-01T00:00:00Z&limit=500 ``` ### 4. CSV export for spreadsheet analysis ``` GET /api/v1/iocs?type=domain&format=csv&limit=1000 ``` ## Output formats - `json` (default): structured response with metadata + pagination - `csv`: 10-column CSV — id, type, value, confidence, first_seen, last_seen, source_article, source_feed, category, tags - `txt`: bare IOC values one per line — for direct firewall/EDR ingestion ## Tier behavior | Tier | Per request | Lookback | Formats | |------|-------------|----------|---------| | Free | 100 | 1 day | json only | | Pro | 10,000 | 365 days | json, csv, txt | ## Pagination Standard `offset` + `limit`. For walks past ~1k offsets, use the Articles endpoint pattern (cursor) or narrow your time window. ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/v1/iocs openapi: 3.0.3 info: title: SOC Defenders Threat Intelligence API description: >- # Overview The SOC Defenders Threat Intelligence API provides programmatic access to aggregated threat intelligence from 30+ cybersecurity sources. Export IOCs (Indicators of Compromise) in various formats including JSON, CSV, STIX 2.1, MISP, CEF, and OpenIOC. ## Authentication All API endpoints require authentication using an API key. Include your key in one of these ways: - **Authorization Header** (recommended): `Authorization: Bearer sk_live_xxx` - **X-API-Key Header**: `X-API-Key: sk_live_xxx` - **Query Parameter**: `?api_key=sk_live_xxx` ## Rate Limiting Rate limits vary by tier. When limits are exceeded, the API returns a 429 status code. | Tier | Requests/min | Requests/day | Lookback | Formats | |------|-------------|--------------|----------|---------| | Free | 10 | 1,000 | 1 day | JSON / CSV | | Pro ($299/mo) | 1,000 | 1,000,000 | 365 days | All (STIX, TAXII, MISP, CEF, OpenIOC, Sigma) | Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests per minute - `X-RateLimit-Remaining`: Requests remaining in current window - `X-RateLimit-Reset`: Unix timestamp when the limit resets ## Error Handling All errors follow a consistent format: ```json { "error": { "code": "error_code", "message": "Human readable message", "details": {}, "request_id": "req_abc123" } } ``` ## STIX/TAXII Support For STIX 2.1 and TAXII 2.1 integration, see the TAXII endpoints section. TAXII endpoints are available at `/api/taxii2/`. version: 1.0.0 contact: name: SOC Defenders Support url: https://socdefenders.ai/contact email: support@socdefenders.ai license: name: Proprietary url: https://socdefenders.ai/terms servers: - url: https://socdefenders.ai description: Production server security: [] tags: - name: IOCs description: Indicators of Compromise endpoints - name: Statistics description: Feed and IOC statistics - name: API Keys description: API key management (requires session auth) - name: TAXII description: TAXII 2.1 threat intelligence sharing endpoints - name: Export Formats description: Specialized export format endpoints (MISP, CEF, OpenIOC) - name: Articles description: >- Aggregated news articles from 30+ cybersecurity sources, with rich filtering and bulk-export support - name: Lookup description: >- Single-IOC enrichment lookup. Auto-detects type, aggregates reporting sources, returns AI risk + MITRE techniques + hunting queries. Free-tier friendly. - name: Detection Rules description: >- Generate ready-to-deploy SIEM detection rules from recent IOCs. Sigma rules ship as multi-document YAML covering network / DNS / proxy / process_creation logsources. paths: /api/v1/iocs: get: tags: - IOCs summary: List IOCs (Indicators of Compromise) description: >- The primary IOC export endpoint. Returns indicators of compromise — IPs, domains, URLs, file hashes, email addresses, CVEs, and MITRE ATT&CK technique IDs — extracted from articles and ingested from threat feeds (URLhaus, Feodo Tracker, ThreatFox). ## What's an IOC? An *Indicator of Compromise* is a forensic artifact that suggests a system has been compromised. The feed mixes: - **Article-extracted IOCs**: pulled out of writeups by our extraction pipeline (`source.origin: "article"`) - **Feed-sourced IOCs**: ingested directly from threat-intel feeds (`source.origin: "feed"`) ## Common use cases ### 1. SIEM block-list ingestion (recent IPs) ``` GET /api/v1/iocs?type=ipv4&confidence=high&since=2026-05-16T00:00:00Z&format=txt ``` Returns one IP per line — perfect for piping into a firewall block-list. ### 2. Hash IOCs for EDR detection ``` GET /api/v1/iocs?type=sha256&confidence=high&limit=1000 ``` ### 3. APT-tagged IOCs for threat hunting ``` GET /api/v1/iocs?industry=finance&since=2026-05-01T00:00:00Z&limit=500 ``` ### 4. CSV export for spreadsheet analysis ``` GET /api/v1/iocs?type=domain&format=csv&limit=1000 ``` ## Output formats - `json` (default): structured response with metadata + pagination - `csv`: 10-column CSV — id, type, value, confidence, first_seen, last_seen, source_article, source_feed, category, tags - `txt`: bare IOC values one per line — for direct firewall/EDR ingestion ## Tier behavior | Tier | Per request | Lookback | Formats | |------|-------------|----------|---------| | Free | 100 | 1 day | json only | | Pro | 10,000 | 365 days | json, csv, txt | ## Pagination Standard `offset` + `limit`. For walks past ~1k offsets, use the Articles endpoint pattern (cursor) or narrow your time window. operationId: listIOCs parameters: - name: type in: query description: >- Filter by IOC type. Common: `ipv4`, `domain`, `sha256`. Less common: `email`, `cve` (use `/api/v1/articles?cve_text_search=` for CVE search), `mitre_attack` (technique IDs). schema: type: string enum: - ipv4 - ipv6 - domain - url - md5 - sha1 - sha256 - sha512 - email - cve - mitre_attack example: ipv4 - name: category in: query description: >- Filter by the originating source category. `threat-intel` = direct from threat feeds (URLhaus etc.). `news`/`research`/`vendor`/`government` = extracted from articles in that category. schema: type: string enum: - news - research - threat-intel - vendor - government example: threat-intel - name: confidence in: query description: >- Filter by confidence level. `high` = both source and extraction high-confidence; use this for automated blocking. `medium`/`low` are for review/analyst surfacing. schema: type: string enum: - high - medium - low example: high - name: industry in: query description: >- Filter to IOCs tagged with a target industry sector. Available: `finance`, `healthcare`, `government`, `technology`, `manufacturing`, `retail`, `energy`, `education`, `telecom`, `transportation`, `defense`, `water`. schema: type: string example: finance - name: since in: query description: >- Lower time bound on `extracted_at` (ISO 8601). Silently clamped to your tier lookback. schema: type: string format: date-time example: '2026-05-16T00:00:00Z' - name: until in: query description: Upper time bound on `extracted_at` (ISO 8601). schema: type: string format: date-time example: '2026-05-17T00:00:00Z' - name: limit in: query description: >- Max results per request. Tier-capped (Free=100, Pro=10000). Use the [Articles endpoint](#operation/listArticles) with cursor pagination for unbounded scans. schema: type: integer minimum: 1 maximum: 10000 default: 100 example: 500 - name: offset in: query description: >- Pagination offset. Cheap up to ~1000; for deeper walks narrow your time window instead. schema: type: integer minimum: 0 default: 0 example: 0 - name: format in: query description: >- `json` (full envelope), `csv` (10 columns), `txt` (bare values one per line — drop directly into firewall/EDR). schema: type: string enum: - json - csv - txt default: json example: txt - name: include_context in: query description: >- When false, the `context` field is omitted from each IOC (saves ~30% payload on average). Useful for SIEM ingestion that only needs the value. schema: type: boolean default: true example: false responses: '200': description: Successful response headers: X-RateLimit-Limit: description: Rate limit ceiling for this endpoint schema: type: integer X-RateLimit-Remaining: description: Remaining requests in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when limit resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/IOCListResponse' example: meta: total: 1523 limit: 100 offset: 0 generated_at: '2024-12-09T10:30:00Z' feed_version: '1.0' source: SOC Defenders filters: type: all category: all confidence: all since: '2024-12-08T00:00:00Z' until: '2024-12-09T10:30:00Z' data: - id: 123e4567-e89b-12d3-a456-426614174000 type: ipv4 value: 192.168.1.1 confidence: high first_seen: '2024-12-08T14:30:00Z' last_seen: '2024-12-09T08:15:00Z' source: article_id: abc123 article_title: New APT Campaign Targeting Financial Sector article_url: https://socdefenders.ai/item/abc123 feed_name: Krebs on Security category: news context: C2 server used in APT28 campaign tags: - apt28 - c2 - financial mitre_techniques: - T1071 - T1059 links: self: https://socdefenders.ai/api/v1/iocs?limit=100&offset=0 next: https://socdefenders.ai/api/v1/iocs?limit=100&offset=100 text/csv: schema: type: string example: >- id,type,value,confidence,first_seen,last_seen,source_article,source_feed,category,tags 123e4567-e89b-12d3-a456-426614174000,ipv4,192.168.1.1,high,2024-12-08T14:30:00Z,2024-12-09T08:15:00Z,abc123,Krebs on Security,news,"apt28,c2" text/plain: schema: type: string example: |- 192.168.1.1 10.0.0.1 example.com '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: cURL label: Recent high-confidence IPs source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/iocs?type=ipv4&confidence=high&since=2026-05-16T00:00:00Z&limit=500" - lang: cURL label: Plain-text feed for firewall block-list source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/iocs?type=ipv4&format=txt&limit=1000" \ -o /etc/firewall/socdef-iplist.txt - lang: Python label: Ingest into SIEM source: |- import requests r = requests.get( "https://socdefenders.ai/api/v1/iocs", headers={"Authorization": "Bearer sk_live_..."}, params={"type": "sha256", "confidence": "high", "limit": 1000}, ) for ioc in r.json()["data"]: siem.add_indicator(value=ioc["value"], type="hash", confidence=ioc["confidence"]) components: schemas: IOCListResponse: type: object properties: meta: type: object properties: total: type: integer description: Total matching IOCs limit: type: integer description: Results per page offset: type: integer description: Current offset generated_at: type: string format: date-time feed_version: type: string source: type: string filters: type: object data: type: array items: $ref: '#/components/schemas/IOC' links: type: object properties: self: type: string format: uri next: type: string format: uri prev: type: string format: uri IOC: type: object properties: id: type: string format: uuid description: Unique IOC identifier type: type: string enum: - ipv4 - ipv6 - domain - url - md5 - sha1 - sha256 - sha512 - email - cve - mitre_attack description: IOC type value: type: string description: The IOC value (IP, hash, domain, etc.) confidence: type: string enum: - high - medium - low description: Confidence level first_seen: type: string format: date-time description: First observation timestamp last_seen: type: string format: date-time description: Most recent observation timestamp source: type: object properties: article_id: type: string description: Source article ID article_title: type: string description: Source article title article_url: type: string format: uri description: Link to source article feed_name: type: string description: Name of the source feed category: type: string description: Feed category context: type: string description: Additional context about the IOC tags: type: array items: type: string description: Tags associated with this IOC mitre_techniques: type: array items: type: string description: Related MITRE ATT&CK techniques Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code for programmatic handling message: type: string description: Human-readable error message details: type: object description: Additional error details request_id: type: string description: Unique request identifier for support responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_parameter message: 'Invalid IOC type: invalid' details: valid_types: - ipv4 - ipv6 - domain - url - md5 - sha1 - sha256 request_id: req_abc123 Unauthorized: description: Authentication required or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: missing_api_key message: >- API key is required. Include it in the Authorization header as "Bearer sk_live_..." request_id: req_abc123 Forbidden: description: Insufficient permissions or scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope message: This endpoint requires the "read:stix" scope details: required_scope: read:stix your_scopes: - read:iocs upgrade_url: https://socdefenders.ai/export#pricing request_id: req_abc123 RateLimitExceeded: description: Rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Rate limit ceiling schema: type: integer X-RateLimit-Remaining: description: Remaining requests (will be 0) schema: type: integer X-RateLimit-Reset: description: Unix timestamp when limit resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: Rate limit exceeded. Please wait before making more requests. details: limit: 10 reset_at: '2024-12-09T10:31:00Z' tier: free upgrade_url: https://socdefenders.ai/export#pricing request_id: req_abc123 InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An internal error occurred. Please try again later. request_id: req_abc123 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key in X-API-Key header BearerAuth: type: http scheme: bearer description: 'API key in Authorization header: `Authorization: Bearer sk_live_xxx`' ````