---
title: "Knowledge API"
description: "파일, 키워드 또는 링크를 통해 마인드에 지식을 추가하세요."
---

# Knowledge API

이 API는 Minds 안에서 마인드 지식을 관리합니다.

**파일**, **키워드** 또는 **링크**의 세 가지 방법을 통해 마인드에 지식을 추가할 수 있습니다. 추가된 지식은 프로세싱 및 임베딩 과정을 거쳐 대화 중에 자동으로 검색 및 활용됩니다.

**참고:** v1 API를 통해 지식 목록 조회, 추가, 삭제가 가능합니다. 키워드 검색을 통한 지식 보강(enrichment) 역시 동일한 추가 엔드포인트를 통해 지원됩니다.

---

## 지식 항목 목록 조회

마인드에 등록된 모든 지식 항목을 조회합니다.

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

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

**예시:**

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

**응답:**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data.items
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      지식 항목 객체 배열
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      이 마인드의 총 지식 항목 수
    </td>
  </tr>
</tbody>
</table>

---

## 파일 업로드

마인드에 문서나 이미지를 직접 업로드합니다.

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

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

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수 여부
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        file
      </code>
    </td>
    
    <td>
      file
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      업로드할 파일 (최대 50MB)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      콘텐츠에 대한 설명
    </td>
  </tr>
</tbody>
</table>

**지원되는 포맷:**

- 문서: PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML
- 이미지: JPG, JPEG, PNG, GIF, WEBP

**예시:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"
```

**응답:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

---

## 키워드 검색

웹에서 키워드를 검색하여 지식을 추가합니다. Exa와 YouTube를 검색하고 콘텐츠를 추출하여 마인드의 지식 베이스에 추가합니다.

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

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

웹 검색 보강을 트리거하려면 (`link`/`file` 대신) `keywords` 배열이 포함된 JSON 본문을 전송합니다.

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수 여부
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      검색할 키워드 (최대 35개)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        regeneratePrompt
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      선택
    </td>
    
    <td>
      완료 후 시스템 프롬프트 재생성 여부 (기본값: true)
    </td>
  </tr>
</tbody>
</table>

**예시:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

**응답:** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}
```

**참고:** 이 작업은 비동기식으로 진행됩니다. 백그라운드에서 프로세싱이 실행되며 완료까지 수 분이 소요될 수 있습니다.

---

## 링크

URL에서 지식을 추가합니다. 웹 페이지, YouTube 동영상, 연구 논문을 지원합니다.

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

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

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수 여부
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      웹 콘텐츠 URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      콘텐츠에 대한 설명
    </td>
  </tr>
</tbody>
</table>

**예시:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'
```

**응답:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

**지원되는 링크 유형:**

- 웹 페이지 (스크래핑을 통해 콘텐츠 추출)
- YouTube 동영상 (자막/스크립트 자동 추출)
- 연구 논문 (arXiv 등)

---

## Watch (자동 업데이트)

링크 기반 지식 항목은 "Watch" 기능을 설정하여 주 단위로 콘텐츠 업데이트를 자동으로 확인할 수 있습니다. 변경 사항이 감지되면 지식이 다시 프로세싱되고 재임베딩됩니다.

Watch 기능은 제품 UI를 통해 관리할 수 있습니다. Watch 상태는 API를 통해 지식 항목 목록을 조회할 때 (`isWatched` 필드) 확인할 수 있습니다.

**참고:** Watch 기능은 링크 기반 지식에만 사용할 수 있으며, 파일이나 키워드 검색에는 지원되지 않습니다.

---

## 지식 항목 수정

기존 지식 항목의 설명을 수정합니다.

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

**헤더:**

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

**요청 본문:**

```json
{
  "description": "Updated description for this knowledge item"
}
```

<table>
<thead>
  <tr>
    <th>
      파라미터
    </th>
    
    <th>
      타입
    </th>
    
    <th>
      필수 여부
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      필수
    </td>
    
    <td>
      수정할 설명 (비어 있을 수 없음)
    </td>
  </tr>
</tbody>
</table>

**예시:**

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'
```

**응답:**

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}
```

### 에러 응답

**400 Bad Request** - 업데이트할 유효한 필드가 없거나 설명이 비어 있음

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

**404 Not Found** - 지식 항목 또는 마인드를 찾을 수 없음

---

## 키워드를 통한 보강 (편의 기능)

키워드 기반 지식 보강을 위한 편의용 앨리어스(Alias)입니다.

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

이는 `keywords` 본문을 사용하는 `POST /api/v1/minds/{mindId}/knowledge`과 동일합니다. 자세한 내용은 [키워드 검색](#keyword-search)을 참고하세요.

**예시:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

---

## 지식 항목 삭제

지식 항목 및 관련된 모든 데이터(임베딩, 패턴, 파일)를 영구적으로 삭제합니다.

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

**헤더:**

```text
Authorization: Bearer minds_your_api_key
```

**예시:**

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

**응답:** `204 No Content` (성공 시 빈 본문 반환)

### 삭제되는 데이터

- 지식 항목 레코드
- 관련된 모든 벡터 임베딩
- 관련된 모든 패턴
- 스토리지에 업로드된 파일 (파일 기반인 경우)

**경고:** 이 작업은 취소할 수 없습니다.

---

## 프로세싱 동작 방식

1. **업로드** - 콘텐츠가 저장되고 API가 성공을 반환합니다.
2. **추출** - 백그라운드 프로세싱을 통해 텍스트를 추출합니다 (스크래핑, 스크립트 추출, OCR, 비전 기술 활용).
3. **임베딩** - 추출된 콘텐츠가 벡터 임베딩으로 변환됩니다.
4. **검색** - 채팅 진행 시, 시맨틱 검색을 통해 관련 지식을 자동으로 찾아내 활용합니다.

---

## 에러

<table>
<thead>
  <tr>
    <th>
      코드
    </th>
    
    <th>
      메시지
    </th>
    
    <th>
      원인
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Link and description are required
      </code>
    </td>
    
    <td>
      필수 필드 누락
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        keywords array is required and must not be empty
      </code>
    </td>
    
    <td>
      키워드가 비어 있거나 누락됨
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        File too large
      </code>
    </td>
    
    <td>
      파일 크기가 50MB 제한을 초과함
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Can only watch link-based knowledge
      </code>
    </td>
    
    <td>
      파일에 대해 Watch 설정을 시도함
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      <code>
        Mind not found or access denied
      </code>
    </td>
    
    <td>
      유효하지 않은 Mind ID이거나 접근 권한이 없음
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      <code>
        Unsupported Content-Type
      </code>
    </td>
    
    <td>
      잘못된 Content-Type 헤더
    </td>
  </tr>
</tbody>
</table>

---

## 다음 단계

- [마인드와 채팅하기](/docs/api/chat)
- [마인드 생성하기](/docs/api/minds)
- [API 에러 및 제한 사항](/docs/api/errors)