Configuration for API call enrichment stage. Stage Category: ENRICH (1-1 Enrichment) allowed_domains allowlist. 2. Data Exfiltration: Malicious configurations could send internal data to external endpoints. Audit all configurations before deployment. 3. Credential Safety: NEVER store credentials directly in configuration. Always use auth.secret_ref to reference vault-stored credentials. 4. Rate Limiting: Set rate limits to prevent abuse and excessive costs. 5. Domain Allowlist: REQUIRED. Explicitly list allowed domains. Never use "". Transformation: N documents → N documents (same count, expanded schema) Purpose: Enriches documents by calling external HTTP APIs. Enables integration with third-party services (Stripe, GitHub, weather APIs, etc.) to augment documents with real-time data. Due to security risks, this stage implements strict controls including domain allowlisting, SSRF protection, rate limiting, and secure credential management. When to Use: - Enrich documents with data from external APIs - Integrate third-party services (Stripe, GitHub, Salesforce) - Fetch real-time data (weather, stocks, currency rates) - Validate data against external systems - Lookup additional context from APIs When NOT to Use: - For untrusted/user-provided URLs (major security risk) - When API credentials can't be securely stored - For high-volume enrichment (rate limits apply) - When response time is critical (network latency) - For internal-only APIs behind firewalls Requirements: - url: REQUIRED, API endpoint URL (supports templates) - allowed_domains: REQUIRED, domain allowlist (NEVER use "") - method: OPTIONAL, HTTP method (default: GET) - auth: OPTIONAL, authentication configuration - headers: OPTIONAL, additional headers - body: OPTIONAL, request body (for POST/PUT) - output_field: REQUIRED, where to store response - timeout: OPTIONAL, request timeout (default: 10s) - max_response_size: OPTIONAL, max response size (default: 10MB) - when: OPTIONAL, conditional enrichment filter - on_error: OPTIONAL, error handling (skip/remove/raise) Use Cases: - Stripe customer lookup: Enrich with billing data - GitHub repo info: Fetch commit stats - Weather API: Add location-based weather - Currency conversion: Real-time exchange rates - Address validation: Verify and standardize addresses
| Name | Type | Description | Notes |
|---|---|---|---|
| url | str | API endpoint URL to call. Supports template variables: {INPUT.field}, {DOC.field}. Must be HTTP/HTTPS. Domain must be in allowed_domains list. Default uses httpbin.org for testing. Examples: 'https://api.stripe.com/v1/customers/{DOC.metadata.customer_id}' | [optional] [default to 'https://httpbin.org/get'] |
| allowed_domains | List[str] | Allowlist of domains that can be called. CRITICAL FOR SECURITY - prevents SSRF attacks. Supports wildcards: '.example.com' matches subdomains. NEVER use '' (all domains) in production. Default allows httpbin.org for testing. Examples: ['api.stripe.com', '*.github.com', 'api.weatherapi.com'] | [optional] [default to ["httpbin.org"]] |
| method | str | HTTP method: GET, POST, PUT, PATCH, DELETE. Default: GET. | [optional] [default to 'GET'] |
| auth | StageDefsAuthConfig | OPTIONAL. Authentication configuration. Uses organization vault for credential storage. See AuthConfig for details. | [optional] |
| headers | Dict[str, str] | OPTIONAL. Additional HTTP headers to include. Do NOT include authentication headers here - use 'auth' field. Supports template variables in values. Example: {'Content-Type': 'application/json', 'X-Custom': '{{INPUT.value}}'} | [optional] |
| body | Dict[str, object] | OPTIONAL. Request body (for POST/PUT/PATCH). Serialized as JSON. Supports template variables in values. Only used for non-GET requests. | [optional] |
| output_field | str | Dot-path where API response should be stored. Creates nested structure if needed. Response stored as-is (JSON object/array/primitive). Example: 'metadata.api_data' | [optional] [default to 'metadata.api_response'] |
| timeout | int | Request timeout in seconds. Range: 1-60. Default: 10. | [optional] [default to 10] |
| max_response_size | int | Maximum response size in bytes. Prevents memory exhaustion. Default: 10MB. | [optional] [default to 10485760] |
| rate_limit | StageDefsRateLimitConfig | OPTIONAL. Rate limiting configuration per domain. | [optional] |
| response_path | str | OPTIONAL. JSONPath expression to extract specific field from response. If not specified, stores entire response. Examples: '$.data', '$.results[0]', '$.customer.email' | [optional] [default to 'null'] |
| when | StageDefsLogicalOperator | OPTIONAL. Conditional filter for selective enrichment. Only documents matching condition will call API. RECOMMENDED for cost/performance optimization. | [optional] |
| on_error | StageDefsErrorHandling | Error handling strategy: 'skip': Pass document through unchanged. 'remove': Remove failed documents. 'raise': Halt pipeline on error. Default: 'skip'. | [optional] |
from mixpeek.models.stage_params_api_call import StageParamsApiCall
# TODO update the JSON string below
json = "{}"
# create an instance of StageParamsApiCall from a JSON string
stage_params_api_call_instance = StageParamsApiCall.from_json(json)
# print the JSON string representation of the object
print(StageParamsApiCall.to_json())
# convert the object into a dict
stage_params_api_call_dict = stage_params_api_call_instance.to_dict()
# create an instance of StageParamsApiCall from a dict
stage_params_api_call_from_dict = StageParamsApiCall.from_dict(stage_params_api_call_dict)