본문으로 건너뛰기

Hedy API

엔드포인트 URL과 API 키 생성 기능을 보여 주는 API 액세스 설정

Hedy API란?

Hedy API를 통해 회의 데이터, 녹취록, 요약, AI가 생성한 인사이트에 코드로 액세스할 수 있습니다. 자체 연동을 만들거나 업무를 자동화하거나 Zapier 같은 도구에 연결해 앱 밖에서도 Hedy의 기능을 활용할 수 있습니다. 모든 API 기능을 사용하려면 Pro를 구독하고 클라우드 동기화를 켜야 합니다. 코드를 작성하지 않고 AI 도우미와 대화하며 이 데이터를 활용하려면 Model Context Protocol(MCP)로 Hedy와 AI 도우미 연결을 참고하세요.

API 시작하기

  1. 설정을 열고 자동화 및 데이터 탭으로 이동하세요.

  2. API 액세스 섹션까지 스크롤하세요.

  3. 새 API 키 생성을 클릭하세요(Pro 구독 필요).

  4. API 키를 복사해 안전하게 보관하세요. 나중에 다시 확인할 수 없습니다.

  5. 엔드포인트에 관한 자세한 내용은 SwaggerHub의 API 문서를 참고하세요. 원본 OpenAPI 명세는 https://api.hedy.bot/docs에서 확인할 수 있습니다.

보안 참고 사항. API 키로 모든 Hedy 데이터에 액세스할 수 있습니다. 안전하게 보관하고 공개적으로 공유하거나 버전 관리에 커밋하지 마세요.

지역별 엔드포인트 URL

Hedy API는 사용자 데이터를 해당 관할권에 보관하기 위해 두 지역에서 실행됩니다. 계정을 만든 지역과 일치하는 기본 URL을 사용하세요.

  • 미국 계정 https://api.hedy.bot

  • EU 계정 https://eu-api.hedy.bot

두 지역 모두 같은 코드를 실행하고 동일한 엔드포인트와 기능을 제공합니다. API 키는 계정의 지역에 연결되므로 다른 지역의 기본 URL로 호출하면 인증이 실패합니다. 계정이 어느 지역을 사용하는지 모르겠다면 Hedy에서 설정 → 개인 정보 및 시스템 → 개인정보 보호 기본 설정으로 이동하세요. 깃발 아이콘으로 데이터 보관 위치를 알 수 있습니다.

이 문서의 예제는 https://api.hedy.bot를 사용합니다. EU 계정이라면 모든 예제에서 https://eu-api.hedy.bot로 바꾸세요.

API 기능

Hedy API로 다양한 회의 정보에 액세스할 수 있습니다.

  • 세션. 회의 세션을 나열하고 전체 녹취록, AI 요약, 핵심 사항을 조회합니다.

  • 주요 내용. 회의에서 중요했던 순간을 AI가 생성한 인사이트와 함께 조회합니다.

  • 토픽. 토픽을 만들고 수정하고 삭제하며 사용자 정의 컨텍스트 지침을 포함한 토픽으로 세션을 정리합니다.

  • 할 일. 모든 세션의 실행 항목을 조회하고 관리합니다.

  • 세션 컨텍스트. Hedy가 회의를 분석하는 방식에 적용할 재사용 가능한 지침을 만들고 관리합니다.

  • 사용자 정의 어휘. 이름과 기술 용어의 음성 텍스트 변환 정확도를 높여 주는 계정 어휘 목록을 읽고 교체합니다.

  • 웹훅. API를 통해 웹훅 엔드포인트를 설정하고 관리해 이벤트 알림을 실시간으로 받습니다.

  • 사용자 정보. /me 엔드포인트로 계정 정보를 조회합니다.

API는 이미 만들어진 세션을 다룹니다. 실시간 세션의 시작과 종료는 기기의 Hedy 앱에서 이루어지므로 API로는 할 수 없습니다. 같은 기기의 스크립트나 다른 앱에서 세션을 시작하거나 종료하려면 다른 앱에서 세션 시작을 참고하세요.

인증

모든 API 요청은 API 키로 인증해야 합니다. Authorization 헤더에 키를 넣으세요.

Authorization: Bearer YOUR_API_KEY

웹훅

Hedy 계정에서 이벤트가 발생할 때 실시간 알림을 받으려면 웹훅을 설정하세요.

  1. ‘API 액세스’ 섹션에서 웹훅 관리를 클릭하세요.

  2. + 버튼을 클릭해 새 웹훅을 추가하세요.

  3. HTTPS 엔드포인트 URL을 입력하세요.

  4. 수신할 이벤트를 선택하세요.

    • session.created - 새 세션이 시작될 때

    • session.ended - 세션 처리가 완료될 때

    • session.exported - 사용자가 세션을 수동으로 내보낼 때

    • highlight.created - 새 주요 내용이 추가될 때

    • todo.exported - 세션의 할 일을 내보낼 때

    • suggestion.created - 세션 중 Hedy가 자동 제안을 표시할 때

  5. 웹훅을 저장하고 페이로드를 검증할 때 사용할 서명 비밀 키를 기록해 두세요.

