/api-integrations

name: api-integrations
description: Expose external APIs to Falcon Foundry via OpenAPI specs. TRIGGER when user asks to "create an API integration", "adapt an OpenAPI spec for Foundry", "expose an API to workflows", "connect to a third-party API", or runs `foundry api-integrations create`. Also trigger when user has an OpenAPI/Swagger spec and wants it working in Falcon Foundry. DO NOT TRIGGER when user wants to call Falcon platform APIs from function code — use functions-falcon-api instead.
version: 1.7.1
updated: 2026-11-10
tags: [foundry, openapi, api, workflows]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: integration

Foundry API Integrations

> Build API integrations from the vendor's published OpenAPI spec, adapted for Foundry, with its authentication scheme configured. > > For `api-integrations create`, always include `--description` (50 characters max) — the CLI still prompts for it even with `--no-prompt` if omitted.

> **Part of a suite.** If `development-workflow` has not already run, and this is a new app or its first capability, load the `development-workflow` skill first — it owns the CLI prerequisite check, scaffolding order, and manifest coordination.

This skill covers exposing external APIs (third-party services or CrowdStrike Falcon APIs) to the Falcon Foundry platform via OpenAPI/Swagger specifications. These integrations make API operations available to Falcon Fusion SOAR workflows, Foundry UI extensions, Foundry Functions, and other Foundry capabilities.

**API integrations are how Foundry manages credentials.** There is no secrets system, no encrypted env vars, and no key vault. When you register an API integration, the platform collects credentials at install time and manages tokens automatically. Change them later under **App catalog > the app > ⋮ > Modify settings**; `development-workflow` covers integrations added after install. This is why functions MUST call third-party REST APIs through `APIIntegrations().execute_command_proxy()` — not via raw HTTP with env vars.

For calling Falcon APIs from within Function code, see **functions-falcon-api** instead.

Decision Tree

What kind of API integration?

External API (Okta, VirusTotal, ServiceNow, etc.)
├── Vendor publishes OpenAPI spec → Download it, adapt for Foundry
└── No vendor spec available      → Write minimal spec as last resort

CrowdStrike Falcon API
├── From functions → use functions-falcon-api instead
├── From workflows → use CrowdStrike auto-auth (no spec needed)
└── API family FalconPy does not wrap
    → API integration with oauth2 clientCredentials against /oauth2/token.
      The Falcon swagger at assets.falcon.*.crowdstrike.com returns AccessDenied
      without console auth, so a minimal spec written from the product docs
      is acceptable here — the one case where hand-writing is not a last resort.

Workflow: Download, Adapt, Register

**Always follow this order.** Hosts that load this plugin's hooks enforce adaptation (see the hook safety net below). Antigravity CLI and a skill-symlink install MUST run the script explicitly.

1. Download the vendor's spec

**NEVER write an OpenAPI spec from scratch when the vendor publishes one.** Hand-written specs produce incorrect response schemas, miss required parameters, and lack proper security definitions. Download the vendor's spec even if it has hundreds of endpoints — Foundry handles large specs fine. Do NOT rationalize writing a "focused" or "minimal" spec because the vendor spec is big.

1. **Ask the user** if they have a local copy or know where to download it 2. **Browse the repo first, don't guess URLs.** List its YAML and JSON files in one call (`HEAD` is the default branch), then download the spec with `curl`.

   gh api "repos/{owner}/{repo}/git/trees/HEAD?recursive=1" \
     --jq '.tree[] | select(.type=="blob" and (.path|test("\\.(ya?ml|json)$"))) | .path'

Narrow a long list with `grep`, not `head` (versioned copies sort first); prefer a `current` or `latest` path. Never guess URLs. 3. **Search locally** for existing specs 4. If the vendor does not publish a spec, only then write a minimal one

**Do NOT delegate spec download to Explore agents or subagents.** They lack skill context and fall back to Fetch or a browser. Download inline with `gh` and `curl`.

For detailed download commands and structural fix patterns, see [references/spec-adaptation-examples.md](references/spec-adaptation-examples.md).

2. Adapt the spec for Foundry (MANDATORY)

# <skill-dir> is this SKILL.md's directory. --dry-run previews the fixes without
# saving them, though it still converts a Swagger 2.0 input to .openapi3.*.
python3 <skill-dir>/scripts/adapt_spec_for_foundry.py /tmp/VendorApi.yaml

> **Dependencies:** The script requires `pyyaml`, and installing the plugin does not install Python packages. A bare `pip install` fails on Homebrew and system Pythons with `externally-managed-environment` (PEP 668), so set up a venv once in the checkout and run the script from it: > > ```bash > SKILLS_REPO=/path/to/foundry-skills > python3 -m venv "$SKILLS_REPO/.venv" > "$SKILLS_REPO/.venv/bin/pip" install -r "$SKILLS_REPO/requirements.txt" > "$SKILLS_REPO/.venv/bin/python" "$SKILLS_REPO/skills/api-integrations/scripts/adapt_spec_for_foundry.py" /tmp/VendorApi.yaml > ```

The helper is bundled with this skill at `scripts/adapt_spec_for_foundry.py`. Resolve that path relative to this `SKILL.md`, not the app workspace.

The script applies fixes derived from 12 Foundry sample apps:

• **Swagger 2.0 conversion**: Converts to OpenAPI 3.0 via `swagger2openapi` (npx) and writes the result next to the input as `<name>.openapi3.json` or `<name>.openapi3.yaml`. Register that file, not the original.
• **Auth fixing**: Deletes an `oauth2` scheme (and its security references) when it has `authorizationCode` and no `clientCredentials` flow; a scheme with both is kept unchanged