OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

OpenAPI Spec & TypeScript Clients

Machine-readable OpenAPI 3.1.0 spec for the Minds API. Generate typed TypeScript clients or pipe the JSON straight into your LLM.

The Minds public API ships a machine-readable OpenAPI 3.1.0 spec. Build typed clients or give the JSON to an LLM for routes with detailed operation metadata. Use the complete endpoint catalog alongside it while schema coverage is expanded.

Endpoint

URLWhat you get
https://getminds.ai/_openapi.jsonOpenAPI 3.1.0 JSON spec. Feed this into any generator.
https://getminds.ai/_openapi-3.0.jsonGenerated OpenAPI 3.0.2 compatibility view for importers such as RapidAPI.
https://getminds.ai/api/v1/openapi.jsonThe same spec, served next to the endpoints it describes. No API key needed.

Both documents come from the same route metadata. The 3.1 document is canonical. The generated 3.0.2 view only exists for importers that do not support 3.1. Both include only public /api/v1/** endpoints that declare OpenAPI metadata. Internal endpoints (admin, debug, cron, MCP, etc.) are excluded.

Authentication

Every operation in the spec is gated by ApiKeyAuth — send your personal API key as a bearer token:

Authorization: Bearer minds_…_key

Create one in Settings → API Keys. See Authentication for the full flow.

Generate a TypeScript client

The fastest path: use openapi-typescript to generate strict types from the live spec.

npx openapi-typescript https://getminds.ai/_openapi.json -o minds.d.ts

Then use them with openapi-fetch for a fully-typed client:

import createClient from 'openapi-fetch'
import type { paths } from './minds'

const client = createClient<paths>({
  baseUrl: 'https://api.getminds.ai',
  headers: { Authorization: `Bearer ${process.env.MINDS_API_KEY}` },
})

// All params + responses are typed from the live spec.
const { data, error } = await client.GET('/api/v1/sparks', {
  params: { query: { limit: 10 } },
})

Prefer a runtime SDK? Any OpenAPI 3.1-compatible generator works — openapi-generator, orval, kubb, etc.

Use it with an LLM

The JSON spec is small enough to drop into a chat:

curl -s https://getminds.ai/_openapi.json | pbcopy

Then paste it into ChatGPT, Claude, Cursor, or another coding agent with a prompt like:

Here is the Minds API OpenAPI spec. Also consult https://getminds.ai/api/reference and https://getminds.ai/api/agents. Write a Python script that lists my Minds and prints their IDs and names. Read the API key from MINDS_API_KEY; never print it.

The spec includes the bearer-token contract and operation metadata for covered routes. The endpoint catalog supplies complete route discovery, while the domain pages provide richer workflow examples and limitations.

Coverage

The spec lists only /api/v1/** endpoints that opt in via defineRouteMeta({ openAPI: … }). It deliberately excludes internal admin, cron, debug, app-only, and MCP routes. Detailed v1 schema coverage is progressive: absence from the spec does not mean a v1 route is unavailable. The endpoint catalog is tested against every concrete v1 route and is the completeness authority.

Note on stability: OpenAPI generation runs on Nitro's experimental openAPI flag. The spec format is stable (OpenAPI 3.1.0); minor structural drift in operation metadata is possible as the underlying Nitro feature matures. Pin your client-generation step to a build artifact if you need a frozen contract.

Next steps