---
title: "Minds API"
description: "사용자 지정 구성 및 페르소나를 사용하여 프로그래밍 방식으로 AI 마인드를 생성하고 관리합니다."
---

# Minds API

프로그래밍 방식으로 AI 마인드(에이전트)를 생성하고 관리합니다. Minds는 특정 전문성, 페르소나, 지식을 갖춘 맞춤형 AI 어시스턴트입니다.

**기본 URL:** `https://getminds.ai/api/v1` 또는 `https://api.getminds.ai/v1`

## Mind 가져오기

시스템 프롬프트, 공유 설정, 지식 항목 수를 포함한 단일 마인드의 전체 세부 정보를 검색합니다.

**엔드포인트:** `GET /api/v1/minds/{mindId}`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 응답

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Life Story & Background\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}
```

### 응답 필드

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      유형
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      고유한 마인드 식별자
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      마인드 이름
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      마인드 설명
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       또는 <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      전문 분야
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      마인드의 행동을 정의하는 전체 시스템 프롬프트
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      분류용 태그
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      마인드의 공개 여부
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      링크 공유 활성화 여부
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicShareId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      공개 액세스를 위한 공유 ID (공유되지 않은 경우 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아바타 이미지 URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phoneNumber
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      연결된 전화번호 (없는 경우 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clonedVoiceStatus
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      음성 복제 상태 (복제되지 않은 경우 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profitSplitOptIn
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      수익 분배 활성화 여부
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledgeItemCount
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      연결된 지식 항목 수
    </td>
  </tr>
</tbody>
</table>

### 요청 예시

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### 오류 응답

**400 Bad Request** - 잘못된 mind ID 형식

**401 Unauthorized** - 유효하지 않거나 누락된 API 키

**403 Forbidden** - 이 마인드에 대한 액세스 권한 없음

**404 Not Found** - 마인드가 존재하지 않음

---

## Minds 목록 조회

인증된 사용자에 속한 모든 마인드를 검색합니다.

**엔드포인트:** `GET /api/v1/minds`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 쿼리 매개변수

<table>
<thead>
  <tr>
    <th>
      매개변수
    </th>
    
    <th>
      유형
    </th>
    
    <th>
      기본값
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      -
    </td>
    
    <td>
      이름, 설명 또는 전문 분야로 마인드 필터링 (대소문자 구분 안 함)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      100
    </td>
    
    <td>
      반환할 최대 마인드 수 (1–100)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      0
    </td>
    
    <td>
      페이지네이션을 위해 건너뛸 마인드 수
    </td>
  </tr>
</tbody>
</table>

### 응답

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}
```

### 응답 필드

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      유형
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      마인드 객체 배열
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      쿼리와 일치하는 총 마인드 수
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      페이지당 최대 결과 수
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      건너뛴 결과 수
    </td>
  </tr>
</tbody>
</table>

### 요청 예시

```bash
curl -X GET "https://getminds.ai/api/v1/minds?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"
```

## Mind 생성

다양한 훈련 모드를 사용하여 사용자 지정 구성으로 새로운 AI 마인드를 생성합니다.

**엔드포인트:** `POST /api/v1/minds`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### 요청 본문

```json
{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}
```

### 매개변수

