---
title: "Spécification OpenAPI & clients TypeScript"
description: "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."
---

# OpenAPI Spec

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

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      Ce que vous obtenez
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      Spécification JSON OpenAPI 3.1.0. Donnez-la à n'importe quel générateur.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      Vue de compatibilité OpenAPI 3.0.2 générée pour les importateurs comme RapidAPI.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      La même spécification, servie à côté des endpoints qu'elle décrit. Aucune clé API requise.
    </td>
  </tr>
</tbody>
</table>

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 :

```http
Authorization: Bearer minds_…_key
```

Créez-en une dans [Paramètres → Clés API](/settings/api-keys). Voir [Authentification](/docs/api/authentication) pour le flux complet.

## Générer un client TypeScript

Le chemin le plus rapide : utilisez [`openapi-typescript`](https://openapi-ts.dev/) pour générer des types stricts à partir de la spécification en direct.

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

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

```ts
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/minds', {
  params: { query: { limit: 10 } },
})
```

Vous préférez un SDK runtime ? N'importe quel générateur compatible OpenAPI 3.1 fonctionne — [`openapi-generator`](https://openapi-generator.tech/), [`orval`](https://orval.dev/), [`kubb`](https://www.kubb.dev/), etc.

## L'utiliser avec un LLM

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

```bash
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

- Récupérez la spécification en direct sur [/_openapi.json](/_openapi.json)
- Lisez [Authentification](/docs/api/authentication) pour le flux par bearer token
- Plongez dans [Minds](/docs/api/minds), [Studies](/docs/api/studies) ou [Chat](/docs/api/chat) pour des parcours d'endpoints