/webhooks 엔드포인트에 GET, POST, DELETE를 호출해 웹훅을 코드로 관리할 수도 있습니다. 계정당 최대 50개의 웹훅을 만들 수 있습니다.

웹훅 서명 검증

모든 웹훅 요청에는 Hedy가 보냈는지 확인할 수 있도록 X-Hedy-Signature 헤더에 서명이 포함됩니다. 서명은 웹훅의 서명 비밀 키로 원본 요청 본문을 서명한 HMAC-SHA256 해시입니다. 서버에서 페이로드를 처리하기 전에 서명을 검증해 출처를 확인하세요. 각 요청의 X-Hedy-Event 헤더에는 session.ended와 같은 이벤트 유형이 포함됩니다.

세션 컨텍스트

세션 컨텍스트를 사용하면 Hedy가 회의를 어떻게 분석할지 정하는 사용자 정의 지침을 만들어 다시 사용할 수 있습니다. 예를 들어 “영업 통화” 컨텍스트는 실행 항목과 고객의 반론에 집중하고, “스탠드업 회의” 컨텍스트는 진행을 막는 문제와 업데이트를 추적하도록 설정할 수 있습니다.

다음 API로 세션 컨텍스트를 관리하세요.

  • GET /contexts - 모든 세션 컨텍스트 나열

  • GET /contexts/{id} - ID로 특정 컨텍스트 조회

  • POST /contexts - 새 컨텍스트 생성(제목 및 내용)

  • PATCH /contexts/{id} - 기존 컨텍스트 수정

  • DELETE /contexts/{id} - 컨텍스트 삭제

컨텍스트를 기본값으로 지정하면 모든 새 세션에 자동으로 적용됩니다. 무료 요금제 계정은 세션 컨텍스트를 1개까지만 사용할 수 있습니다.

API로 토픽 관리

토픽으로 세션을 범주별로 정리할 수 있습니다. API는 다음과 같은 토픽 관리 기능을 지원합니다.

  • GET /topics - AI가 생성한 인사이트와 세션 수를 포함해 모든 토픽 나열

  • GET /topics/{id} - 특정 토픽의 세부 정보 조회

  • POST /topics - 이름, 설명, 색상, 아이콘, 기본 세션 유형을 지정해 새 토픽 생성

  • PATCH /topics/{id} - 토픽 속성, 사용자 정의 컨텍스트 또는 기본 세션 유형 수정

  • DELETE /topics/{id} - 토픽 삭제(세션은 토픽과의 연결만 해제되며 삭제되지 않습니다.)

  • GET /topics/{id}/sessions - 토픽에 포함된 모든 세션 나열

  • PATCH /sessions/{id} - {"topicId": "<topic id>"}로 세션을 토픽에 옮기거나 {"topicId": null}로 토픽에서 뺍니다. 지원하는 필드는 topicId 하나이며 Hedy가 영향을 받는 토픽의 AI 개요를 새로 생성합니다.

클라우드 동기화를 끈 상태에서 캡처한 세션은 옮길 수 없습니다(409 session_not_synced). 대상 토픽이 존재해야 하며 삭제가 진행 중이면 안 됩니다.

토픽의 topicContext 필드에 사용자 정의 지침을 최대 20,000자까지 넣어 Hedy가 해당 토픽에 할당된 세션을 분석하는 방식을 지정할 수 있습니다. 이 지침은 해당 토픽에서 시작하는 모든 세션과 그 세션의 실시간 제안에 자동으로 적용됩니다. API로 토픽을 준비하는 것만으로 세션에도 지침이 적용됩니다.

토픽의 dominantSessionType 필드에는 해당 토픽에서 시작하는 세션에 쓸 세션 유형을 지정할 수 있습니다. 코드로 여러 토픽을 만들 때 모든 토픽에 기본 유형이 적용되는 일을 피할 수 있습니다. 이 필드는 실제 사용에서 파생되는 통계이기도 합니다. 세션이 생기면 Hedy가 실제로 사용한 유형을 기준으로 다시 계산하므로, 지정한 값은 시작점으로 쓰입니다. 이미 세션이 있는 토픽에 이 값을 지정하면 다음 세션 한 번에만 적용됩니다. 사용할 수 있는 세션 유형 값은 API 레퍼런스를 참고하세요.

사용자 정의 어휘

사용자 정의 어휘는 업무에서 쓰는 이름, 약어, 기술 용어를 Hedy에 알려 주어 음성 텍스트 변환의 정확도를 높입니다. 목록은 계정에 저장되며 모든 세션에 적용됩니다.

  • GET /vocabulary - 현재 용어 목록과 기능 활성화 여부 조회

  • PUT /vocabulary - 전체 용어 목록 교체

PUT은 용어를 추가하는 대신 전체 목록을 교체합니다. 새 목록에 없는 기존 용어는 삭제됩니다. 용어는 2~50자씩 최대 100개를 보내세요. 대소문자를 구분하지 않으며 중복 용어를 허용하지 않습니다. 꺾쇠괄호, 중괄호, 대괄호, 역슬래시, 파이프, 백틱, 물결표는 포함할 수 없습니다.

