---
title: "API 개요"
description: "minds 및 지식 관리에 프로그래밍 방식으로 액세스하기 위한 Minds API 소개."
---

# API 개요

Minds API 문서에 오신 것을 환영합니다. Minds API를 사용하면 프로그래밍 방식으로 AI minds를 생성 및 관리하고, 지식을 업로드하며, 이들과 상호작용할 수 있습니다.

## 시작하기

Minds API는 REST 원칙을 기반으로 설계되었습니다. 예측 가능한 리소스 지향적 URL을 제공하며, JSON 형식의 요청 본문을 수락하고 JSON 형식의 응답을 반환합니다. 또한 표준 HTTP 응답 코드, 인증 및 메서드를 사용합니다.

### 기본 URL

**프로덕션:** `https://getminds.ai/api/v1` 또는 `https://api.getminds.ai/v1`

**로컬 개발:** `http://localhost:3000/api/v1`

두 프로덕션 기본 URL은 완전히 동일하게 작동합니다. 더 깔끔한 통합 URL을 위해 `api.getminds.ai` 서브도메인을 사용하는 것을 권장합니다.

### 인증

모든 API 엔드포인트는 API 키를 통한 인증이 필요합니다. [Settings → API Keys](/settings/api-keys)에서 API 키를 생성하고 관리할 수 있습니다.

`Authorization` 헤더에 API 키를 포함하세요:

```bash
Authorization: Bearer minds_your_api_key_here
```

### OpenAPI 사양

기계 읽기 가능한 OpenAPI 3.1.0 사양은 [`/_openapi.json`](/_openapi.json)에 게시되어 있습니다. 이 사양을 사용하여 타입이 지정된 클라이언트(TypeScript, Python 등)를 생성하거나, LLM에 입력하여 원샷 통합 코드를 생성할 수 있습니다. 예시는 [OpenAPI](/docs/api/openapi)를 참조하세요.

### 콘텐츠 타입

데이터를 전송하는 모든 요청에는 `Content-Type` 헤더가 포함되어야 합니다:

```bash
Content-Type: application/json
```

파일 업로드의 경우 다음을 사용하세요:

```bash
Content-Type: multipart/form-data
```

## 사용 가능한 엔드포인트

### Minds

맞춤형 설정으로 AI minds(에이전트)를 생성하고 관리합니다.

- `GET /api/v1/minds` - 모든 Mind 목록 조회
- `GET /api/v1/minds/{mindId}` - Mind 상세 정보 조회
- `POST /api/v1/minds` - 새로운 Mind 생성
- `PUT /api/v1/minds/{mindId}` - Mind 수정
- `DELETE /api/v1/minds/{mindId}` - Mind 삭제
- `POST /api/v1/minds/{mindId}/regenerate-prompt` - 지식을 기반으로 시스템 프롬프트 재생성
- `GET /api/v1/minds/{mindId}/patterns` - Mind의 원시 사고 패턴 조회

### Knowledge

minds를 위한 지식을 관리합니다.

- `GET /api/v1/minds/{mindId}/knowledge` - 지식 항목 목록 조회
- `POST /api/v1/minds/{mindId}/knowledge` - 지식 추가 (링크, 파일 또는 키워드 검색)
- `PUT /api/v1/minds/{mindId}/knowledge/{itemId}` - 지식 항목 수정
- `DELETE /api/v1/minds/{mindId}/knowledge/{itemId}` - 지식 항목 삭제
- `POST /api/v1/minds/{mindId}/knowledge/enrich` - 키워드 검색을 통한 보강 (편의용 별칭)
- `GET /api/v1/minds/{mindId}/knowledge/patterns` - 프레임워크별 지식 패턴 조회

### Chat

챗 컴플리션(chat completions)을 통해 minds와 상호작용합니다.

- `POST /api/v1/minds/{mindId}/completion` - 메시지 전송 및 응답 수신

### Studies

여러 minds 그룹을 조사하기 위한 AI studies를 생성하고 관리합니다.

- `GET /api/v1/studies` - 모든 study 목록 조회
- `POST /api/v1/studies` - 새로운 study 생성
- `GET /api/v1/studies/{studyId}` - 메시지 기록을 포함한 study 상세 정보 조회
- `POST /api/v1/studies/{studyId}/ask` - 모든 study minds에 질문하기 (SSE 스트림)
- `POST /api/v1/studies/{studyId}/export` - study 결과를 보고서로 내보내기
- `GET /api/v1/studies/{studyId}/export-status` - 내보내기 작업 상태 확인
- `GET /api/v1/studies/{studyId}/export-download` - 내보낸 PDF 다운로드

### User

사용자 관련 엔드포인트입니다.

- `GET /api/v1/auth/me` - 현재 인증된 사용자 정보 조회
- `GET /api/v1/user/shareable-sparks` - 공유 가능한 minds 목록 조회

### API Keys

인증용 API 키를 관리합니다.

- `GET /api/v1/api-keys` - API 키 목록 조회
- `POST /api/v1/api-keys` - 새로운 API 키 생성
- `DELETE /api/v1/api-keys/{keyId}` - API 키 삭제

## 빠른 예시

다음은 mind를 생성하고 대화를 나누는 간단한 예시입니다:

```bash
# 1. Create a mind (keywords mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Create a mind from social profile (clone mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

# 3. Chat with the mind
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top social media trends for 2025?"
      }
    ]
  }'
```

## 다음 단계

- [인증](/docs/api/authentication)에 대해 알아보기
- [Minds 엔드포인트](/docs/api/minds) 살펴보기
- [지식 관리](/docs/api/knowledge)에 대해 알아보기
- [챗 컴플리션](/docs/api/chat) 이해하기
- 다중 mind 조사를 위한 [Studies](/docs/api/studies) 생성하기
- [지연 시간 및 성능](/docs/api/latency) 검토하기
- [MCP 통합](/mcp/overview)을 통해 연결하기
- [오류 및 제한 사항](/docs/api/errors) 검토하기

## 요금제 제한 사항

API 및 MCP 액세스는 지원되는 유료 플랜에서 제공됩니다. 통합에 제한을 하드코딩하지 말고 구조화된 `plan_limited` 및 `429` 응답을 처리하세요. Individual 플랜은 API payload에서 `"premium"`으로 표시됩니다.

아래 공개 기본값은 제품에서 사용하는 동일한 플랜 제한 및 기능 액세스 계약에서 생성됩니다. 제품에 표시되는 계정별 또는 Enterprise 계약별 재정의가 우선합니다.

:plan-limits-table[요금제 보기](/settings?tab=subscription)

## 도움이 필요하신가요?

API와 관련하여 질문이 있거나 지원이 필요한 경우:

- [가이드](/guide) 확인하기
- 피드백 양식을 통해 문의하기
- 커뮤니티 토론 참여하기