> ## 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. # Fetch STIX 2.1 objects from a TAXII collection > Returns a STIX 2.1 bundle of objects in the requested collection. This is the workhorse pull endpoint for TAXII clients. ## Pagination TAXII pagination uses `added_after` + `limit` + the `X-TAXII-Date-Added-Last` response header. Save the response's `X-TAXII-Date-Added-Last` and pass it as `added_after` on the next request to walk forward without missing objects. ## Filtering - `?type=indicator` — only Indicator SDOs (most common) - `?match[type]=ipv4-addr` — narrow further by indicator subtype - `added_after` is the **canonical** delta-poll mechanism. Don't use any other field. ## Rate cost This endpoint has a 2.5× rate multiplier (it generates a full STIX bundle). Plan polling cadence accordingly. ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/taxii2/api/collections/{collectionId}/objects/ 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/taxii2/api/collections/{collectionId}/objects/: get: tags: - TAXII summary: Fetch STIX 2.1 objects from a TAXII collection description: >- Returns a STIX 2.1 bundle of objects in the requested collection. This is the workhorse pull endpoint for TAXII clients. ## Pagination TAXII pagination uses `added_after` + `limit` + the `X-TAXII-Date-Added-Last` response header. Save the response's `X-TAXII-Date-Added-Last` and pass it as `added_after` on the next request to walk forward without missing objects. ## Filtering - `?type=indicator` — only Indicator SDOs (most common) - `?match[type]=ipv4-addr` — narrow further by indicator subtype - `added_after` is the **canonical** delta-poll mechanism. Don't use any other field. ## Rate cost This endpoint has a 2.5× rate multiplier (it generates a full STIX bundle). Plan polling cadence accordingly. operationId: getTAXIIObjects parameters: - name: collectionId in: path required: true description: >- Collection ID from the list endpoint (e.g. `soc-defenders-all`, `soc-defenders-network`, `soc-defenders-hashes`). schema: type: string example: soc-defenders-network - name: added_after in: query description: >- Return only objects added to the collection after this timestamp. **Canonical delta-poll mechanism** — save the response's `X-TAXII-Date-Added-Last` header value and pass it back here on the next request. schema: type: string format: date-time example: '2026-05-16T00:00:00Z' - name: limit in: query description: >- Max objects per response (max 1000). For deep pulls, walk forward via `added_after` rather than skipping. schema: type: integer default: 100 maximum: 1000 example: 500 - name: type in: query description: >- Filter by STIX object type. `indicator` is the most common — narrows the bundle to just IOC indicators (no identity/marking-definition objects). schema: type: string example: indicator responses: '200': description: >- STIX 2.1 bundle of objects in the collection. Use `X-TAXII-Date-Added-Last` for delta-poll continuation. headers: X-TAXII-Date-Added-First: description: Timestamp of the first object in this response (oldest) schema: type: string format: date-time X-TAXII-Date-Added-Last: description: >- Timestamp of the last object in this response (newest). **Save this** for delta polling. schema: type: string format: date-time content: application/taxii+json;version=2.1: 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: '2026-05-17T10:30:00.000Z' name: SOC Defenders identity_class: organization - type: indicator spec_version: '2.1' id: indicator--00000000-0000-4000-8000-000000000001 created: '2026-05-16T08:21:30Z' modified: '2026-05-16T08:21:30Z' created_by_ref: identity--f8e75d96-8e4c-4b1a-9e3d-4f8a7b6c5d3e object_marking_refs: - marking-definition--bab4a63c-aed9-4cf5-a766-dfca5abac2bb name: Malicious Domain - c2.example.com indicator_types: - malicious-activity pattern: '[domain-name:value = ''c2.example.com'']' pattern_type: stix valid_from: '2026-05-16T08:21:30Z' confidence: 85 labels: - c2 - botnet '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: cURL label: Pull recent indicators source: |- curl -H "Authorization: Bearer sk_live_..." \ -H "Accept: application/taxii+json;version=2.1" \ "https://socdefenders.ai/api/taxii2/api/collections/soc-defenders-network/objects/?added_after=2026-05-16T00:00:00Z&limit=500" - lang: Python label: Delta poll loop source: |- import requests import time KEY = "sk_live_..." COLLECTION = "soc-defenders-all" checkpoint = "2026-05-16T00:00:00Z" while True: r = requests.get( f"https://socdefenders.ai/api/taxii2/api/collections/{COLLECTION}/objects/", headers={"Authorization": f"Bearer {KEY}", "Accept": "application/taxii+json;version=2.1"}, params={"added_after": checkpoint, "limit": 1000}, ) r.raise_for_status() bundle = r.json() for obj in bundle.get("objects", []): ingest_stix(obj) checkpoint = r.headers.get("X-TAXII-Date-Added-Last", checkpoint) if len(bundle.get("objects", [])) < 1000: time.sleep(300) # No more data — back off 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 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: The requested resource was not found 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`' ````