> ## 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.

# Export IOCs as a STIX 2.1 bundle

> Generates a STIX 2.1 bundle of Indicator SDOs (Structured Data Objects) for direct download. Use this when you want a one-shot bundle; for streaming/polling integrations use the [TAXII 2.1 endpoints](#tag/TAXII) instead.

## Bundle structure

```
bundle
├── identity (SOC Defenders, optional)
├── marking-definition (TLP, optional)
└── indicator × N
```

Each `indicator` SDO carries:
- A STIX 2.1 pattern (e.g. `[ipv4-addr:value = '1.2.3.4']`)
- TLP marking (mapped from our confidence: high→green, medium→amber, low→clear, or override with `tlp=`)
- Tags as STIX `labels`
- MITRE references via `kill_chain_phases`

## TLP markings

By default, indicators are tagged with TLP based on their confidence. Override with `tlp=`:

- `clear`: share freely (low confidence)
- `green`: share within community (high confidence indicators by default)
- `amber`: limited distribution
- `amber+strict`: amber + need-to-know
- `red`: do not share

## Splunk ES / Sentinel ingestion

Both platforms accept STIX bundles via their threat-intel connectors. Download with `format=bundle` (default) and upload via their UI/API.

Requires the **Pro plan** (`read:stix` scope).



## OpenAPI

````yaml https://socdefenders.ai/api/openapi.json get /api/v1/iocs/stix
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/stix:
    get:
      tags:
        - Export Formats
      summary: Export IOCs as a STIX 2.1 bundle
      description: >-
        Generates a STIX 2.1 bundle of Indicator SDOs (Structured Data Objects)
        for direct download. Use this when you want a one-shot bundle; for
        streaming/polling integrations use the [TAXII 2.1 endpoints](#tag/TAXII)
        instead.


        ## Bundle structure


        ```

        bundle

        ├── identity (SOC Defenders, optional)

        ├── marking-definition (TLP, optional)

        └── indicator × N

        ```


        Each `indicator` SDO carries:

        - A STIX 2.1 pattern (e.g. `[ipv4-addr:value = '1.2.3.4']`)

        - TLP marking (mapped from our confidence: high→green, medium→amber,
        low→clear, or override with `tlp=`)

        - Tags as STIX `labels`

        - MITRE references via `kill_chain_phases`


        ## TLP markings


        By default, indicators are tagged with TLP based on their confidence.
        Override with `tlp=`:


        - `clear`: share freely (low confidence)

        - `green`: share within community (high confidence indicators by
        default)

        - `amber`: limited distribution

        - `amber+strict`: amber + need-to-know

        - `red`: do not share


        ## Splunk ES / Sentinel ingestion


        Both platforms accept STIX bundles via their threat-intel connectors.
        Download with `format=bundle` (default) and upload via their UI/API.


        Requires the **Pro plan** (`read:stix` scope).
      operationId: exportSTIX
      parameters:
        - name: type
          in: query
          description: >-
            Filter by IOC type. Generates patterns specific to each:
            `ipv4-addr:value`, `domain-name:value`, `url:value`, `file:hashes`,
            etc.
          schema:
            type: string
            enum:
              - ipv4
              - ipv6
              - domain
              - url
              - md5
              - sha1
              - sha256
              - sha512
              - email
              - cve
              - mitre_attack
            example: ipv4
        - name: since
          in: query
          description: Lower time bound (ISO 8601). Clamped to tier lookback.
          schema:
            type: string
            format: date-time
            example: '2026-05-15T00:00:00Z'
        - name: limit
          in: query
          description: >-
            Maximum number of indicator SDOs in the bundle. Capped at 1000 per
            request.
          schema:
            type: integer
            default: 100
            maximum: 1000
            example: 500
        - name: format
          in: query
          description: >-
            `bundle` wraps objects in a STIX Bundle (recommended — most tools
            expect this). `objects` returns just the array, no wrapper.
          schema:
            type: string
            enum:
              - bundle
              - objects
            default: bundle
            example: bundle
        - name: include_identity
          in: query
          description: >-
            Include a SOC Defenders Identity SDO that all indicators reference
            via `created_by_ref`. Most STIX consumers expect this; keep enabled
            unless your importer rejects unknown SDOs.
          schema:
            type: boolean
            default: true
            example: true
        - name: include_tlp_markings
          in: query
          description: >-
            Include explicit TLP Marking Definition SDOs. Some tools require
            these to recognize TLP tagging on indicators; others auto-resolve
            them. Toggle on if your importer drops indicators whose
            `object_marking_refs` is unresolved.
          schema:
            type: boolean
            default: false
            example: true
        - name: tlp
          in: query
          description: >-
            Force a TLP level on every indicator (overrides the confidence-based
            default).
          schema:
            type: string
            enum:
              - clear
              - green
              - amber
              - amber+strict
              - red
            example: amber
      responses:
        '200':
          description: STIX 2.1 bundle with TLP markings
          content:
            application/stix+json:
              schema:
                $ref: '#/components/schemas/STIXBundle'
              example:
                type: bundle
                id: bundle--12345678-1234-1234-1234-123456789abc
                objects:
                  - type: identity
                    spec_version: '2.1'
                    id: identity--f8e75d96-8e4c-4b1a-9e3d-4f8a7b6c5d3e
                    created: '2024-01-01T00:00:00.000Z'
                    modified: '2024-12-09T10:30:00.000Z'
                    name: SOC Defenders
                    identity_class: organization
                  - type: indicator
                    spec_version: '2.1'
                    id: indicator--87654321-4321-4321-4321-abc123456789
                    created: '2024-12-08T14:30:00Z'
                    modified: '2024-12-09T08:15:00Z'
                    created_by_ref: identity--f8e75d96-8e4c-4b1a-9e3d-4f8a7b6c5d3e
                    object_marking_refs:
                      - marking-definition--bab4a63c-aed9-4cf5-a766-dfca5abac2bb
                    name: Malicious IPv4 Address - 192.168.1.1
                    indicator_types:
                      - malicious-activity
                    pattern: '[ipv4-addr:value = ''192.168.1.1'']'
                    pattern_type: stix
                    valid_from: '2024-12-08T14:30:00Z'
                    confidence: 85
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      x-codeSamples:
        - lang: cURL
          label: Download STIX bundle
          source: |-
            curl -H "Authorization: Bearer sk_live_..." \
              -H "Accept: application/stix+json;version=2.1" \
              "https://socdefenders.ai/api/v1/iocs/stix?type=ipv4&since=2026-05-15T00:00:00Z&limit=500" \
              -o socdefenders.stix.json
        - lang: cURL
          label: Objects only (no envelope)
          source: |-
            curl -H "Authorization: Bearer sk_live_..." \
              "https://socdefenders.ai/api/v1/iocs/stix?format=objects&type=domain&limit=200"
        - lang: Python
          label: Parse with stix2 SDK
          source: |-
            import requests
            from stix2 import parse

            r = requests.get(
                "https://socdefenders.ai/api/v1/iocs/stix",
                headers={"Authorization": "Bearer sk_live_..."},
                params={"type": "sha256", "limit": 100},
            )
            bundle = parse(r.text, allow_custom=True)
            for obj in bundle.objects:
                if obj.type == "indicator":
                    print(obj.pattern, obj.confidence)
components:
  schemas:
    STIXBundle:
      type: object
      properties:
        type:
          type: string
          enum:
            - bundle
        id:
          type: string
          pattern: ^bundle--[0-9a-f-]+$
        objects:
          type: array
          items:
            type: object
    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:
    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
  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`'

````