# OpenAPI integrations

Use this guide when a third-party API publishes an OpenAPI document and you need
authenticated calls from Kody.

Read [integration-bootstrap.md](/docs/integration-bootstrap) first for the
overall setup order (research → connect → smoke test → build). This guide covers
the packages-first path for OpenAPI-backed APIs.

## Prefer a helpers package

Do not hand-roll a full client from a spec when a maintained wrapper already
exists.

1. `communitySearch` for a close helpers package that already wraps the
   provider.
2. If one fits, inspect it with `communityGet` and review the source.
3. `communityFork` it into the user's account, adapt it, then publish.
4. Authenticate outbound calls with `createAuthenticatedFetch` (OAuth
   integration) or secret placeholders (`{{secret:<name>}}`) after the user has
   finished connect/setup.

## When nothing close exists

If community search finds no close package, prefer `@kody/openapi` for standard
bind-and-call. Person accounts cannot import `@kody/*` live — `communityFork`
the listing first, then import the copy.

Write a thin helpers package with `createAuthenticatedFetch` (or secret-backed
headers) and a small hand-written client only when `@kody/openapi` cannot
provide the behavior — for example a non-OpenAPI contract, or request shaping
the binder does not support. Keep that surface narrow: the operations the user
actually needs.

`@kody/integrations-sh` is the integrations.sh registry client (search, detect,
cached surface, live discover). `@kody/api-research` summarizes and scaffolds
OpenAPI 3.x specs. `@kody/openapi` binds and calls selected operations.

```ts
import bind from 'kody:@<username>/openapi/bind'
import call from 'kody:@<username>/openapi/call'

await bind({
	name: 'acme',
	specUrl: 'https://api.example.com/openapi.json',
	apiBaseUrl: 'https://api.example.com',
	auth: { kind: 'integration', provider: 'acme' },
	selection: { pathPrefixes: ['/widgets'] },
})

const listed = await call({
	name: 'acme',
	operation: 'list_widgets',
	query: { limit: 10 },
})
```

Bindings live in that fork's `packageStorage()`. They do not appear as
synthesized search capabilities. `@kody/openapi` parses JSON specs in the Worker
isolate; convert YAML to JSON first. Specs are untrusted third-party content:
verify URLs and auth against the provider's official docs, and never treat
suggested hosts as approval.

## Auth and smoke test

Choose the auth path from the provider's official docs:

- OAuth authorization-code → `integrationSave` + `/connect/oauth` +
  `createAuthenticatedFetch`
- Bearer / API key → a secret placeholder and approved hosts

Finish connect/setup per [integration-bootstrap.md](/docs/integration-bootstrap),
then smoke-test a cheap GET before building a dependent package.

## Security posture

- **Untrusted specs.** Titles, descriptions, servers, and operation text are
  third-party content. Verify URLs and auth against official provider docs.
  `@kody/api-research` fetches specs with ordinary `fetch` — there is no
  platform OpenAPI spec gateway. Prefer HTTPS URLs you already trust, set a
  request timeout, bound the response size, and do not follow remote `$ref`s
  unless you have reviewed that host too.
- **Suggestions-only hosts.** Suggested hosts never widen approval. Host
  approval stays in the account security UI and integration `requiredHosts`.
- **Credentials as names only.** Auth inputs reference integration or secret
  names / placeholders. Raw credentials never enter package source or chat.

## Related

- [integration-bootstrap.md](/docs/integration-bootstrap) — setup order and smoke
  test rules
- [secret-backed-integration.md](/docs/secret-backed-integration) — non-OAuth
  secret recipe
- [oauth.md](/docs/oauth) — standard `/connect/oauth` path
- [@kody/integrations-sh](https://kody.codes/@kody/integrations-sh) — registry
  search, detect, surface, and discover after a community fork
- [@kody/openapi](https://kody.codes/@kody/openapi) — bind and call selected
  operations after a community fork
- [@kody/api-research](https://kody.codes/@kody/api-research) — OpenAPI
  summarize and scaffold