enabled 플래그는 읽고 쓸 수 있습니다. 용어를 교체할 때 생략하면 저장된 값은 그대로 유지됩니다. 어휘 업데이트를 자동화할 경우 먼저 이 플래그를 읽으면 새 어휘가 실제로 사용될지, 어휘 기능이 꺼진 계정에 저장만 될지 알 수 있습니다.

호출 한 번으로 전체 목록을 바꿀 수 있으므로 긴 목록 하나를 관리하는 대신 회의에 필요한 이름과 용어로 매번 목록을 바꿀 수 있습니다.

일반적인 활용 사례

  • 프로젝트 관리 연동. 회의 실행 항목으로 프로젝트 관리 도구에 작업을 자동으로 만듭니다.

  • 지식 관리. 회사 지식 베이스에서 회의 콘텐츠를 검색할 수 있게 색인합니다.

  • CRM 연동. 회의에서 얻은 인사이트를 고객 기록에 반영합니다.

  • 분석 대시보드. 회의 패턴과 생산성에 관한 맞춤 보고서를 만듭니다.

  • 워크플로 자동화. 회의 내용이나 완료 여부를 기준으로 작업을 실행합니다.

  • Zapier 연동. Zapier로 Hedy를 수천 개 앱에 연결합니다. 엔드포인트에 ?format=zapier를 붙이면 Zapier와 호환되는 평면 배열 형식으로 응답합니다.

API 한도 및 권장 사항

  • 호출 한도. API 키당 분당 200회 요청

  • 페이지네이션. limit 매개변수(기본값 50, 최대 100)와 after 커서 매개변수로 결과를 페이지 단위로 조회하세요.

  • 가능하면 응답을 캐시해 API 호출을 줄이세요.

  • 오류가 발생하면 지수 백오프로 재시도하세요.

  • 실시간 업데이트에는 폴링 대신 웹훅을 사용하세요.

할 일 자동 내보내기

할 일 자동 내보내기를 켜면 연동한 시스템으로 실행 항목이 전송됩니다.

  1. ‘API 액세스’ 섹션에서 자동 할 일 내보내기를 켜세요.

  2. 설정한 웹훅 엔드포인트로 할 일이 자동으로 전송됩니다.

  3. 각 할 일에는 컨텍스트, 담당자 제안, 관련 회의 정보가 포함됩니다.

코드 예제

최근 세션을 조회하는 간단한 예제입니다.

curl -X GET "https://api.hedy.bot/sessions?limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

더 많은 예제와 전체 엔드포인트 레퍼런스는 API 문서에서 확인하세요.

문제 해결

401 Unauthorized 오류

  • API 키가 올바르고 형식이 정확한지 확인하세요.

  • Pro 구독이 활성 상태인지 확인하세요.

  • 계정에 클라우드 동기화가 켜져 있는지 확인하세요.

  • API 키를 다시 생성한 적이 있는지 확인하세요. 다시 생성하면 이전 키는 무효화됩니다.

응답이 비어 있거나 데이터가 누락됨

  • 클라우드 동기화가 켜져 있는지 확인하세요. API는 클라우드에 동기화된 데이터에만 액세스합니다.

  • 세션 종료 후 데이터가 동기화되도록 몇 분 기다리세요.

  • 날짜 필터와 페이지네이션 매개변수를 확인하세요.

  • 데이터 유형에 맞는 엔드포인트를 사용 중인지 확인하세요.

웹훅에서 이벤트를 수신하지 못함

  • 엔드포인트 URL이 필수 프로토콜인 HTTPS를 사용하는지 확인하세요.

  • 서버가 200 OK 상태로 응답하는지 확인하세요.

  • 서명 검증을 구현하고 있다면 X-Hedy-Signature 헤더를 확인하세요.

  • ‘웹훅 테스트’ 버튼으로 웹훅을 테스트하세요.

  • 방화벽 규칙이 Hedy 서버를 차단하고 있지 않은지 확인하세요.

호출 한도 초과

  • 캐시를 사용해 중복 API 호출을 줄이세요.

  • 실시간 업데이트에는 폴링 대신 웹훅을 사용하세요.

  • 가능한 작업을 일괄 처리하세요.

  • 더 높은 한도가 필요하면 고객 지원에 문의하세요.

팁. 실시간 업데이트에는 폴링 대신 웹훅을 사용하세요. 더 효율적이며 데이터가 바뀌면 즉시 알림을 받을 수 있습니다.

개인정보 보호 및 보안

사용자 데이터의 보안을 중요하게 생각합니다.

  • 모든 API 통신은 HTTPS로 암호화됩니다.

  • 언제든 API 키를 다시 생성할 수 있습니다. 이전 키는 무효화됩니다.

  • 웹훅 페이로드는 검증할 수 있도록 HMAC-SHA256으로 서명합니다.

  • 유효한 인증이 있어야 데이터에 액세스할 수 있습니다.

  • 모든 엔드포인트는 엄격한 보안 헤더 설정을 적용합니다.

도움 받기

API에 관한 질문이 있다면 다음 자료를 참고하세요.