OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

OpenAPI-Spezifikation & TypeScript-Clients

Maschinenlesbare OpenAPI-3.1.0-Spezifikation für die Minds-API. Generiere typisierte TypeScript-Clients oder gib das JSON direkt an dein LLM weiter.

Die öffentliche Minds-API liefert eine maschinenlesbare OpenAPI-3.1.0-Spezifikation. Baue typisierte Clients oder gib das JSON an ein LLM weiter — dieselbe Quelle der Wahrheit wie diese Dokumentation.

Endpoint

URLWas du bekommst
https://getminds.ai/_openapi.jsonOpenAPI-3.1.0-JSON-Spezifikation. Gib sie in jeden Generator.
https://getminds.ai/api/v1/openapi.jsonDieselbe Spezifikation, direkt neben den Endpunkten, die sie beschreibt. Kein API-Key nötig.

Die Spezifikation enthält nur öffentliche /api/v1/**-Endpunkte mit OpenAPI-Metadaten. Interne Endpunkte (Admin, Debug, Cron, MCP usw.) sind ausgeschlossen.

Authentifizierung

Jede Operation in der Spezifikation ist durch ApiKeyAuth geschützt — sende deinen persönlichen API-Schlüssel als Bearer-Token:

Authorization: Bearer minds_…_key

Erstelle einen unter Einstellungen → API-Schlüssel. Siehe Authentifizierung für den vollständigen Ablauf.

Einen TypeScript-Client generieren

Der schnellste Weg: Nutze openapi-typescript, um strikte Typen aus der Live-Spezifikation zu generieren.

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

Verwende sie dann mit openapi-fetch für einen vollständig typisierten 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 } },
})

Lieber ein Runtime-SDK? Jeder OpenAPI-3.1-kompatible Generator funktioniert — openapi-generator, orval, kubb usw.

Mit einem LLM nutzen

Die JSON-Spezifikation ist klein genug, um sie in einen Chat zu kopieren:

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

Dann füge sie in ChatGPT / Claude / Cursor mit einem Prompt wie diesem ein:

Hier ist die OpenAPI-Spezifikation der Minds-API. Schreibe mir ein Python-Skript, das meine Sparks auflistet und ihre Namen ausgibt.

Die Spezifikation enthält Request-/Response-Schemas, Beispiel-Payloads und den Bearer-Token-Auth-Vertrag — das Modell hat alles, was es braucht.

Abdeckung

Die Spezifikation listet jeden /api/v1/**-Endpunkt. Routen werden mit vollständigen Request-/Response-Schemas ausgeliefert, wenn sie einen defineRouteMeta-Block tragen; Routen ohne einen solchen erscheinen nur mit Pfad + Methode und einer generischen Beschreibung. Wir arbeiten die Oberfläche nach und nach durch — die Spezifikation bleibt ohnehin korrekt, da sie aus dem Live-Router generiert und nicht von Hand gepflegt wird.

Hinweis zur Stabilität: Die OpenAPI-Generierung läuft über Nitros experimentelles openAPI-Flag. Das Spezifikationsformat ist stabil (OpenAPI 3.1.0); geringfügige strukturelle Abweichungen in den Operations-Metadaten sind möglich, während die zugrunde liegende Nitro-Funktion reift. Pinne deinen Client-Generierungsschritt an ein Build-Artefakt, wenn du einen eingefrorenen Vertrag brauchst.

Nächste Schritte