OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

OpenAPI Spesifikasyonu & TypeScript İstemcileri

Minds API için makine tarafından okunabilir OpenAPI 3.1.0 spesifikasyonu. Tip güvenli TypeScript istemcileri oluştur veya JSON'u doğrudan LLM'ine aktar.

Minds genel API'si makine tarafından okunabilir bir OpenAPI 3.1.0 spesifikasyonu sunar. Tip güvenli istemciler oluştur veya JSON'u bir LLM'e ver — bu dokümantasyonla aynı doğruluk kaynağı.

Endpoint

URLNe elde edersin
https://getminds.ai/_openapi.jsonOpenAPI 3.1.0 JSON spesifikasyonu. Herhangi bir üretece besle.
https://getminds.ai/api/v1/openapi.jsonAynı spesifikasyon, tanımladığı endpoint'lerin yanında sunulur. API anahtarı gerekmez.

Spesifikasyon yalnızca OpenAPI meta verisi bildiren genel /api/v1/** endpoint'lerini içerir. Dahili endpoint'ler (admin, debug, cron, MCP vb.) hariç tutulur.

Kimlik Doğrulama

Spesifikasyondaki her işlem ApiKeyAuth ile korunur — kişisel API anahtarını bearer token olarak gönder:

Authorization: Bearer minds_…_key

Birini Ayarlar → API Anahtarları bölümünde oluştur. Tam akış için Kimlik Doğrulama sayfasına bak.

TypeScript istemcisi oluştur

En hızlı yol: canlı spesifikasyondan katı tipler üretmek için openapi-typescript kullan.

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

Ardından tamamen tipli bir istemci için bunları openapi-fetch ile kullan:

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

Çalışma zamanı SDK'sı mı tercih edersin? OpenAPI 3.1 uyumlu herhangi bir üreteç çalışır — openapi-generator, orval, kubb vb.

Bir LLM ile kullan

JSON spesifikasyonu bir sohbete bırakılacak kadar küçüktür:

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

Ardından ChatGPT / Claude / Cursor içine şuna benzer bir komutla yapıştır:

İşte Minds API OpenAPI spesifikasyonu. Bana sparklarımı listeleyen ve adlarını yazdıran bir Python betiği yaz.

Spesifikasyon istek/yanıt şemalarını, örnek payload'ları ve bearer token kimlik doğrulama sözleşmesini içerir — modelin ihtiyacı olan her şey var.

Kapsam

Spesifikasyon her /api/v1/** endpoint'ini listeler. Bir defineRouteMeta bloğu taşıyan rotalar tam istek/yanıt şemalarıyla gelir; böyle bir bloğu olmayan rotalar yalnızca yol + yöntem ve genel bir açıklamayla görünür. Yüzeyi zamanla işliyoruz — spesifikasyon her halükârda doğru kalır, çünkü elle değil canlı yönlendiriciden üretilir.

Kararlılık notu: OpenAPI üretimi Nitro'nun deneysel openAPI bayrağıyla çalışır. Spesifikasyon biçimi kararlıdır (OpenAPI 3.1.0); altta yatan Nitro özelliği olgunlaştıkça işlem meta verilerinde küçük yapısal sapmalar olabilir. Donmuş bir sözleşmeye ihtiyacın varsa istemci üretim adımını bir build artefaktına sabitle.

Sonraki adımlar