OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

Especificación OpenAPI y clientes TypeScript

Especificación OpenAPI 3.1.0 legible por máquina para la API de Minds. Genera clientes TypeScript tipados o pasa el JSON directamente a tu LLM.

La API pública de Minds incluye una especificación OpenAPI 3.1.0 legible por máquina. Crea clientes tipados o entrega el JSON a un LLM — la misma fuente de verdad que esta documentación.

Endpoint

URLLo que obtienes
https://getminds.ai/_openapi.jsonEspecificación JSON OpenAPI 3.1.0. Pásala a cualquier generador.
https://getminds.ai/api/v1/openapi.jsonLa misma especificación, servida junto a los endpoints que describe. No requiere clave de API.

La especificación solo incluye endpoints públicos /api/v1/** que declaran metadatos OpenAPI. Los endpoints internos (admin, debug, cron, MCP, etc.) quedan excluidos.

Autenticación

Cada operación de la especificación está protegida por ApiKeyAuth — envía tu clave de API personal como bearer token:

Authorization: Bearer minds_…_key

Crea una en Ajustes → Claves de API. Consulta Autenticación para el flujo completo.

Generar un cliente TypeScript

La vía más rápida: usa openapi-typescript para generar tipos estrictos a partir de la especificación en vivo.

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

Luego úsalos con openapi-fetch para un cliente totalmente tipado:

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 } },
})

¿Prefieres un SDK en runtime? Funciona cualquier generador compatible con OpenAPI 3.1 — openapi-generator, orval, kubb, etc.

Úsala con un LLM

La especificación JSON es lo bastante pequeña para pegarla en un chat:

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

Luego pégala en ChatGPT / Claude / Cursor con un prompt como:

Aquí está la especificación OpenAPI de la API de Minds. Escríbeme un script de Python que liste mis sparks e imprima sus nombres.

La especificación incluye esquemas de petición/respuesta, payloads de ejemplo y el contrato de autenticación por bearer token — el modelo tiene todo lo que necesita.

Cobertura

La especificación lista cada endpoint /api/v1/**. Las rutas se entregan con esquemas completos de petición/respuesta cuando llevan un bloque defineRouteMeta; las rutas sin él aparecen solo con ruta + método y una descripción genérica. Vamos cubriendo la superficie con el tiempo — la especificación se mantiene precisa en cualquier caso, porque se genera a partir del router en vivo y no se mantiene a mano.

Nota sobre la estabilidad: la generación de OpenAPI se ejecuta con el flag experimental openAPI de Nitro. El formato de la especificación es estable (OpenAPI 3.1.0); es posible una ligera deriva estructural en los metadatos de las operaciones a medida que madura la funcionalidad subyacente de Nitro. Fija tu paso de generación de cliente a un artefacto de build si necesitas un contrato congelado.

Próximos pasos