<table>
<thead>
  <tr>
    <th>
      매개변수
    </th>
    
    <th>
      유형
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      마인드 이름 (2-100자)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        예
      </strong>
    </td>
    
    <td>
      마인드의 전문 분야 (예: "마케팅", "엔지니어링")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      훈련 모드: <code>
        keywords
      </code>
      
      , <code>
        clone
      </code>
      
      , <code>
        link
      </code>
      
       또는 <code>
        manual
      </code>
      
      . 기본값: <code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드 유형: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       또는 <code>
        user
      </code>
      
      . 기본값: <code>
        creative
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드의 목적에 대한 설명
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      조건부
    </td>
    
    <td>
      키워드 배열 (<code>
        mode
      </code>
      
      가 <code>
        keywords
      </code>
      
      인 경우 필수)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        personaContext
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      조건부
    </td>
    
    <td>
      모방할 사람의 이름/문맥 (<code>
        mode
      </code>
      
      가 <code>
        clone
      </code>
      
      인 경우 필수, 키워드 자동 추출에도 사용됨)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextLink
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      조건부
    </td>
    
    <td>
      프로필/콘텐츠 URL (<code>
        mode
      </code>
      
      가 <code>
        link
      </code>
      
      인 경우 필수, 서버가 스크래핑하여 키워드 추출)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      분류용 태그 배열 (최대 20개)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      아바타 이미지의 외부 URL (다운로드 후 저장됨)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      <code>
        true
      </code>
      
      인 경우, 백그라운드에서 AI 프로필 이미지 생성을 트리거합니다
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cloneVoice
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      <code>
        true
      </code>
      
      인 경우, YouTube 검색을 통해 음성 복제를 트리거합니다 (실험적 기능)
    </td>
  </tr>
</tbody>
</table>

### 모드 값

`mode` 매개변수는 마인드가 어떻게 훈련될지를 결정합니다:

- **keywords** (기본값) - 쉼표로 구분된 키워드를 사용하여 마인드를 훈련합니다. AI는 이 키워드를 기반으로 다양한 소스에서 관련 정보를 수집하여 마인드의 지식 기반을 구축합니다.
  - **필수 필드:** `keywords` - 키워드/주제 배열
  - **최적 활용:** 특정 주제나 도메인에 대한 일반적인 전문성
- **clone** - 이름과 문맥을 제공하여 특정 인물의 스타일과 지식을 복제합니다. AI는 해당 인물의 전문성과 소통 스타일을 모방하는 포괄적인 프로필을 연구하고 구축합니다.
  - **필수 필드:** `personaContext` - 이름과 간략한 문맥 (예: "에이다 러브레이스, 선구적인 컴퓨터 과학자")
  - **최적 활용:** 특정 개인, 역사적 인물 또는 유명 전문가 모방
- **link** - 특정 URL의 콘텐츠를 사용하여 마인드를 훈련합니다. 프로필, 포트폴리오 또는 웹사이트 링크를 제공하면 AI가 관련 정보를 분석하고 추출합니다.
  - **필수 필드:** `contextLink` - 콘텐츠 소스 URL
  - **최적 활용:** 특정 웹사이트, 포트폴리오 또는 온라인 프로필 기반 훈련
- **manual** - 자동 훈련 없이 마인드를 생성합니다. 모든 설정을 수동으로 구성하고 나중에 지식 API를 통해 지식을 추가하게 됩니다.
  - **추가 필드 필요 없음**
  - **최적 활용:** 훈련 데이터에 대한 완전한 제어를 원하는 사용자 지정 구성

> **자동 처리:** `keywords`, `clone` 또는 `link`를 사용하면 백엔드는 제품 내 'Mind 추가' 양식과 동일하게 작동합니다. 즉, 엔티티 키워드를 추출하고(`clone`/`link`의 경우 AI 지원) 마인드를 비동기적으로 훈련합니다. 이 훈련 과정은 생성 응답의 `training` 블록과 아래 **마인드 훈련 수명 주기**에 설명된 전용 엔드포인트를 통해 추적할 수 있습니다. `manual` 모드는 이 자동화 과정을 건너뛰므로 나중에 지식 API를 통해 마인드를 훈련할 수 있습니다.

### 유형 값

- **creative** - 아티스트, 디자이너, 작가 및 크리에이티브 전문가용
- **expert** - 전문가, 컨설턴트 및 특정 분야 전문가용
- **user** - 사용자 페르소나, 고객 및 타겟 고객 유형용

