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 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.

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, 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 $refs 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 — setup order and smoke test rules
• secret-backed-integration.md — non-OAuth secret recipe
• oauth.md — standard /connect/oauth path
• @kody/integrations-sh — registry search, detect, surface, and discover after a community fork
• @kody/openapi — bind and call selected operations after a community fork
• @kody/api-research — OpenAPI summarize and scaffold