가이드

Nubbo API 시작하기

처음부터 첫 요청까지 몇 분이면 충분해요. API 키를 만들고 직접 작성한 코드에서 스토리지 관리를 시작하세요.

Nubbo API는 내 코드에서 버킷을 다룰 수 있는 REST API예요. 파일, 폴더, 링크, 인박스, 갤러리, 라벨, 프로젝트, 자동화를 다룰 수 있어요. 이 가이드에서는 키를 만들고 curl로 첫 요청을 보내요.

제공되는 기능

  • 내 프로그램에서 Nubbo 공간을 관리해요. 키는 내가 선택한 것만 볼 수 있어요.
  • 내 코드와 스토리지 프로바이더 사이에서 직접 업로드하고 다운로드해요.
  • 트리거로 새 파일, 인박스 업로드, 활동에 반응해요.

시작하기 전에

Pro 또는 팀 요금제의 Nubbo 계정과 curl을 쓸 수 있는 터미널이 필요해요. 팀에서는 소유자나 관리자가 API 키를 만들어요.

1단계: 키 만들기

  1. Nubbo에서 설정 › API(팀이라면 팀 › API)를 열고 API 키 만들기를 누르세요.

  2. 이름을 정하고 다음을 선택하세요.

    • 권한: 읽기 전용 또는 읽기 및 쓰기.
    • 범위: 공간 전체 또는 선택한 버킷과 프로젝트. 키는 여기서 선택한 것만 볼 수 있어요.
    • 만료: 30일, 90일, 1년 또는 만료 없음. Nubbo가 7일 전에 알려 줘요.

    키 만들기를 누르세요. 본인 확인을 위해 Nubbo가 비밀번호를 물어봐요. 2단계 인증을 켜 두었다면 코드도 물어봐요.

    권한, 범위, 만료를 설정하는 API 키 만들기 창 권한, 범위, 만료를 설정하는 API 키 만들기 창
  3. 키를 복사하고 저장했어요를 누르세요. 키는 nbk_로 시작하며 전체를 볼 수 있는 건 이번 한 번뿐이에요. 키는 서버나 키를 사용할 도구에 보관하고, 웹 페이지에는 절대 넣지 마세요.

    복사할 수 있는 키가 표시된 API 키 창 복사할 수 있는 키가 표시된 API 키 창

2단계: 첫 요청

모든 요청의 Authorization 헤더에 키를 넣어 보내세요. 요청 수가 소모되지 않는 GET /v1/me로 시작하세요.

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_your_key"

응답에는 공간, 요금제, 이번 달 할당량, 그리고 권한과 범위가 포함된 키 정보가 담겨 있어요. 다음은 일부예요.

{
  "workspace": { "id": "…", "name": "노스 스튜디오", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "내 첫 번째 키",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

그다음 버킷 목록과 폴더의 파일 목록을 확인하세요.

curl https://api.nubbo.app/v1/buckets \
  -H "Authorization: Bearer nbk_your_key"

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=invoices/" \
  -H "Authorization: Bearer nbk_your_key"

목록은 data와 nextCursor를 반환해요. 다음 페이지를 보려면 그 값을 cursor에 넣어 보내세요. nextCursor가 null이면 더 이상 없어요.

GET /v1/me 요청과 응답이 표시된 터미널 GET /v1/me 요청과 응답이 표시된 터미널

3단계: 레퍼런스

설정 › API에서 문서 보기를 누르거나 api.nubbo.app/v1/docs를 여세요. 모든 리소스의 필드와 예시가 있어요. OpenAPI 문서는 api.nubbo.app/v1/openapi.json에 있어요.

curl 예시가 표시된 Nubbo API 레퍼런스 curl 예시가 표시된 Nubbo API 레퍼런스

업로드와 다운로드

파일은 Nubbo를 거치지 않아요. 파일을 업로드하려면 POST /v1/buckets/{bucketId}/uploads로 업로드를 요청하고, 돌려받은 사전 서명 주소로 파일을 보낸 뒤 POST /v1/uploads/{uploadId}/complete로 마무리하세요. 다운로드하려면 POST /v1/files/{fileId}/download-link로 링크를 요청하고 프로바이더에서 다운로드하세요.

한도

Pro팀
키당 분당 요청 수60120
월간 요청 수50,000100,000 + 좌석당 10,000
월간 트리거 이벤트 수20,00050,000 + 좌석당 5,000

할당량은 공간 단위이며 청구 주기마다 갱신돼요. GET /v1/me, 트리거 조회, 401, 429, 5xx 응답은 요청으로 집계되지 않아요. 트리거가 전달하는 이벤트는 각각 이벤트로 집계돼요. 모든 응답에는 X-RateLimit-Remaining과 X-Nubbo-Quota-Requests-Remaining 헤더가 포함되고, 설정 › API에서 기간 사용량을 볼 수 있어요.

Nubbo 설정에 표시된 기간 API 사용량 Nubbo 설정에 표시된 기간 API 사용량

문제가 생겼을 때

  • API_KEY_INVALID, API_KEY_REVOKED 또는 API_KEY_EXPIRED: 키가 유효하지 않거나, 취소됐거나, 만료됐어요. 헤더를 확인하거나 새 키를 만드세요.
  • API_PLAN_REQUIRED: 키의 공간에서 API를 사용할 수 없어요. API는 Pro와 팀 요금제에 있어요.
  • API_KEY_READ_ONLY: 읽기 전용 키예요. 읽기 및 쓰기 키를 만드세요.
  • API_RATE_LIMITED: 이 키로 보낸 요청이 너무 많아요. Retry-After의 초만큼 기다린 뒤 다시 시도하세요.
  • API_QUOTA_EXCEEDED: 공간이 이번 달 한도를 다 썼어요. details.resetsAt에서 갱신 시점을 알 수 있어요.

모든 오류에는 requestId가 있어요. 문의할 때 함께 알려 주세요.

Nubbo API에 대해 더 알아보세요. 코드 없이 사용하려면 Zapier, n8n 또는 Make 가이드를 따라 하세요. AI 어시스턴트에서 사용하려면 Nubbo를 Claude, ChatGPT 또는 Cursor에 연결하는 방법을 확인하세요.

자주 묻는 질문

어떤 요금제에 API가 포함되나요?

Pro와 팀이에요. 무료나 Personal에서는 요청에 API_PLAN_REQUIRED가 응답돼요.

API로 암호화된 파일을 읽을 수 있나요?

아니요. 암호화된 항목은 이름, 경로, 크기, 유형 없이 표시되고 이에 대한 변경은 모두 API_ENCRYPTED_CONTENT로 거부돼요.

네트워크 오류로 요청을 다시 보내면 어떻게 되나요?

POST와 PATCH에 Idempotency-Key 헤더를 보내세요. 24시간 동안 같은 요청을 반복하면 첫 번째 응답이 돌아오고 아무것도 두 번 만들어지지 않아요.

API가 예고 없이 바뀌나요?

아니요. 호환되지 않는 변경은 /v2로 나오고 /v1은 Deprecation 및 Sunset 헤더와 함께 최소 12개월 동안 유지돼요.

출처

단계는 아래 페이지로 확인했어요.