### 응답

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}
```

`training` 블록은 생성 시점의 마인드 수명 주기를 보고합니다. `keywords`, `clone`, `link` 모드는 `queued` 상태로 시작하여 백그라운드에서 훈련됩니다. `manual` 마인드는 `readyToChat`가 이미 `true`인 상태로 `completed`로 반환됩니다. 이 호출이 반환되는 즉시 마인드의 `id`는 존재하지만, 마인드는 `readyToChat`가 `true`가 되어야만 답변할 수 있습니다. 폴링 방법은 아래 **마인드 훈련 수명 주기**를 참조하세요.

### 예시: 키워드 모드로 마인드 생성

```bash
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": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'
```

### 예시: 복제 모드로 마인드 생성

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'
```

### 예시: 링크 모드로 마인드 생성

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'
```

### 예시: 수동 모드로 마인드 생성

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'
```

## 마인드 훈련 수명 주기

마인드 생성은 비동기적으로 처리됩니다. `POST /v1/minds`는 즉시 `id`와 함께 반환되지만, `keywords`, `clone`, `link` 모드의 경우 마인드는 백그라운드에서 계속 훈련됩니다. **마인드의 id가 존재한다고 해서 마인드가 준비된 것은 아닙니다.** 마인드는 `readyToChat`가 `true`가 되어야만 답변할 수 있습니다. 유일한 예외는 `manual` 모드입니다. 이 모드의 마인드는 데이터 수집을 건너뛰고 생성되는 즉시 `completed` 상태가 됩니다.

마인드가 준비될 때까지 전용 훈련 엔드포인트를 폴링하세요:

```bash
curl "https://getminds.ai/api/v1/minds/{mindId}/training" \
  -H "Authorization: Bearer minds_your_api_key"
```

```json
{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}
```

### 상태 값

<table>
<thead>
  <tr>
    <th>
      상태
    </th>
    
    <th>
      의미
    </th>
    
    <th>
      <code>
        readyToChat
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queued
      </code>
    </td>
    
    <td>
      훈련이 대기열에 추가되었지만 아직 시작되지 않았습니다.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        running
      </code>
    </td>
    
    <td>
      마인드가 활발하게 지식을 수집하고 페르소나를 구축하고 있습니다.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        completed
      </code>
    </td>
    
    <td>
      훈련이 완료되었습니다. 마인드가 채팅할 준비가 되었습니다.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        failed
      </code>
    </td>
    
    <td>
      훈련이 완료되지 않았습니다. <code>
        error
      </code>
      
      를 확인하고 재시도 가능한 경우 다시 훈련하세요.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

`GET /v1/minds/{id}`는 나머지 마인드 정보와 함께 `readyToChat` (및 `trainingStatus`)도 반환하므로, 한 번의 읽기 요청으로 마인드의 정체성과 답변 가능 여부를 모두 알 수 있습니다.

### 훈련 실패 시

`status`가 `failed`일 때, 응답에는 `code`와 `retryable` 플래그가 포함된 `error` 객체가 포함됩니다:

<table>
<thead>
  <tr>
    <th>
      오류 코드
    </th>
    
    <th>
      의미
    </th>
    
    <th>
      <code>
        retryable
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COLLECTION_FAILED
      </code>
    </td>
    
    <td>
      지식 수집을 완료할 수 없습니다.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROFILE_GEN_FAILED
      </code>
    </td>
    
    <td>
      페르소나 프로필을 생성할 수 없습니다.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
    </td>
    
    <td>
      훈련 시간이 초과되어 중지되었습니다.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INTERNAL
      </code>
    </td>
    
    <td>
      예상치 못한 내부 오류가 발생했습니다.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

### 재훈련

