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

OpenAPI Spec

The Minds public API ships a machine-readable OpenAPI 3.1.0 spec. Build typed clients or hand the JSON to an LLM — same source of truth as this documentation.

Endpoint

URLWhat you get
https://getminds.ai/_openapi.jsonOpenAPI 3.1.0 JSON spec. Feed this into any generator.

The spec only includes 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 into ChatGPT / Claude / Cursor with a prompt like:

Here is the Minds API OpenAPI spec. Write me a Python script that lists my sparks and prints their names.

The spec includes request/response schemas, example payloads, and the bearer-token auth contract — the model has everything it needs.

Coverage

The spec lists only /api/v1/** endpoints that opt in via defineRouteMeta({ openAPI: … }). We're working through the surface over time — the spec stays accurate because it's generated from the live router, not maintained by hand.

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