Skip to Content
문서API 레퍼런스파일 저장소

파일 저장소

CI 파이프라인 같은 외부 시스템이 managed 파일 저장소에 파일을 올리고 받을 때 쓰는 API예요.
storage scope가 있는 API Token으로 호출하며, 토큰에 묶인 binding 범위 안에서 동작해요.

Base URLhttps://api.deplite.io인증Authorization: Bearer dpl_...스코프storageSDKJavaScript · Flutter · GitHub Actions

업로드 흐름

  1. POST/v1/storage/files/presign-upload

    업로드 URL과 fileId를 받아요.

  2. PUT{uploadUrl}저장소로 직접 전송

    받은 URL로 파일을 바로 올려요.
    요청 헤더는 응답의 headers를 그대로 사용해주세요.

  3. POST/v1/storage/files/{id}/complete

    완료를 알리면 파일이 active 상태가 돼요.

SDK의 files.upload()와 GitHub Actions의 Deplite/files-action은 세 단계를 한 번에 처리해요.

권한

storage scope는 토큰을 발급할 때 binding과 권한을 함께 지정해요.
권한은 read·write·delete를 자유롭게 조합할 수 있어요.

권한호출할 수 있는 엔드포인트
read다운로드 URL 발급, 파일 조회, 파일 목록
write업로드 URL 발급, 업로드 완료
delete파일 삭제

업로드 URL 발급

POST/v1/storage/files/presign-upload권한 storage · write

파일을 올릴 사전 서명 URL을 발급해요.
받은 uploadUrl로 파일을 올린 뒤 업로드 완료를 호출해야 파일이 active 상태가 돼요.

요청 본문

cleanupRulestring필수

업로드한 파일을 정리할 규칙이에요.

허용 값ttlpersistent
ttlSecondsinteger

cleanupRule이 ttl일 때 보관할 시간(초)이에요.

60 ~ 7,776,000 (90일)
bindingIdstring · uuid

파일을 저장할 binding이에요.

허용 binding이 하나면 생략할 수 있어요.
전체 binding 허용이면 조직 기본 binding을 사용해요.
여러 binding이면 필수예요.
filenamestring

원본 파일명이에요.

최대 255자
contentTypestring

파일의 MIME 타입이에요.

최대 255자

응답

성공하면 HTTP 201과 아래 필드를 돌려줘요.

fileIdstring · uuid

만들어진 파일 ID예요.
업로드 완료 요청에 사용해요.

uploadUrlstring · URL

파일을 올릴 사전 서명 URL이에요.

methodstring

업로드할 HTTP 메서드예요.

허용 값PUT
headersobject

업로드 요청에 그대로 포함할 헤더예요.

expiresInSecondsinteger

업로드 URL의 유효 시간(초)이에요.

오류

400
토큰이 binding 여러 개를 허용하지만 bindingId가 없어요.
bindingId is required (token allows multiple bindings)
400
cleanupRule이 없거나 TTL 값이 허용 범위를 벗어났어요.
403
토큰에 해당 binding의 write 권한이 없어요.
Token lacks 'write' on binding <bindingId>

공통 오류는 에러 코드에서 확인해주세요.

업로드 완료

POST/v1/storage/files/{id}/complete권한 storage · write

파일을 uploadUrl로 올린 뒤 호출해주세요.
본문 없이 호출하며 성공하면 파일이 active 상태가 돼요.

경로 파라미터

idstring · uuid필수

업로드 URL 발급 응답에서 받은 fileId예요.

응답

성공하면 HTTP 201과 파일 객체를 돌려줘요.

오류

400
id가 UUID 형식이 아니에요.
Validation failed (uuid is expected)
403
토큰에 해당 binding의 write 권한이 없어요.
Token lacks 'write' on binding <bindingId>
404
파일을 찾을 수 없어요.
File not found

공통 오류는 에러 코드에서 확인해주세요.

다운로드 URL 발급

GET/v1/storage/files/{id}/download-url권한 storage · read

다운로드 URL은 호출할 때마다 새로 발급돼요.
워크플로우에 전달할 때는 호출 직전에 받아 params로 넘겨주세요.

경로 파라미터

idstring · uuid필수

