---
title: "OpenAPI 스펙 및 TypeScript 클라이언트"
description: "Minds API를 위한 기계 판독 가능한 OpenAPI 3.1.0 스펙입니다. 타입이 정의된 TypeScript 클라이언트를 생성하거나 JSON을 LLM에 직접 전달하세요."
---

# OpenAPI 스펙

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

## 엔드포인트

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      제공 내용
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      OpenAPI 3.1.0 JSON 스펙입니다. 원하는 제너레이터에 입력하여 사용하세요.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      RapidAPI 같은 가져오기 도구를 위해 생성된 OpenAPI 3.0.2 호환 보기입니다.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      동일한 스펙을 해당 스펙이 설명하는 엔드포인트 옆에서 제공합니다. API 키가 필요 없습니다.
    </td>
  </tr>
</tbody>
</table>

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

## 인증

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

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

[설정 → API 키](/settings/api-keys)에서 키를 생성할 수 있습니다. 전체 흐름은 [인증](/docs/api/authentication) 문서를 참고하세요.

## TypeScript 클라이언트 생성하기

가장 빠른 방법: [`openapi-typescript`](https://openapi-ts.dev/)를 사용하여 라이브 스펙에서 엄격한 타입을 생성합니다.

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

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

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

런타임 SDK를 선호하시나요? [`openapi-generator`](https://openapi-generator.tech/), [`orval`](https://orval.dev/), [`kubb`](https://www.kubb.dev/) 등 OpenAPI 3.1과 호환되는 모든 제너레이터를 사용할 수 있습니다.

## LLM과 함께 사용하기

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

```bash
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](/_openapi.json)에서 라이브 스펙 가져오기
- Bearer 토큰 인증 흐름은 [인증](/docs/api/authentication) 문서 참고하기
- 엔드포인트별 상세 가이드는 [Minds](/docs/api/minds), [Studies](/docs/api/studies) 또는 [Chat](/docs/api/chat) 문서 확인하기