Knowledge API

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

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

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

지식 항목 목록 조회

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

엔드포인트: GET /api/v1/sparks/{sparkId}/knowledge

헤더:

Authorization: Bearer minds_your_api_key

예시:

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge" \
  -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
  }
}

파일 업로드

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

엔드포인트: POST /api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

응답: 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/sparks/{sparkId}/knowledge

Content-Type: application/json

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

예시:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge

Content-Type: application/json

예시:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/enrich

이는 keywords 본문을 사용하는 POST /api/v1/sparks/{sparkId}/knowledge과 동일합니다. 자세한 내용은 키워드 검색을 참고하세요.

예시:

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

지식 항목 삭제

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

엔드포인트: DELETE /api/v1/sparks/{sparkId}/knowledge/{itemId}

헤더:

Authorization: Bearer minds_your_api_key

예시:

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key"

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

삭제되는 데이터

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

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

프로세싱 동작 방식

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

에러

다음 단계

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