다운로드할 파일 ID예요.

응답

성공하면 HTTP 200과 아래 필드를 돌려줘요.

downloadUrlstring · URL

파일을 내려받을 사전 서명 URL이에요.

expiresInSecondsinteger

다운로드 URL의 유효 시간(초)이에요.

오류

400
id가 UUID 형식이 아니에요.
Validation failed (uuid is expected)
403
토큰에 해당 binding의 read 권한이 없어요.
Token lacks 'read' on binding <bindingId>
404
파일을 찾을 수 없어요.
File not found

공통 오류는 에러 코드에서 확인해주세요.

파일 정보 조회

GET/v1/storage/files/{id}권한 storage · read

토큰이 접근할 수 있는 binding 범위 안에서 파일 메타데이터를 조회해요.
파일 ID는 UUID 형식이어야 해요.

경로 파라미터

idstring · uuid필수

조회할 파일 ID예요.

응답

성공하면 HTTP 200과 파일 객체를 돌려줘요.

오류

400
id가 UUID 형식이 아니에요.
Validation failed (uuid is expected)
403
토큰에 해당 binding의 read 권한이 없어요.
Token lacks 'read' on binding <bindingId>
404
파일을 찾을 수 없어요.
File not found

공통 오류는 에러 코드에서 확인해주세요.

파일 목록 조회

GET/v1/storage/files권한 storage · read

응답은 파일 메타데이터 배열이며 최대 200건이에요.
bindingId 또는 status로 결과를 좁힐 수 있어요.

쿼리 파라미터

bindingIdstring · uuid

특정 binding의 파일만 조회해요.

statusstring

파일 상태로 결과를 좁혀요.

허용 값pendingactivedeletingdeleteddelete_failed

응답

성공하면 HTTP 200과 파일 객체 배열을 돌려줘요.

오류

400
bindingId가 UUID 형식이 아니거나 status 값이 허용되지 않아요.
403
토큰에 read 권한이 없거나 binding 범위 밖이에요.
Token lacks 'read' permission

공통 오류는 에러 코드에서 확인해주세요.

파일 삭제

DELETE/v1/storage/files/{id}권한 storage · delete

파일을 삭제해요.
릴리스가 참조 중인 파일은 App Deploy에서 릴리스를 먼저 회수해야 삭제할 수 있어요.

경로 파라미터

idstring · uuid필수

삭제할 파일 ID예요.

응답

성공하면 HTTP 204로 응답하고 본문은 없어요.

오류

400
id가 UUID 형식이 아니에요.
Validation failed (uuid is expected)
403
토큰에 해당 binding의 delete 권한이 없어요.
Token lacks 'delete' on binding <bindingId>
404
파일을 찾을 수 없어요.
File not found

공통 오류는 에러 코드에서 확인해주세요.

파일 객체

idstring · uuid

파일 ID예요.

bindingIdstring · uuid

파일이 저장된 binding ID예요.

filenamestringnull 가능

원본 파일명이에요.

contentTypestringnull 가능

파일의 MIME 타입이에요.

sizeintegernull 가능

파일 크기(바이트)예요.

statusstring

현재 파일 상태예요.

허용 값pendingactivedeletingdeleteddelete_failed
cleanupRulestring

파일 정리 규칙이에요.

허용 값ttlon_job_endpersistent
expiresAttimestampnull 가능

파일 만료 시각이에요.

deletedAttimestampnull 가능

파일 삭제 시각이에요.

createdAttimestamp

파일 메타데이터 생성 시각이에요.

예시
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "bindingId": "3f2b8c1e-5d4a-4b9e-8f1a-2c6d7e8f9a0b",
  "filename": "release.apk",
  "contentType": "application/vnd.android.package-archive",
  "size": 28473921,
  "status": "active",
  "cleanupRule": "ttl",
  "expiresAt": "2026-11-04T12:00:00.000Z",
  "deletedAt": null,
  "createdAt": "2026-10-28T12:00:00.000Z"
}

외부 API 응답에는 organizationId·jobId 같은 내부 필드가 포함되지 않아요.
토큰의 binding 권한 범위에서만 파일 메타데이터를 조회할 수 있어요.

관련 문서

최종 수정 일자: