---
title: "Especificación OpenAPI y clientes TypeScript"
description: "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."
---

# OpenAPI Spec

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

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      Lo que obtienes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      Especificación JSON OpenAPI 3.1.0. Pásala a cualquier generador.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      Vista de compatibilidad OpenAPI 3.0.2 generada para importadores como RapidAPI.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      La misma especificación, servida junto a los endpoints que describe. No requiere clave de API.
    </td>
  </tr>
</tbody>
</table>

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:

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

Crea una en [Ajustes → Claves de API](/settings/api-keys). Consulta [Autenticación](/docs/api/authentication) para el flujo completo.

## Generar un cliente TypeScript

La vía más rápida: usa [`openapi-typescript`](https://openapi-ts.dev/) para generar tipos estrictos a partir de la especificación en vivo.

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

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

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

¿Prefieres un SDK en runtime? Funciona cualquier generador compatible con OpenAPI 3.1 — [`openapi-generator`](https://openapi-generator.tech/), [`orval`](https://orval.dev/), [`kubb`](https://www.kubb.dev/), etc.

## Úsala con un LLM

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

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

- Obtén la especificación en vivo en [/_openapi.json](/_openapi.json)
- Lee [Autenticación](/docs/api/authentication) para el flujo por bearer token
- Adéntrate en [Minds](/docs/api/minds), [Studies](/docs/api/studies) o [Chat](/docs/api/chat) para recorridos de endpoints