# Calling API Integrations from Code Full examples for calling API integrations from UI extensions, Python functions, and Go functions. ## UI Extensions (JavaScript / Foundry-JS) UI extensions call API integrations through `falcon.apiIntegration()`, not direct HTTP calls. Foundry UI extensions run in sandboxed iframes and cannot make arbitrary HTTP requests. ```javascript // React example using Foundry-JS import FalconApi from '@crowdstrike/foundry-js'; const falcon = new FalconApi(); await falcon.connect(); // Call an API integration operation const apiIntegration = falcon.apiIntegration({ definitionId: 'Okta', // Matches the API integration name in manifest.yml operationId: 'listUsers' // Matches the operationId in the OpenAPI spec }); const response = await apiIntegration.execute({ request: { params: {} } // Pass query parameters here }); // Response structure: // response.resources[0].status_code - HTTP status from the external API // response.resources[0].response_body - Parsed response body const resource = response.resources?.[0]; const statusCode = resource?.status_code; const body = resource?.response_body; ``` **Reference:** See `foundry-sample-foundryjs-demo` for a working example of `falcon.apiIntegration().execute()`. ## Python Functions (FalconPy APIIntegrations) ```python # functions/external-enrichment/main.py from logging import Logger from typing import Any, Dict, Union from crowdstrike.foundry.function import Function, Request, Response from falconpy import APIIntegrations func = Function.instance() @func.handler(method='POST', path='/api/enrich') def enrich_with_external_api(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response: """Call an external API via API Integration.""" # Get the data to enrich ip_address = request.body.get("ip_address") if not ip_address: return Response(body={"error": "IP address required"}, code=400) # Use API Integrations SDK to call the configured integration api_integrations = APIIntegrations() # Call the API integration operation # definition_id is the integration name from manifest.yml response = api_integrations.execute( definition_id="VirusTotal", # Integration name operation_id="getIpReport", # Operation ID from OpenAPI spec body={ "request": { "params": { "ip": ip_address } } } ) if response["status_code"] != 200: logger.error(f"API integration failed: {response.get('errors')}") return Response( body={"error": "Failed to call external API"}, code=500 ) # Extract the external API response resources = response.get("body", {}).get("resources", []) if not resources: return Response(body={"error": "No data returned"}, code=404) external_data = resources[0].get("response_body", {}) return Response( body={ "ip_address": ip_address, "enrichment": external_data }, code=200 ) if __name__ == '__main__': func.run() ``` ## Go Functions (gofalcon) ```go // functions/external-enrichment/main.go package main import ( "context" "encoding/json" "log/slog" "github.com/crowdstrike/gofalcon/falcon" "github.com/crowdstrike/gofalcon/falcon/client" "github.com/crowdstrike/gofalcon/falcon/client/custom_storage" fdk "github.com/crowdstrike/foundry-fn-go" ) type enrichRequest struct { IPAddress string `json:"ip_address"` } type enrichResponse struct { IPAddress string `json:"ip_address"` Enrichment map[string]interface{} `json:"enrichment"` } func newHandler(_ context.Context, _ *slog.Logger, _ fdk.SkipCfg) fdk.Handler { m := fdk.NewMux() m.Post("/api/enrich", fdk.HandleFnOf(func(ctx context.Context, r fdk.RequestOf[enrichRequest]) fdk.Response { if r.Body.IPAddress == "" { return fdk.Response{ Code: 400, Body: fdk.JSON(map[string]string{"error": "IP address required"}), } } // Get Falcon client for API Integrations accessToken := r.Header.Get("X-CS-ACCESSTOKEN") opts := fdk.FalconClientOpts() falconClient, err := falcon.NewClient(&falcon.ApiConfig{ AccessToken: accessToken, Cloud: falcon.Cloud(opts.Cloud), Context: ctx, UserAgentOverride: opts.UserAgent, }) if err != nil { return fdk.Response{ Code: 500, Body: fdk.JSON(map[string]string{"error": "Failed to authenticate"}), } } // Call API integration // Note: Use the integration's definition_id from manifest.yml integrationRequest := map[string]interface{}{ "request": map[string]interface{}{ "params": map[string]string{ "ip": r.Body.IPAddress, }, }, } requestBody, _ := json.Marshal(integrationRequest) // Execute API integration operation params := custom_storage.NewExecuteCommandParamsWithContext(ctx) params.SetDefinitionID("VirusTotal") // Integration name from manifest.yml params.SetOperationID("getIpReport") // Operation ID from OpenAPI spec params.SetBody(requestBody) apiResponse, err := falconClient.CustomStorage.ExecuteCommand(params) if err != nil { return fdk.Response{ Code: 500, Body: fdk.JSON(map[string]string{"error": "Failed to call external API"}), } } // Parse the response var result struct { Resources []struct { StatusCode int `json:"status_code"` ResponseBody map[string]interface{} `json:"response_body"` } `json:"resources"` } if err := json.Unmarshal(apiResponse.Payload, &result); err != nil { return fdk.Response{ Code: 500, Body: fdk.JSON(map[string]string{"error": "Failed to parse response"}), } } if len(result.Resources) == 0 { return fdk.Response{ Code: 404, Body: fdk.JSON(map[string]string{"error": "No data returned"}), } } response := enrichResponse{ IPAddress: r.Body.IPAddress, Enrichment: result.Resources[0].ResponseBody, } return fdk.Response{ Code: 200, Body: fdk.JSON(response), } })) return m } func main() { fdk.Run(context.Background(), newHandler) } ``` ## Request Schema Validation Happens Before the Proxy Call The platform validates the `request` object against the OpenAPI spec's parameter schemas before it forwards anything to the vendor. Values must be scalars typed exactly as the spec declares them — an `integer` parameter takes `1`, not `"1"` and not `["1"]`. A mismatch never reaches the vendor; it comes back as: ``` 400 request failed schema validation: /properties/params/properties/query/properties/limit ... ``` This trips up two habits. The foundry-js `Params` type suggests `query?: Record`, and the FDK's own `request.params.query` is `Dict[str, List[str]]` — both list-valued shapes fail for anything other than `type: string` array parameters. Unwrap and convert before forwarding: ```python # Python — forward a query param from the handler's request to an integration limit = int(request.params.query.get("limit", ["25"])[0]) response = api.execute_command_proxy(body={"resources": [{ "definition_id": "VendorApi", "operation_id": "listItems", "request": {"params": {"query": {"limit": limit}}}, # scalar, typed per the spec }]}) ``` ```javascript // foundry-js — same rule await apiIntegration.execute({ request: { params: { query: { limit: 25 } } } }); // number, not '25' or ['25'] ``` Path parameters go under `params.path`, query parameters under `params.query`, and headers under `headers`; a request body goes in `json`. Check each parameter's `schema.type` in the spec before building the request. ## Extracting Fields from API Responses Before writing code that reads fields from an API response, verify the field's location in the OpenAPI spec's response schema. Fields are often nested under objects (e.g., `meta.severity` not `severity`). Similarly, query parameter names may differ from response field names (e.g., filtering by `meta.severity` even though the CSV column is just `severity`). **Checklist:** 1. Find the endpoint's response schema in the OpenAPI spec 2. Trace the field path — is it top-level or nested under an object? 3. For query parameters, check the `parameters` section for the exact name 4. Match your struct/dict access to the actual nesting (e.g., `ioc.get("meta", {}).get("severity", '')`) ## Key Points | Aspect | Detail | |--------|--------| | **Python SDK** | `APIIntegrations()` from FalconPy with `execute()` method | | **Go SDK** | Falcon client with `CustomStorage.ExecuteCommand()` | | **definition_id** | Must match the integration name in `manifest.yml` | | **operation_id** | Must match the `operationId` in the OpenAPI spec | | **Authentication** | Automatic when called from within FDK handlers | | **Response structure** | Returns `resources` array with `status_code` and `response_body` | | **Request validation** | Validated against the spec's parameter schemas before proxying — scalars typed per the spec, not string arrays | | **Local development** | Use the UUID `definition_id` from `manifest.yml`, not the human-readable name (avoids 404 errors) |