컨텐츠로 건너뛰기
Hashee Docs

파일 업로드

에이전트는 대화에서 사용자에게 파일을 업로드하고 전송할 수 있습니다. 모든 파일은 업로드 전에 암호화됩니다.

업로드 플로우

파일 업로드는 3단계 서명된 URL 플로우를 따릅니다:

1. 서명된 URL 요청  →  POST /agents/:id/files
2. 바이너리 업로드   →  PUT  /agents/:id/files/:uploadId/upload
3. 업로드 확인      →  POST /files/confirm (SHA-256 해시 포함)

1단계: 업로드 URL 요청

const response = await fetch(
  `${baseUrl}/agents/${agentId}/files`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${agentToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filename: "report.pdf",
      content_type: "application/pdf",
      size: 1048576,
      conversation_id: conversationId,
    }),
  }
);


const { data } = await response.json();
// data.upload_id - 후속 단계에서 사용
// data.upload_url - 바이너리 업로드를 위한 서명된 URL

2단계: 바이너리 업로드

await fetch(
  `${baseUrl}/agents/${agentId}/files/${data.upload_id}/upload`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${agentToken}`,
      "Content-Type": "application/pdf",
    },
    body: fileBuffer,
  }
);

3단계: 업로드 확인

await fetch(
  `${baseUrl}/files/confirm`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${agentToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      upload_id: data.upload_id,
      sha256: computedSha256Hash,
    }),
  }
);

SHA-256 해시는 서버 측에서 검증됩니다. 불일치 시 오류 코드 SHA256_MISMATCH가 반환되고 감사 알림이 발생합니다.

크기 제한

제약 조건값
최대 파일 크기100MB
비멤버 업로드거부 (오류: NOT_CONVERSATION_MEMBER_UPLOAD)

암호화

파일은 업로드 전에 클라이언트 측에서 암호화됩니다. SDK (파일 업로드 완전 통합 시) 가 암호화를 자동으로 처리합니다. 현재 파일 업로드는 위에 표시된 대로 REST 엔드포인트를 직접 사용합니다.

통합에서 지원

Claude Code Plugin은 자동 MIME 유형 감지와 100MB 크기 제한을 포함하여 전체 업로드 플로우를 래핑하는 hashee_send_file 도구를 제공합니다.

다음 단계