> ## 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. # Search for a specific IOC value > Look up a specific IOC (IP, domain, hash, URL, CVE, etc.) and get back every record from across the feed plus related indicators from the same article or campaign. ## Strategy Two-stage lookup: 1. **Exact match** against `ioc_value_normalized` (btree-indexed, ~5ms). Lowercased + URL-canonicalized + IPv6-zero-compressed. 2. **Trigram fallback** if no exact match. Requires ≥3 characters and uses the `pg_trgm` GIN index on the value column. ## Use cases - **Triage**: pasted IP from an alert → "is this in our threat intel?" - **Pivot**: found a hash → fetch the article + the other IOCs from the same report - **Verification**: confirm a domain hasn't been flagged elsewhere ## Related IOCs When `include_related=true` (default), the response includes up to 10 IOCs from the same source article. Useful for hash → campaign expansion. ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/v1/iocs/search 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/search: get: tags: - IOCs summary: Search for a specific IOC value description: >- Look up a specific IOC (IP, domain, hash, URL, CVE, etc.) and get back every record from across the feed plus related indicators from the same article or campaign. ## Strategy Two-stage lookup: 1. **Exact match** against `ioc_value_normalized` (btree-indexed, ~5ms). Lowercased + URL-canonicalized + IPv6-zero-compressed. 2. **Trigram fallback** if no exact match. Requires ≥3 characters and uses the `pg_trgm` GIN index on the value column. ## Use cases - **Triage**: pasted IP from an alert → "is this in our threat intel?" - **Pivot**: found a hash → fetch the article + the other IOCs from the same report - **Verification**: confirm a domain hasn't been flagged elsewhere ## Related IOCs When `include_related=true` (default), the response includes up to 10 IOCs from the same source article. Useful for hash → campaign expansion. operationId: searchIOCs parameters: - name: q in: query required: true description: >- IOC value to search for. Accepts any type (IPv4/IPv6, domain, URL, MD5/SHA1/SHA256/SHA512, email, CVE ID, MITRE technique). Auto-normalized for lookup. schema: type: string minLength: 2 example: 192.168.1.1 - name: include_related in: query description: >- When true (default), the response includes up to 10 IOCs from the same source article — useful for pivot/expansion workflows. schema: type: boolean default: true example: true responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: meta: generated_at: '2026-05-17T10:30:00Z' feed_version: '1.0' source: SOC Defenders data: found: true query: 192.168.1.1 matches: - id: 6fc99fbc-2c24-4ce2-8b42-48065d4976e7 type: ipv4 value: 192.168.1.1 confidence: high first_seen: '2026-05-15T08:21:30Z' last_seen: '2026-05-16T18:42:11Z' source: article_id: c59a6bb4-f69a-4b90-babe-ca1afcda3514 article_title: New botnet observed beaconing to home routers article_url: >- https://socdefenders.ai/item/c59a6bb4-f69a-4b90-babe-ca1afcda3514 reference_url: https://krebsonsecurity.com/... feed_name: Krebs on Security category: threat-intel origin: article context: C2 server IP referenced in botnet writeup. tags: - c2 - botnet mitre_techniques: - T1071 relatedIOCs: - id: ... type: domain value: c2.example.com confidence: high first_seen: '2026-05-15T08:21:30Z' last_seen: '2026-05-15T08:21:30Z' source: article_id: c59a6bb4-... article_title: New botnet observed beaconing to home routers article_url: https://socdefenders.ai/item/c59a6bb4-... reference_url: null feed_name: Krebs on Security category: threat-intel origin: article tags: - c2 - botnet mitre_techniques: - T1071 meta: total_matches: 1 related_count: 1 search_time_ms: 12 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: cURL label: Search an IP source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/iocs/search?q=192.168.1.1" - lang: cURL label: Search a SHA256 source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/iocs/search?q=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" components: schemas: SearchResponse: 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: Whether any matches were found query: type: string description: The search query matches: type: array items: $ref: '#/components/schemas/IOC' relatedIOCs: type: array items: $ref: '#/components/schemas/IOC' meta: type: object properties: total_matches: type: integer related_count: type: integer search_time_ms: type: integer 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 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`' ````