마인드가 `failed` 상태로 종료되었거나 단순히 `completed` 상태의 마인드를 재구축하고 싶다면 다시 훈련하세요:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"
```

이 요청은 마인드를 다시 대기열에 추가하고 `status`가 `queued`로 설정된 새로운 `training` 블록을 반환합니다. 재훈련은 완료된 마인드에만 작동합니다. 아직 `queued` 또는 `running` 상태인 마인드는 이미 훈련이 진행 중이므로 `409 Conflict`를 반환합니다. 재훈련 후, `readyToChat`가 `true`가 될 때까지 다시 `GET /v1/minds/{id}/training`를 폴링하세요.

## 프로필 이미지

`profileImageUrl`를 제공하면:

1. 외부 URL에서 이미지를 다운로드합니다.
2. 보안 스토리지에 업로드합니다.
3. 저장된 URL이 응답으로 반환됩니다.

지원 형식: JPG, PNG, GIF, WEBP

## 훈련 방식

시스템은 선택한 모드, 유형, 전문 분야에 따라 지능적인 시스템 프롬프트를 자동으로 생성합니다:

- **키워드 모드**: 지정한 키워드를 중심으로 전문성을 구축합니다.
- **복제 모드**: 지정한 인물의 스타일과 지식을 모방하는 프로필을 구축합니다.
- **링크 모드**: 제공된 URL에서 지식을 추출합니다.
- **수동 모드**: 사용자 지정 지식으로 훈련할 기본 어시스턴트를 생성합니다.

생성 후 [지식을 업로드](/api/knowledge)하여 마인드를 더욱 향상시킬 수 있습니다.

## 플랜 한도

현재 공개 기본값은 생성된 [플랜 제한 표](/api/overview)를 참조하세요. 계약별 재정의는 다를 수 있으므로 통합은 인증된 `PLAN_LIMIT` 응답의 `data.limit`와 `data.current`를 사용해야 합니다. Individual 플랜은 API payload에서 `"premium"`으로 표시됩니다.

한도에 도달하면 `403 Forbidden` 오류가 발생합니다:

```json
{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "minds",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}
```

## 오류 응답

### 400 Bad Request

매개변수가 누락되었거나 유효하지 않습니다.

```json
{
  "statusCode": 400,
  "statusMessage": "Name is required"
}
```

### 401 Unauthorized

API 키가 유효하지 않거나 누락되었습니다.

### 403 Forbidden

플랜 한도에 도달했습니다.

### 500 Internal Server Error

서버 측 오류 (드문 경우).

## Mind 업데이트

이름, 설명, 시스템 프롬프트 및 기타 설정을 포함하여 기존 마인드의 구성을 업데이트합니다.

**엔드포인트:** `PUT /api/v1/minds/{mindId}`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### 요청 본문

```json
{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}
```

### 매개변수

<table>
<thead>
  <tr>
    <th>
      매개변수
    </th>
    
    <th>
      유형
    </th>
    
    <th>
      필수
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드 이름 (2-100자)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드의 목적에 대한 설명
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      유형: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
       또는 <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드의 전문 분야
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드의 행동과 페르소나를 정의하는 사용자 지정 시스템 프롬프트
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      분류용 태그 배열 (최대 20개)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      아니요
    </td>
    
    <td>
      마인드의 공개 여부
    </td>
  </tr>
</tbody>
</table>

### 시스템 프롬프트

`systemPrompt` 필드를 사용하면 마인드가 행동하고 응답하는 방식을 사용자 지정할 수 있습니다. 다음과 같은 경우에 유용합니다:

- **페르소나 맞춤 설정**: 특정 성격 특성, 소통 스타일 또는 전문 분야 정의
- **응답 형식 지정**: 마인드가 특정 형식(예: 글머리 기호, 번호 매기기 목록)으로 응답하도록 지시
- **도메인 제약**: 특정 주제나 관점으로 응답 제한
- **언어/어조**: 응답의 언어, 격식 수준 또는 어조 설정

**시스템 프롬프트 예시:**

```text
# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.
```

```text
# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.
```

### 응답

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}
```

### 예시: 시스템 프롬프트 업데이트

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'
```

### 예시: 여러 필드 업데이트

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'
```

### 오류 응답

**400 Bad Request** - 업데이트할 유효한 필드가 없거나 필드 값이 유효하지 않음

**401 Unauthorized** - 유효하지 않거나 누락된 API 키

**403 Forbidden** - 이 마인드를 업데이트할 권한 없음 (소유자여야 함)

**404 Not Found** - 마인드가 존재하지 않음

