POST/v1/uploads
멀티파트 업로드 시작
create_upload
큰 파일(설치 환경의 멀티파트 업로드 한도까지, 기본 5GB)의 업로드 세션을 열어요. 이름, 콘텐츠 유형, 크기, 그리고 업로드를 무엇에 쓸지 정하는 purpose 값을 보내요. 용도는 card_file(POST /v1/cards), archive(POST /v1/cards/archive), import_attachment(사용자 지정 소스 문서의 첨부 파일) 중 하나예요. 응답에는 id(upl_ 뒤에 16진수 문자 32자), 파트 크기 part_size, 파트 수 part_count가 들어 있어요. 마지막 파트를 뺀 모든 파트는 정확히 part_size바이트(5~100MiB)이고, 마지막 파트는 나머지예요. 완료되지 않은 업로드는 24시간 동안 유지돼요(expires_at).
파일 이름의 확장자가 용도에 맞는 형식이 아니면 415 uploads.unsupported_format 오류를 반환해요(가져오기 첨부 파일은 모든 확장자를 받아요). 설치 환경의 한도나 요금제에 따른 조직의 전체 저장 공간보다 큰 파일은 413 uploads.too_large 오류를 반환해요. 조직의 완료되지 않은 업로드까지 포함해 남은 저장 공간이 부족하면 402 limits.storage 오류를 반환해요.
파트는 Sursa를 거쳐(PUT /v1/uploads/{upload_id}/parts/{n}) 파일 저장소에 조직의 키로 암호화되어 저장돼요. 저장소로 가는 직접 링크는 없어요. 업로드를 만든 API 키나 사용자만 업로드를 보고 쓸 수 있어요. 1.62.0에서 추가됐어요.
인증
Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.
헤더 파라미터
Idempotency-Keystring쓰기 요청을 안전하게 재시도하기 위한 키예요. 출력 가능한 ASCII 문자 1~255자이며, 논리적 처리 단위마다 UUID v4를 하나씩 쓰기를 권장해요. 24시간 안에 같은 키로 재시도하면 처리를 다시 실행하지 않고, 저장된 응답(상태, 헤더, 본문)을
Idempotency-Replayed: true헤더와 함께 반환해요. 같은 키를 다른 메서드, 경로,Content-Type값이나 본문과 함께 보내면409 api.idempotency_mismatch오류를 반환하고, 첫 요청이 아직 실행 중이면409 api.idempotency_in_progress오류를Retry-After: 1헤더와 함께 반환해요. 5xx나 429 응답 뒤에는 키가 해제되어, 재시도하면 처리가 다시 실행돼요. 키의 적용 범위는 조직과 호출자(API 키, 사용자, 사용자 지정 소스 키)예요.length ≥ 1, length ≤ 255
요청 본문
application/json
filenamestring필수확장자를 포함한 파일 이름. 확장자로 형식이 정해져요.
length ≥ 1, length ≤ 255
content_typestring선언한 콘텐츠 유형(MIME). 파일 시그니처와 비교해요.
length ≤ 255
sizeinteger (int64)필수파일 크기(바이트).
≥ 1
sha256string미리 알고 있다면 파일의 SHA-256.
complete단계에서 체크섬을 이 값과 비교해요.
응답
201업로드 세션이 생성되었어요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
Idempotency-Replayedtrue이면 이Idempotency-Key값으로 저장된 응답을 재생한 것이에요. 처리는 다시 실행되지 않았어요.
application/json
idstring필수업로드 ID(
upl_뒤에 16진수 32자).filenamestring필수파일 이름(폴더 제외).
content_typestring필수선언한 콘텐츠 유형. 선언하지 않았으면 비어 있어요.
sizeinteger (int64)필수파일 크기(바이트).
sha256string | null필수생성할 때나
complete단계에서 선언한 파일의 SHA-256. 아직 모르면null이에요.part_sizeinteger (int64)필수마지막 파트를 제외한 각 파트의 크기(5~100MiB).
part_countinteger필수파트 수.
≥ 1, ≤ 1000
parts_receivedinteger필수수신된 파트 수.
≥ 0
번호별로 수신된 파트(
POST /v1/uploads응답에서는 비어 있어요).reject_reasonstring | null필수거부 사유(
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. 값이 늘어날 수 있는 열거형이에요. 거부되지 않았으면null이에요.reject_detailsobject | null필수거부 세부 정보(확장자, 선언한 형식과 감지한 형식, 체크섬). 거부되지 않았으면
null이에요.created_atstring (date-time)필수업로드가 생성된 시각.
expires_atstring (date-time)필수업로드를 완료하고, 준비된 뒤에는 사용해야 하는 기한.
completed_atstring (date-time) | null필수검사가 끝난 시각(
ready또는rejected).consumed_atstring (date-time) | null필수업로드가 사용된 시각(카드, 압축 파일 또는 가져오기에서).
401자격 증명(세션 쿠키나 API 키)을 보내지 않았거나 키를 찾을 수 없어요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
402조직이 요금제 한도(카드, 저장 공간, 사용자)에 도달했어요. `error.details` 필드에 `kind`, `limit`, `used` 값이 들어 있어요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
403이 동작은 허용되지 않아요. 역할이 부족하거나, 컬렉션이나 카드에 접근할 수 없거나, 요청이 “View as” 모드로 실행 중이거나, 조직이 정지 또는 삭제된 경우예요(`detail` 필드는 `code: org_suspended | org_deleted` 값을 가진 객체예요).
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
413요청 본문이 허용 크기를 넘었어요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
415지원하지 않는 파일 형식이에요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
422유효성 검사 오류예요. 본문이나 파라미터가 스키마와 맞지 않거나(`detail` 필드는 유효성 검사 오류 목록), 파라미터 값이 허용 범위를 벗어났어요(`detail` 필드는 메시지).
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
429요청이 너무 많거나(`api.rate_limited`), 조직의 분·일·월 할당량을 다 썼거나(`api.quota_exceeded`, `error.details` 필드에 `quota`, `limit`, `reset_at` 값이 있어요), 조직의 한도에 도달했거나, 답변 서비스가 바쁜 상태예요(`answers.engine_busy`). `Retry-After` 헤더에 적힌 시간만큼 기다리세요.
응답 헤더
Retry-After요청을 다시 시도하기 전에 기다릴 초.
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
오류 코드
모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.
안전한 재시도
POST와 PATCH 요청마다 Idempotency-Key 헤더(예: UUID)를 보내세요. 24시간 안에 같은 키로 재시도하면 요청을 다시 실행하지 않고 저장된 응답을 반환해요.
호출 한도
응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.