Skip to docs content
Browse documentation
On this page

OpenAPI integrations

Call a third-party API that publishes an OpenAPI document: treat the spec as untrusted, authenticate with an integration or secret, and wrap the operations you need in a thin helpers package.

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

Read Integration bootstrap first for the overall setup order (research, connect, smoke test, build). This guide covers the packages-first path for OpenAPI-backed APIs.

Minion has no built-in OpenAPI client, spec binder or package catalog. The helpers package is yours to write, and it stays small.

Write a thin helpers package

Do not generate a full client from a spec. Wrap the handful of operations the user actually needs.

  1. Check the organization's saved packages first (minion.packages.list()) for one that already wraps the provider.
  2. Read the provider's OpenAPI document as reference to learn the paths, parameters and response shapes. Fetch it with ordinary fetch in execute, or open it in a browser.
  3. Write a package with one export per operation. Authenticate outbound calls with createAuthenticatedFetch from minion:runtime (OAuth integration) or a secret placeholder ({{secret:<name>}}) after the user has finished connect and setup.
  4. Keep the surface narrow, and say in the README which integration or secret and which hosts the package needs.
import { createAuthenticatedFetch } from 'minion:runtime'

const acme = createAuthenticatedFetch('acme')

export default async function listWidgets({ limit = 10 }: { limit?: number }) {
	const res = await acme(`https://api.example.com/widgets?limit=${limit}`)
	if (!res.ok) throw new Error(`Acme returned ${res.status}`)
	return await res.json()
}

Auth and smoke test

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

Finish connect and setup per 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 the provider's official docs. Prefer HTTPS URLs you already trust, set a request timeout, and bound the response size.
  • Suggested hosts never widen approval. A server URL in a spec is not an approved host. Host approval stays with an owner or admin on the Secrets page, and an integration only sends its token to the API hosts of its OAuth app.
  • Credentials as names only. Auth inputs reference integration or secret names and placeholders. Raw credentials never enter package source or chat.

Related