API Key 종류별로 어떤 노트를 다루나요?
API Key 종류를 구분하는 방법과 발급 절차는 인증에서 확인하세요.
범위 밖의 노트는 어떻게 나타나나요?
범위 밖의 노트는
403이 아니라 404를 반환해요. 노트가 존재하는지 자체를 알리지 않기 위한 동작이에요. 그래서 삭제된 노트와 응답이 같아요. 어제까지 되던 요청이 404를 반환하기 시작했다면 그 노트가 전체 공유 폴더 밖으로 이동했는지 먼저 확인하세요.폴더는 어디까지 다루나요?
시스템 API Key로 할 수 있는 폴더 작업은 제목 수정, 이동, 순서 변경 세 가지예요. 폴더 목록·단건 조회, 폴더 삭제, 노트를 폴더에 넣고 빼는 요청은 폴더 종류와 상관없이 계정 API Key만 할 수 있고, 시스템 API Key로 호출하면401을 반환해요.
이 세 작업은 전체 공유 폴더에만 할 수 있어요. 개인 폴더나 일부 사람에게만 공유한 폴더를 대상으로 하면 403을 반환하고, 옮길 위치로 지정한 상위 폴더에도 같은 조건이 적용돼요. 순서 변경은 목록에 전체 공유 폴더가 아닌 폴더가 하나라도 있으면 요청 전체가 403이 되니, 전체 공유 폴더만 골라서 보내세요.
폴더를 옮겨도 공유 범위는 그대로예요. 상위 폴더의 공유 설정을 물려받는 옵션(sharingTypeUpdateStrategy)을 보내도 시스템 API Key에서는 적용되지 않아요.
노트가 어느 폴더에 들어 있는지 조회할 때(GET /v1/external/notes/{guid}/folders)는 전체 공유 폴더만 응답에 담겨요. 같은 노트가 구성원의 개인 폴더에도 들어 있다면 그 폴더는 빠져요. 이때는 에러가 나지 않고 목록만 짧아지므로, 폴더 이름으로 분류하는 연동이라면 계정 API Key로 볼 때와 결과가 다를 수 있어요.
노트를 검색할 때 folderId로 폴더를 지정하는 경우에도 전체 공유 폴더만 쓸 수 있어요. 개인 폴더의 ID를 지정하면 404를 반환해요.
이 범위가 적용되지 않는 API는 무엇인가요?
음성 파일 작업(Voice File Job) API와voice_file_job.* 이벤트(created, completed, failed, deleted)는 이 범위의 대상이 아니에요.
개인 폴더의 노트가 필요하면
계정 API Key를 발급해서 사용하세요. 발급 방법은 인증을 참고하세요. 연동에 필요한 노트를 전체 공유 폴더로 옮기는 방법도 있어요.기존에 발급한 키는 어떻게 되나요?
이 범위가 적용되기 전에 발급한 시스템 API Key와 등록한 시스템 Webhook은 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 그래서 지금 새로 발급한 키가 기존 키보다 노트를 더 적게 반환할 수 있는데 정상이에요. 전환되면 조회 결과가 줄어드는 것뿐 아니라 폴더 제목 수정·이동·순서 변경이403으로 거부될 수 있어요. 지금 그 요청이 성공하는 폴더라도 전체 공유 폴더가 아니면 전환 후에는 거부돼요.
전환 대상인 키와 Webhook은 Tiro Platform의 API Keys, Webhooks 화면에서 확인해보세요.