OpenAPI 스펙 및 TypeScript 클라이언트

Minds 공개 API는 기계 판독 가능한 OpenAPI 3.1.0 스펙을 제공합니다. 타입이 정의된 클라이언트를 빌드하거나 JSON을 LLM에 직접 전달하세요. 이 문서와 동일한 단일 진실 공급원(Single Source of Truth)을 공유합니다.

엔드포인트

이 스펙에는 OpenAPI 메타데이터를 선언하는 공개 /api/v1/** 엔드포인트만 포함됩니다. 내부 엔드포인트(admin, debug, cron, MCP 등)는 제외됩니다.

인증

스펙의 모든 작업은 ApiKeyAuth으로 보호됩니다. 개인 API 키를 Bearer 토큰으로 전송하세요:

Authorization: Bearer minds_…_key

설정 → API 키에서 키를 생성할 수 있습니다. 전체 흐름은 인증 문서를 참고하세요.

TypeScript 클라이언트 생성하기

가장 빠른 방법: openapi-typescript를 사용하여 라이브 스펙에서 엄격한 타입을 생성합니다.

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

그런 다음 openapi-fetch과 함께 사용하여 완전한 타입이 정의된 클라이언트를 구현하세요:

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

런타임 SDK를 선호하시나요? openapi-generator, orval, kubb 등 OpenAPI 3.1과 호환되는 모든 제너레이터를 사용할 수 있습니다.

LLM과 함께 사용하기

JSON 스펙은 크기가 작아 채팅창에 바로 붙여넣을 수 있습니다:

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

그런 다음 ChatGPT, Claude, Cursor 등에 다음과 같은 프롬프트와 함께 붙여넣으세요:

여기 Minds API OpenAPI 스펙이 있어. 내 sparks 목록을 가져와 이름을 출력하는 Python 스크립트를 작성해 줘.

이 스펙에는 요청/응답 스키마, 페이로드 예시, Bearer 토큰 인증 규약이 포함되어 있어, 모델이 필요한 모든 정보를 갖추고 있습니다.

지원 범위

이 스펙에는 defineRouteMeta({ openAPI: … })을 통해 명시적으로 옵트인한 /api/v1/** 엔드포인트만 나열됩니다. 점진적으로 지원 범위를 넓혀가고 있으며, 수동으로 관리하는 대신 라이브 라우터에서 직접 생성하므로 항상 정확한 스펙을 유지합니다.

안정성 관련 참고 사항: OpenAPI 생성은 Nitro의 실험적 기능인 openAPI 플래그를 기반으로 작동합니다. 스펙 포맷 자체는 안정적이지만(OpenAPI 3.1.0), 기반이 되는 Nitro 기능이 성숙해짐에 따라 작업 메타데이터의 미세한 구조적 변화가 발생할 수 있습니다. 고정된 규약이 필요한 경우, 클라이언트 생성 단계를 특정 빌드 아티팩트에 고정(pin)하여 사용하세요.

다음 단계

• /_openapi.json에서 라이브 스펙 가져오기
• Bearer 토큰 인증 흐름은 인증 문서 참고하기
• 엔드포인트별 상세 가이드는 Sparks, Panels 또는 Chat 문서 확인하기