## Mind 패턴 가져오기 (원시 데이터)

마인드의 원시 `Pattern[]` 행을 검색합니다. 이는 제품 UI의 SphereGraph 시각화에서 사용하는 처리되지 않은 피드입니다. 프레임워크 그룹화나 집계 없이 감지된 각 패턴(메서드/역량 쌍 및 이를 뒷받침하는 `mind` 인용문, 소스 연결)에 대해 하나의 행을 반환합니다.

구조화되고 프레임워크별로 그룹화된 뷰를 원한다면, 대신 아래의 `Get Mind Knowledge Patterns` 엔드포인트를 사용하세요.

**엔드포인트:** `GET /api/v1/minds/{mindId}/patterns`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 응답

```json
{
  "data": [
    {
      "id": 12345,
      "mindId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "...",
      "messageId": null,
      "portfolioItemId": "abc-123",
      "aspect": "Strategic Thinking",
      "subAspect": "Market Analysis",
      "mind": "Market segmentation requires understanding customer pain points...",
      "isPredefined": true,
      "isPredefinedAspect": true,
      "isPredefinedSubAspect": true,
      "createdAt": "2025-12-10T15:30:00.000Z"
    }
  ]
}
```

결과는 `createdAt` 내림차순으로 정렬됩니다. 레거시 필드 이름 `aspect`/`subAspect`는 기본 스키마의 `method`/`competency` 열에 해당하며 이전 버전과의 호환성을 위해 유지됩니다.

### 액세스 규칙

- 공개 마인드(`isPublic: true`) 및 링크 공유 마인드(`publicShareId` 설정됨)는 인증 없이 읽을 수 있습니다.
- 비공개 마인드는 마인드 소유자, 팀 멤버 또는 직접 멤버인 소유자의 API 키가 필요합니다.

### 요청 예시

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/patterns" \
  -H "Authorization: Bearer minds_your_api_key"
