Document query parameter type matching for API integrations

A/B run 4 of 5 generated `limit: '25'` in an extension's `falconApi` call while the other four generated `limit: 25`. All five OpenAPI specs declare `limit` as `type: integer`, so the quoted value failed server-side schema validation with `got string want integer` and that extension never fetched data.

`apiIntegration().execute()` types params as `Record<string, unknown>` (`foundry-js` `src/abstraction/api-integration.ts`), so a quoted number type-checks and builds cleanly — the mismatch only appears at runtime. The extension still renders, which makes it look like an API or credential error rather than a bug in the generated code. Verification scored that app's UI as passing.

Adds the constraint to the API integration section with a correct/incorrect pair, and a Common Pitfalls entry for anyone scanning for gotchas.

Author: mraible

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - **`foundry apps list` in prerequisite check** — New CLI 2.0.2 command that lists all deployed apps on the CID from any directory. Added to Step 3 to help avoid name collisions.
 - **Collection description validation constraints** — Documents the 3–500 character length limit, alphanumeric-start requirement, and allowed character set for collection descriptions.
 - **Function logs in testing-patterns reference** — Added function logs (viewing in UI and Advanced Event Search) to the reference table entry for testing patterns.
+- **Query parameter type matching for API integrations** — Documents that `apiIntegration().execute()` types params as `Record<string, unknown>`, so a quoted number like `limit: '25'` passes type-checking and fails server-side with `got string want integer`. The extension still renders, so the failure reads as an API or credential error rather than a code bug.
 - **Content regression tests** — `tests/test_skill_content.py` guards critical documentation (LogScale recipe, schema requirements, workflow deletion warning) against accidental removal.
 
 ### Changed

app1-okta-user-manager-installed.png

@@ -173,6 +173,16 @@ const body = result.resources?.[0]?.response_body;
 const status = result.resources?.[0]?.status_code;
 ```
 
+Query and path parameters must match the types declared in the OpenAPI spec. `execute()` types params as `Record<string, unknown>`, so a quoted number compiles and ships fine, then fails server-side schema validation at runtime with `got string want integer`. The extension still renders, so this looks like an API or credential error rather than a bug in your code.
+
+```javascript
+// spec declares: - name: limit / schema: { type: integer }
+request: { params: { query: { limit: 25 } } }    // ✅ number
+request: { params: { query: { limit: '25' } } }  // ❌ got string want integer
+```
+
+Check the `schema.type` of each parameter in the spec before passing it. Numbers and booleans are unquoted; only `type: string` parameters take quotes.
+
 ### Collection Operations
 
 ```javascript
@@ -330,6 +340,7 @@ Run `foundry ui extensions list-sockets` to get the current list of available so
 - **Expecting backend to work with `foundry ui run`.** The dev server only serves UI — deploy backend capabilities first.
 - **Shoelace dialogs/drawers white in dark mode.** Override `--sl-panel-background-color` and `--sl-color-neutral-0` with `var(--ground-floor)`. See [references/shoelace-reference.md](references/shoelace-reference.md).
 - **Using Tailwind arbitrary values with prebuilt toucan CSS.** Values like `max-h-[400px]` require JIT compilation. Use inline styles instead when using the prebuilt `tailwind-toucan-base/index.css`.
+- **Quoting numeric query parameters.** `execute()` accepts `Record<string, unknown>`, so `limit: '25'` passes type-checking and fails server-side with `got string want integer`. Match the `schema.type` declared in the OpenAPI spec — the extension still renders, so this reads as an API error rather than a code bug.
 - **Missing CSP for Shoelace icons.** The Foundry CSP only allows `assets.foundry.crowdstrike.com`. If using `setBasePath()` with `cdn.jsdelivr.net`, you must add it to `connect-src` and `img-src` in the manifest's `content_security_policy`. Alternatively, copy icon assets to your `dist/` folder and set a relative base path to avoid CDN dependencies entirely.
 
 ## Reading Guide