Minds
Minds Team

OpenAPI Spec & TypeScript Clients

Machine-readable OpenAPI 3.1.0 spec for the Minds API. Generate typed TypeScript clients, explore endpoints interactively in Scalar, 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, explore endpoints in an interactive reference, or hand the JSON to an LLM — same source of truth as this documentation.

Endpoints

URLWhat you get
https://getminds.ai/_openapi.jsonOpenAPI 3.1.0 JSON spec. Feed this into any generator.
https://getminds.ai/_scalarScalar reference UI — interactive, try-it-out, copy-paste curl.
https://getminds.ai/_swaggerClassic Swagger UI.

The spec only includes endpoints under /api/v1/**. Internal endpoints (admin, debug, cron, MCP, etc.) are filtered out.

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 every /api/v1/** endpoint. Routes ship with full request/response schemas when they carry a defineRouteMeta block; routes without one appear with path + method only and a generic description. We're working through the surface over time — the spec stays accurate either way 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