> ## 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. # Single-IOC enrichment with AI risk + hunting queries > VirusTotal-style enrichment for one indicator. Auto-detects the type from the value (no need to pass `type=` unless overriding). ## What you get - **Aggregated source reports**: every feed that has seen this indicator - **First/last seen** timestamps across all sources - **Confidence** (high/medium/low) — calculated from source reputation + recency - **Tags + malware family** (when available) - **MITRE ATT&CK techniques** referenced in the source articles - **AI risk score** (0-100) and risk level - **Hunting queries**: ready-to-paste Splunk SPL and Sentinel KQL ## When `found: false` A "not found" response is **not** "this is safe" — it just means we have no record. Combine with reputation services (VT, GreyNoise, etc.) for negative conclusions. ## Common use cases ### 1. SOC triage (paste the alert IP) ``` GET /api/v1/lookup?ioc=110.36.30.112 ``` ### 2. Hash triage from sandbox detonation ``` GET /api/v1/lookup?ioc=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` ### 3. CVE risk assessment ``` GET /api/v1/lookup?ioc=CVE-2024-12345 ``` Returns CVE + recent articles mentioning it (proxy for "is this actively exploited"). ### 4. Auto-type-detect override ``` GET /api/v1/lookup?ioc=internal.example.com&type=domain ``` Avoids ambiguous detection for short or unusual strings. Available on the **Free plan** with standard 10 req/min limit. ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/v1/lookup 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/lookup: get: tags: - Lookup summary: Single-IOC enrichment with AI risk + hunting queries description: >- VirusTotal-style enrichment for one indicator. Auto-detects the type from the value (no need to pass `type=` unless overriding). ## What you get - **Aggregated source reports**: every feed that has seen this indicator - **First/last seen** timestamps across all sources - **Confidence** (high/medium/low) — calculated from source reputation + recency - **Tags + malware family** (when available) - **MITRE ATT&CK techniques** referenced in the source articles - **AI risk score** (0-100) and risk level - **Hunting queries**: ready-to-paste Splunk SPL and Sentinel KQL ## When `found: false` A "not found" response is **not** "this is safe" — it just means we have no record. Combine with reputation services (VT, GreyNoise, etc.) for negative conclusions. ## Common use cases ### 1. SOC triage (paste the alert IP) ``` GET /api/v1/lookup?ioc=110.36.30.112 ``` ### 2. Hash triage from sandbox detonation ``` GET /api/v1/lookup?ioc=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` ### 3. CVE risk assessment ``` GET /api/v1/lookup?ioc=CVE-2024-12345 ``` Returns CVE + recent articles mentioning it (proxy for "is this actively exploited"). ### 4. Auto-type-detect override ``` GET /api/v1/lookup?ioc=internal.example.com&type=domain ``` Avoids ambiguous detection for short or unusual strings. Available on the **Free plan** with standard 10 req/min limit. operationId: lookupIOC parameters: - name: ioc in: query required: true description: >- The indicator value to look up. Accepts any type — IPv4/IPv6 address, domain, URL, MD5/SHA1/SHA256/SHA512 hash, CVE ID, MITRE technique ID, or email address. schema: type: string maxLength: 2048 example: 110.36.30.112 - name: type in: query description: >- Override the auto-detected type. Useful for ambiguous values (e.g., a short hex string that could be a hash prefix or a domain). schema: type: string enum: - ipv4 - ipv6 - domain - url - md5 - sha1 - sha256 - sha512 - email - cve - mitre_attack example: ipv4 responses: '200': description: >- Lookup result. The `data.found` field is `true` when at least one source reported this IOC; `false` means we have no record (which is not the same as "safe"). content: application/json: schema: $ref: '#/components/schemas/LookupResponse' example: meta: generated_at: '2026-05-16T05:00:00Z' feed_version: '1.0' source: SOC Defenders data: found: true ioc_value: 110.36.30.112 ioc_type: ipv4 confidence: high first_seen: '2026-05-16T04:23:18Z' last_seen: '2026-05-16T04:23:18Z' total_occurrences: 3 reporting_sources: 2 threat_type: malware_hosting malware_family: Mozi tags: - 32-bit - elf - mips - Mozi mitre_techniques: [] risk: score: 78 level: high hunting: detection_guidance: >- Alert on outbound connections to this IP from production servers... splunk_query: index=firewall dest_ip=110.36.30.112 kql_query: DeviceNetworkEvents | where RemoteIP == '110.36.30.112' sources: - source_feed: URLhaus source_category: threat-feed reference_url: https://urlhaus.abuse.ch/host/110.36.30.112/ first_seen: '2026-05-16T04:23:18Z' last_seen: '2026-05-16T04:23:18Z' occurrence_count: 1 confidence: high context: 'malware_hosting: 32-bit, elf, mips, Mozi' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: cURL label: IP triage source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/lookup?ioc=110.36.30.112" - lang: cURL label: Hash triage source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/lookup?ioc=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" - lang: Python label: SOC triage script source: |- import requests def triage(ioc_value): r = requests.get( "https://socdefenders.ai/api/v1/lookup", headers={"Authorization": "Bearer sk_live_..."}, params={"ioc": ioc_value}, ) data = r.json()["data"] if not data["found"]: return f"{ioc_value}: NO RECORD — combine with other sources" return f"{ioc_value}: {data['risk']['level']} risk (score={data['risk']['score']}), {data['reporting_sources']} sources" print(triage("110.36.30.112")) components: schemas: LookupResponse: type: object properties: meta: type: object properties: generated_at: type: string format: date-time feed_version: type: string source: type: string data: type: object properties: found: type: boolean description: True if at least one source has reported this IOC. ioc_value: type: string ioc_type: type: string enum: - ipv4 - ipv6 - domain - url - md5 - sha1 - sha256 - sha512 - email - cve - mitre_attack confidence: type: string enum: - high - medium - low nullable: true first_seen: type: string format: date-time nullable: true last_seen: type: string format: date-time nullable: true total_occurrences: type: integer nullable: true reporting_sources: type: integer nullable: true threat_type: type: string nullable: true malware_family: type: string nullable: true tags: type: array items: type: string mitre_techniques: type: array items: type: string industries: type: array items: type: string risk: type: object nullable: true properties: score: type: integer nullable: true minimum: 0 maximum: 100 level: type: string nullable: true attack_context: type: string nullable: true false_positive_likelihood: type: string nullable: true ioc_lifecycle: type: string nullable: true hunting: type: object nullable: true properties: detection_guidance: type: string nullable: true splunk_query: type: string nullable: true kql_query: type: string nullable: true response_actions: type: string nullable: true related: type: object nullable: true properties: threat_actors: type: array items: type: string campaigns: type: array items: type: string related_ioc_types: type: array items: type: string sources: type: array items: type: object properties: source_feed: type: string nullable: true source_category: type: string nullable: true reference_url: type: string format: uri nullable: true first_seen: type: string format: date-time last_seen: type: string format: date-time occurrence_count: type: integer confidence: type: string context: type: string nullable: true 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 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 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`' ````