OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

Spécification OpenAPI & clients TypeScript

Spécification OpenAPI 3.1.0 lisible par machine pour l'API Minds. Générez des clients TypeScript typés ou injectez le JSON directement dans votre LLM.

L'API publique Minds fournit une spécification OpenAPI 3.1.0 lisible par machine. Construisez des clients typés ou confiez le JSON à un LLM — la même source de vérité que cette documentation.

Endpoint

URLCe que vous obtenez
https://getminds.ai/_openapi.jsonSpécification JSON OpenAPI 3.1.0. Donnez-la à n'importe quel générateur.
https://getminds.ai/api/v1/openapi.jsonLa même spécification, servie à côté des endpoints qu'elle décrit. Aucune clé API requise.

La spécification n'inclut que les endpoints publics /api/v1/** qui déclarent des métadonnées OpenAPI. Les endpoints internes (admin, debug, cron, MCP, etc.) sont exclus.

Authentification

Chaque opération dans la spécification est protégée par ApiKeyAuth — envoyez votre clé API personnelle en tant que bearer token :

Authorization: Bearer minds_…_key

Créez-en une dans Paramètres → Clés API. Voir Authentification pour le flux complet.

Générer un client TypeScript

Le chemin le plus rapide : utilisez openapi-typescript pour générer des types stricts à partir de la spécification en direct.

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

Utilisez-les ensuite avec openapi-fetch pour un client entièrement typé :

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

Vous préférez un SDK runtime ? N'importe quel générateur compatible OpenAPI 3.1 fonctionne — openapi-generator, orval, kubb, etc.

L'utiliser avec un LLM

La spécification JSON est assez petite pour être déposée dans un chat :

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

Collez-la ensuite dans ChatGPT / Claude / Cursor avec un prompt comme :

Voici la spécification OpenAPI de l'API Minds. Écris-moi un script Python qui liste mes sparks et affiche leurs noms.

La spécification inclut les schémas de requête/réponse, des exemples de payloads et le contrat d'authentification par bearer token — le modèle a tout ce dont il a besoin.

Couverture

La spécification liste chaque endpoint /api/v1/**. Les routes sont livrées avec des schémas de requête/réponse complets lorsqu'elles portent un bloc defineRouteMeta ; les routes sans un tel bloc apparaissent uniquement avec chemin + méthode et une description générique. Nous parcourons la surface au fil du temps — la spécification reste exacte dans tous les cas, car elle est générée à partir du routeur en direct et non maintenue à la main.

Note sur la stabilité : la génération OpenAPI s'appuie sur le flag expérimental openAPI de Nitro. Le format de la spécification est stable (OpenAPI 3.1.0) ; une légère dérive structurelle des métadonnées d'opération est possible à mesure que la fonctionnalité Nitro sous-jacente mûrit. Épinglez votre étape de génération de client à un artefact de build si vous avez besoin d'un contrat figé.

Étapes suivantes