파일 저장소
CI 파이프라인 같은 외부 시스템이 managed 파일 저장소에 파일을 올리고 받을 때 쓰는 API예요.
storage scope가 있는 API Token으로 호출하며, 토큰에 묶인 binding 범위 안에서 동작해요.
https://api.deplite.io인증Authorization: Bearer dpl_...스코프storageSDKJavaScript · Flutter · GitHub Actions업로드 흐름
- POST
/v1/storage/files/presign-upload업로드 URL과
fileId를 받아요. - PUT
{uploadUrl}저장소로 직접 전송받은 URL로 파일을 바로 올려요.
요청 헤더는 응답의headers를 그대로 사용해주세요. - 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 발급
/v1/storage/files/presign-upload파일을 올릴 사전 서명 URL을 발급해요.
받은 uploadUrl로 파일을 올린 뒤 업로드 완료를 호출해야 파일이 active 상태가 돼요.
요청 본문
cleanupRulestring필수업로드한 파일을 정리할 규칙이에요.
ttlpersistentttlSecondsintegercleanupRule이 ttl일 때 보관할 시간(초)이에요.
bindingIdstring · uuid파일을 저장할 binding이에요.
전체 binding 허용이면 조직 기본 binding을 사용해요.
여러 binding이면 필수예요.
filenamestring원본 파일명이에요.
contentTypestring파일의 MIME 타입이에요.
응답
성공하면 HTTP 201과 아래 필드를 돌려줘요.
fileIdstring · uuid만들어진 파일 ID예요.
업로드 완료 요청에 사용해요.
uploadUrlstring · URL파일을 올릴 사전 서명 URL이에요.
methodstring업로드할 HTTP 메서드예요.
PUTheadersobject업로드 요청에 그대로 포함할 헤더예요.
expiresInSecondsinteger업로드 URL의 유효 시간(초)이에요.
오류
bindingId가 없어요.bindingId is required (token allows multiple bindings)cleanupRule이 없거나 TTL 값이 허용 범위를 벗어났어요.write 권한이 없어요.Token lacks 'write' on binding <bindingId>공통 오류는 에러 코드에서 확인해주세요.
업로드 완료
/v1/storage/files/{id}/complete파일을 uploadUrl로 올린 뒤 호출해주세요.
본문 없이 호출하며 성공하면 파일이 active 상태가 돼요.
다운로드 URL 발급
/v1/storage/files/{id}/download-url다운로드 URL은 호출할 때마다 새로 발급돼요.
워크플로우에 전달할 때는 호출 직전에 받아 params로 넘겨주세요.
경로 파라미터
idstring · uuid필수다운로드할 파일 ID예요.
응답
성공하면 HTTP 200과 아래 필드를 돌려줘요.
downloadUrlstring · URL파일을 내려받을 사전 서명 URL이에요.
expiresInSecondsinteger다운로드 URL의 유효 시간(초)이에요.
오류
id가 UUID 형식이 아니에요.Validation failed (uuid is expected)read 권한이 없어요.Token lacks 'read' on binding <bindingId>File not found공통 오류는 에러 코드에서 확인해주세요.
파일 정보 조회
/v1/storage/files/{id}토큰이 접근할 수 있는 binding 범위 안에서 파일 메타데이터를 조회해요.
파일 ID는 UUID 형식이어야 해요.
파일 목록 조회
/v1/storage/files응답은 파일 메타데이터 배열이며 최대 200건이에요.
bindingId 또는 status로 결과를 좁힐 수 있어요.
파일 삭제
/v1/storage/files/{id}파일을 삭제해요.
릴리스가 참조 중인 파일은 App Deploy에서 릴리스를 먼저 회수해야 삭제할 수 있어요.
경로 파라미터
idstring · uuid필수삭제할 파일 ID예요.
응답
성공하면 HTTP 204로 응답하고 본문은 없어요.
오류
id가 UUID 형식이 아니에요.Validation failed (uuid is expected)delete 권한이 없어요.Token lacks 'delete' on binding <bindingId>File not found공통 오류는 에러 코드에서 확인해주세요.
파일 객체
idstring · uuid파일 ID예요.
bindingIdstring · uuid파일이 저장된 binding ID예요.
filenamestringnull 가능원본 파일명이에요.
contentTypestringnull 가능파일의 MIME 타입이에요.
sizeintegernull 가능파일 크기(바이트)예요.
statusstring현재 파일 상태예요.
pendingactivedeletingdeleteddelete_failedcleanupRulestring파일 정리 규칙이에요.
ttlon_job_endpersistentexpiresAttimestampnull 가능파일 만료 시각이에요.
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 권한 범위에서만 파일 메타데이터를 조회할 수 있어요.