```

### 오류 응답

**400 Bad Request** - 잘못된 mind ID 형식

**401 Unauthorized** - 마인드가 비공개이며 유효한 API 키가 제공되지 않음

**403 Forbidden** - 이 비공개 마인드에 대한 액세스 권한 없음

**404 Not Found** - 마인드가 존재하지 않음

---

## Mind 지식 패턴 가져오기

특정 마인드에 대해 프레임워크별로 정리된 사고 패턴과 지식을 검색합니다.

**엔드포인트:** `GET /api/v1/minds/{mindId}/knowledge/patterns`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 응답 구조

이 엔드포인트는 프레임워크(예: AOX Internal, OCEAN, DISC 등)별로 그룹화된 패턴을 반환하며, 메서드와 역량은 발생 횟수와 근거를 보여줍니다.

```json
{
  "success": true,
  "data": {
    "mindId": "550e8400-e29b-41d4-a716-446655440000",
    "mindName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "mind": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "mind": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### 응답 이해하기

- **frameworks**: 스파크의 패턴을 포함하는 프레임워크 배열

  - **totalOccurrences**: 이 프레임워크의 총 패턴 수
  - **methods**: 감지된 사고 메서드 또는 접근 방식
  
    - **occurrences**: 이 메서드가 나타나는 횟수
    - **competencies**: 메서드 내의 특정 기술 또는 하위 영역
    
      - **occurrences**: 이 역량에 대한 패턴 수
      - **evidence**: 이 패턴을 보여주는 인용/인용문 배열
      
        - **mind**: 콘텐츠에서 가져온 실제 인용문 또는 인사이트
        - **portfolioItemId**: 원본 자료에 대한 참조
        - **createdAt**: 이 패턴이 식별된 시점

### 요청 예시

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"
```

### 사용 사례

- **마인드 전문성 이해**: 마인드가 학습한 메서드와 역량 확인
- **품질 보증**: 훈련 데이터에서 패턴이 올바르게 추출되는지 확인
- **지식 격차 식별**: 더 많은 훈련 데이터가 필요한 영역 파악
- **프레임워크 비교**: 여러 프레임워크에서 마인드가 어떻게 수행되는지 비교

### 오류 응답

**401 Unauthorized** - 유효하지 않거나 누락된 API 키

**403 Forbidden** - 이 마인드에 대한 액세스 권한 없음

**404 Not Found** - 마인드가 존재하지 않음

## 시스템 프롬프트 다시 생성

기존 지식 기반을 사용하여 스파크의 모든 시스템 프롬프트 구성 요소를 다시 생성합니다. 이는 UI의 '모두 생성' 버튼과 동일한 AI 기반 생성 기능을 사용합니다.

**엔드포인트:** `POST /api/v1/minds/{mindId}/regenerate-prompt`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 작동 방식

이 엔드포인트는 마인드의 지식 기반(포트폴리오 항목, 패턴, 임베딩)을 분석하고 **모든** 스파크 유형(`user`, `expert`, `creative`)에 대한 통합된 전기적 프롬프트 구성 요소 세트를 생성합니다:

- **생애사와 배경** , 전기적 기반, 현재 나이, 위치, 민족, 성장기 경험
- **소통과 언어** , 독특한 목소리, 어구, 방언, 감정적 유발 요인
- **지식과 경험** , 무엇을 알고 있으며 어떻게 알게 되었는가
- **가치와 모순** , 신념, 이상, 그리고 그 사이의 긴장
- **일상 현실과 문맥** , 경제적, 시간적, 사회적, 물리적 문맥

`type` 필드는 이전 버전과의 호환성을 위해 스파크에 보존되지만, 더 이상 어떤 구성 요소가 생성될지에 영향을 주지 않습니다. 마인드는 마인드일 뿐입니다. 통합된 전기적 접근 방식은 유형에 관계없이 더 강력하고 근거 있는 페르소나를 생성합니다.

### 응답

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Mind",
    "systemPrompt": "## Life Story & Background\n\n...",
    "promptLength": 2847
  }
}
```

### 요청 예시

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"
```

### 사용 사례

- **지식 추가 후**: 새로 추가된 지식 항목을 통합하기 위해 프롬프트 다시 생성
- **페르소나 개선**: 현재 지식 패턴을 기반으로 페르소나를 업데이트하기 위해 다시 생성
- **사용자 지정 재설정**: 수동 편집 내용을 지우고 지식 기반에서 새로운 프롬프트를 다시 생성

### 오류 응답

**401 Unauthorized** - 유효하지 않거나 누락된 API 키

**403 Forbidden** - 이 마인드를 수정할 권한 없음 (소유자여야 함)

**404 Not Found** - 마인드가 존재하지 않음

**500 Internal Server Error** - 프롬프트 생성 실패 (예: 불충분한 지식)

## Mind 삭제

마인드와 관련된 모든 데이터(지식, 포트폴리오 항목, 파일 포함)를 영구적으로 삭제합니다.

**엔드포인트:** `DELETE /api/v1/minds/{mindId}`

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

### 응답

성공 시 빈 본문과 함께 `204 No Content`를 반환합니다.

### 요청 예시

```bash
curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### 삭제되는 항목

마인드를 삭제하면 다음 항목이 영구적으로 제거됩니다:

- 마인드 자체와 모든 구성
- 모든 지식 및 훈련 데이터
- 모든 포트폴리오 항목 및 관련 파일
- 모든 채팅 기록 및 메시지
- 프로필 이미지 및 업로드된 파일

**경고:** 이 작업은 되돌릴 수 없습니다.

### 오류 응답

**400 Bad Request** - 잘못된 mind ID 형식

**401 Unauthorized** - 유효하지 않거나 누락된 API 키

**403 Forbidden** - 이 마인드를 삭제할 권한 없음 (소유자여야 함)

**404 Not Found** - 마인드가 존재하지 않음

## 다음 단계

- [마인드에 지식 업로드](/api/knowledge)
- [마인드와 채팅하기](/api/chat)
- [오류 및 한도](/api/errors)에 대해 알아보기