Knowledge API

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

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

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

Knowledge 목록 및 항목 상태 응답은 비공개입니다(Cache-Control: private, no-store). GET /api/v1/minds/{mindId}/knowledge/{itemId}/status는 확정된 mindId와 itemId, 공개 처리 필드, 임베딩·패턴 수, readyForRetrieval을 반환합니다. 워커 진단 정보와 임의의 저장 메타데이터는 제외되며 처리 실패에는 일반 메시지 Knowledge processing failed를 사용합니다. 잘못 저장된 상태는 unknown이 됩니다. 처리 메타데이터가 없는 이전 항목은 임베딩이 있으면 completed, 없으면 unknown입니다. 인증 정보가 없거나 차단되면 401, Mind나 항목에 접근할 수 없으면 404, 예상치 못한 저장소 오류는 일반적인 500을 반환합니다.

지식 항목 목록 조회

Mind 지식 항목의 한 페이지를 가져옵니다.

limit(1–100, 기본값 100)과 offset(0 이상의 정수, 기본값 0)을 사용합니다. 항목은 createdAt 내림차순, 그다음 ID 내림차순으로 정렬됩니다. data.total은 전체 항목 수이며 data.pagination에는 limit, offset, hasMore가 포함됩니다. hasMore가 true이면 offset + items.length로 다음 페이지를 요청합니다. 페이지는 고정된 스냅샷이 아닙니다. 요청 사이의 추가나 삭제로 위치가 달라질 수 있습니다. 잘못되거나 중복된 페이지 매개변수는 400을 반환합니다.

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

헤더:

Authorization: Bearer minds_your_api_key

예시:

curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge?limit=100&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

응답:

{
  "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,
    "pagination": { "limit": 100, "offset": 0, "hasMore": false }
  }
}

파일 업로드

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

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

Content-Type: multipart/form-data

지원되는 포맷:

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

예시:

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"

워크스페이스 업로드 URL의 파일 접근 권한은 Mind 편집 권한과 별개입니다. 본인이 업로드한 파일, 유효한 서명이 있는 채팅 파일 URL 또는 업로더의 Study를 통해 공유된 컨텍스트 파일을 사용하세요. 그렇지 않으면 요청은 403 Upload access denied를 반환합니다. 객체 경로를 아는 것만으로 접근 권한이 생기지는 않습니다.

응답: 201 Created

{
  "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 본문을 전송합니다.

예시:

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

{
  "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

예시:

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

{
  "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}

헤더:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

요청 본문:

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

예시:

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"}'

응답:

{
  "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과 동일합니다. 자세한 내용은 키워드 검색을 참고하세요.

예시:

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}

헤더:

Authorization: Bearer minds_your_api_key

예시:

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. 검색 - 채팅 진행 시, 시맨틱 검색을 통해 관련 지식을 자동으로 찾아내 활용합니다.

에러

다음 단계

• 마인드와 채팅하기
• 마인드 생성하기
• API 에러 및 제한 사항