App Deploy
App Deploy는 Deplite가 배포 서버 역할을 맡아 아티팩트를 managed storage에 보관하고 기기가 온라인이 될 때 최신 릴리스로 수렴하게 해요.
키오스크처럼 항상 켜져 있지 않은 기기에 배포할 때 참고해주세요.
설치·재시작 같은 적용 로직은 여러분의 로컬 워크플로우(예: app-update)가 담당해요.
서버는 아티팩트를 파라미터로 넣어 기기의 로컬 워크플로우를 실행하는 데까지 관여하고, 적용 방법은 워크플로우가 정해요.
https://api.deplite.io인증API Token · 대시보드 세션 · Agent 서명스코프release · storage · 조직 role · Agent인증과 경로
App Deploy API는 API Token 파일 릴리스 관리, 대시보드 관리, Agent 배포 세 부류예요.
| 부류 | 인증 | 경로 |
|---|---|---|
| API Token 파일 릴리스 | Bearer 토큰과 앱별 release grant | /v1/apps/{app}/releases/... |
| 대시보드 관리 | 로그인 세션(JWT)과 조직 role | /orgs/{orgId}/apps/... |
| Agent 배포 | Agent 서명 (X-Agent-Id, X-Timestamp, X-Nonce, X-Signature) | /v1/agent/deploy/... |
대시보드 API는 앱·릴리스·기기를 만들고 운영하는 콘솔 API예요.
조직 role로 인가하며 앱 삭제처럼 되돌리기 어려운 작업은 owner만 할 수 있어요.
Agent API는 https://api.deplite.io를 Base URL로 사용해요.
앱 (Apps)
앱은 조직 안에서 고유한 slug와 업데이트 workflow 이름, 기기가 구독할 기본 channel을 가져요.
대시보드 API는 세션과 조직 role로 인증해요.
앱 생성
/orgs/{orgId}/apps앱 이름, 조직 안에서 고유한 slug, 업데이트를 적용할 로컬 workflow 이름을 지정해주세요.
기본 channel을 생략하면 stable을 사용해요.
경로 파라미터
orgIdstring · uuid필수앱을 만들 조직 ID예요.
요청 본문
namestring필수앱 이름이에요.
slugstring필수조직 안에서 앱을 구분하는 고유 slug예요.
updateWorkflowNamestring필수업데이트를 적용할 로컬 워크플로우 이름이에요.
defaultChannelstring기기가 구독할 기본 채널이에요.
stable응답
성공하면 HTTP 201과 아래 필드를 돌려줘요.
오류
공통 오류는 에러 코드에서 확인해주세요.
릴리스 (Releases)
릴리스는 아티팩트 파일을 가리키는 배포 단위예요.
목록은 channel과 status로 좁힐 수 있고, 게시와 회수는 조직 role이 있는 사용자만 호출할 수 있어요.
릴리스는 아티팩트(스토리지 파일)를 가리키는 배포 단위예요.
게시(publish)하면 해당 channel의 기기들이 다시 평가되어 최신 릴리스로 수렴하기 시작해요.
회수(yank)하면 대상 channel의 desired가 직전 게시본으로 내려가고 기기들이 그쪽으로 수렴해요.
회수는 롤백 수단이므로 로컬 workflow가 다운그레이드를 감당할 수 있는지 확인해주세요.
게시된 릴리스는 불변이에요.
순서는 version 문자열이 아니라 앱 단위로 증가하는 sequence로 판단해요.
mandatory 릴리스는 최소 버전 마커가 되어 그보다 낮은 기기는 업데이트를 미룰 수 없어요.
optional 릴리스는 최신으로 수렴하되 기기가 미룰 수 있어요.
릴리스용 아티팩트는 cleanupRule: 'persistent'로 업로드해주세요.
릴리스가 참조 중인 파일의 삭제는 409로 거절돼요.
파일을 삭제하려면 해당 릴리스를 먼저 회수(yank)해주세요.
API Token으로 릴리스 관리
API Token은 앱에 grant된 권한으로 파일 릴리스를 생성하고 조회·게시·회수해요.
앱 경로에는 slug 또는 UUID를 넣을 수 있어요.
릴리스 grant에는 대상 앱과 create, publish, yank 권한을 지정해주세요.
아티팩트 업로드에는 storage write, 릴리스 생성 시 파일 binding 확인에는 storage read 권한이 필요해요.
GET은 세 release 권한 중 하나가 있으면 호출할 수 있고, 게시와 회수는 각각 해당 권한이 필요해요.
API Token 생성 경로는 파일 릴리스예요. 릴리스용 파일은 cleanupRule: 'persistent'로 업로드해주세요.
API Token으로 파일 릴리스 생성
/v1/apps/{app}/releases먼저 파일 저장소 API로 아티팩트를 업로드하고 완료 처리해주세요.
파일 ID와 버전을 보내 draft 릴리스를 만들어요.
channel은 생략하면 stable, updatePolicy는 생략하면 optional이에요.
경로 파라미터
appstring필수조직 안 앱의 slug 또는 UUID예요.
요청 본문
versionstring필수릴리스 버전 label이에요.
channelstring릴리스 채널이에요.
stablefileIdstring · uuid필수managed storage에 업로드한 아티팩트 파일 ID예요.
updatePolicystring기기가 업데이트를 미룰 수 있는지 정해요.
optionalmandatory기본값 optionalchecksumSha256string아티팩트의 SHA-256 체크섬이에요.
signaturestring아티팩트 서명이에요.
notesstring릴리스 설명이에요.
workflowNameOverridestring앱의 기본 업데이트 workflow를 대체할 이름이에요.
응답
성공하면 HTTP 201과 릴리스 객체를 돌려줘요.
오류
invalid_requesttoken_missingtoken_invalidtoken_not_authorizedcreate 또는 아티팩트 binding의 storage read 권한이 없어요.app_not_foundfile_not_foundrelease_existsrelease_conflict공통 오류는 에러 코드에서 확인해주세요.
API Token으로 릴리스 조회
/v1/apps/{app}/releases/{releaseId}앱 경로와 릴리스 ID로 릴리스 객체를 조회해요.
조회 응답의 필드 설명은 아래 릴리스 객체를 참고해주세요.
경로 파라미터
appstring필수조직 안 앱의 slug 또는 UUID예요.
releaseIdstring · uuid필수조회할 릴리스 ID예요.
응답
성공하면 HTTP 200과 릴리스 객체를 돌려줘요.
오류
token_missingtoken_invalidtoken_not_authorizedapp_not_foundrelease_not_found공통 오류는 에러 코드에서 확인해주세요.
API Token으로 릴리스 게시
/v1/apps/{app}/releases/{releaseId}/publishdraft 릴리스를 게시하고 게시된 릴리스 객체를 받아요.
해당 앱에 publish 권한이 있는 토큰을 사용해주세요.
경로 파라미터
appstring필수조직 안 앱의 slug 또는 UUID예요.
releaseIdstring · uuid필수게시할 릴리스 ID예요.
응답
성공하면 HTTP 201과 릴리스 객체를 돌려줘요.
오류
invalid_requestsignature_requiredtoken_missingtoken_invalidtoken_not_authorizedpublish 권한이 없어요.app_not_foundrelease_not_found공통 오류는 에러 코드에서 확인해주세요.
API Token으로 릴리스 회수
/v1/apps/{app}/releases/{releaseId}/yank게시된 릴리스를 회수하고 변경된 릴리스 객체를 받아요.
회수 뒤 기기 desired는 직전 게시본으로 내려가요.
해당 앱에 yank 권한이 있는 토큰을 사용해주세요.
경로 파라미터
appstring필수조직 안 앱의 slug 또는 UUID예요.
releaseIdstring · uuid필수회수할 릴리스 ID예요.
응답
성공하면 HTTP 201과 릴리스 객체를 돌려줘요.
오류
invalid_requesttoken_missingtoken_invalidtoken_not_authorizedyank 권한이 없어요.app_not_foundrelease_not_found공통 오류는 에러 코드에서 확인해주세요.
릴리스 응답 객체
idstring · uuid릴리스 ID예요.
applicationIdstring · uuid앱 ID예요.
sequenceinteger앱 안에서 증가하는 릴리스 순서예요.
versionstring릴리스 버전 label이에요.
channelstring릴리스 채널이에요.
kindstring릴리스 종류예요.
fileimagefileIdstring · uuidnull 가능파일 릴리스의 아티팩트 ID예요.
imageRepostringnull 가능이미지 릴리스의 저장소예요.
imageDigeststringnull 가능이미지 릴리스의 digest예요.
checksumSha256stringnull 가능아티팩트 SHA-256 체크섬이에요.
signaturestringnull 가능보관하는 아티팩트 서명이에요.
sizeBytesintegernull 가능아티팩트 크기(바이트)예요.
updatePolicystring업데이트 정책이에요.
optionalmandatoryworkflowNameOverridestringnull 가능대체 업데이트 workflow 이름이에요.
notesstringnull 가능릴리스 설명이에요.
statusstring릴리스 상태예요.
draftpublishedyankedcreatedAttimestamp생성 시각이에요.
publishedAttimestampnull 가능게시 시각이에요.
yankedAttimestampnull 가능회수 시각이에요.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"applicationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"sequence": 2,
"version": "1.2.0",
"channel": "stable",
"kind": "file",
"fileId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"imageRepo": null,
"imageDigest": null,
"checksumSha256": null,
"signature": null,
"sizeBytes": 28473921,
"updatePolicy": "optional",
"workflowNameOverride": null,
"notes": null,
"status": "published",
"createdAt": "2026-10-28T12:00:00.000Z",
"publishedAt": "2026-10-28T12:10:00.000Z",
"yankedAt": null
}기기 (Devices)
기기는 앱과 Agent를 연결하는 binding이에요.
binding에는 관측한 설치 상태와 목표 릴리스 상태가 담겨요.
기기를 연결할 때 channel을 생략하면 앱의 기본 channel을 따라요.
reconcile은 기기의 desired를 다시 계산하고 필요하면 업데이트 job을 다시 발생시키는 수동 재평가예요.
기기 바인딩
/orgs/{orgId}/apps/{appId}/devices앱에 연결할 Agent ID 목록을 보내요.
Agent ID와 앱 ID는 UUID 형식이어야 해요.
{ "agentIds": ["550e8400-e29b-41d4-a716-446655440000", "6ba7b810-9dad-11d1-80b4-00c04fd430c8"], "channel": "stable" }경로 파라미터
orgIdstring · uuid필수앱이 속한 조직 ID예요.
appIdstring · uuid필수Agent를 연결할 앱 ID예요.
요청 본문
agentIdsstring[] · uuid필수앱에 연결할 Agent ID 목록이에요.
channelstring구독할 채널이에요.
생략하면 앱의 기본 채널을 따라요.
응답
성공하면 HTTP 201과 아래 필드를 돌려줘요.
기기 채널 변경
/orgs/{orgId}/apps/{appId}/devices/{deviceId}기기 binding이 구독할 channel을 바꿔요.
{ "channel": "beta" }경로 파라미터
orgIdstring · uuid필수조직 ID예요.
appIdstring · uuid필수앱 ID예요.
deviceIdstring · uuid필수기기 바인딩 ID예요.
요청 본문
channelstring필수기기가 구독할 채널이에요.
응답
성공하면 HTTP 200과 아래 필드를 돌려줘요.
OTA 업데이트 job은 앱과 Agent의 binding, 게시된 릴리스에 따라 진행돼요.
진행 중인 job ID는 기기의 activeJobId로 확인할 수 있어요.
Agent 배포 엔드포인트
Agent가 배포 상태를 조회하고 설치 상태를 보고할 때 사용해요.
Agent 서명으로 인증해주세요.
Agent는 부팅·연결 시 desired를 조회하고 SSE 연결 중 서버 push를 받으면 다시 확인해요.
안전망 폴링 최소 주기는 Free 플랜 60분, Pro 플랜 15분이에요.
더 자주 조회하면 429와 Retry-After를 받고 본문에 pollIntervalSeconds와 retryAfterSeconds가 포함돼요.
유효 폴링 주기는 heartbeat와 desired 응답의 pollIntervalSeconds를 따라요.
desired 조회
/v1/agent/deploy/desiredAgent가 담당하는 각 앱의 서명된 desired 매니페스트를 받아요.
매니페스트의 current는 서버가 관측한 설치본이고 desired는 기기가 수렴할 목표 릴리스예요.
signature는 payload를 canonical JSON으로 직렬화한 값에 대한 서명이에요.
Agent는 등록(enroll) 때 받은 서버 공개키(serverPublicKey)로 서명을 검증해주세요.
download_url은 매번 새로 발급되고 download_expires_in 초 뒤 만료돼요.
이 매니페스트는 서버가 전달한 job의 pull 폴백이자 Agent 자체 점검용이에요.
응답
성공하면 HTTP 200과 아래 필드를 돌려줘요.
appsarrayAgent에 바인딩된 앱별 signed manifest예요.
pollIntervalSecondsinteger다음 안전망 조회까지의 최소 간격이에요.
오류
응답에
Retry-After, pollIntervalSeconds, retryAfterSeconds가 포함돼요.공통 오류는 에러 코드에서 확인해주세요.
설치 상태 보고
/v1/agent/deploy/reportAgent가 관측한 현재 설치 상태를 보고해요.
보고를 받으면 서버가 곧바로 다시 평가하므로 Agent 최초 연결 시 기준선을 맞추는 용도로도 쓸 수 있어요.
{
"applicationId": "550e8400-e29b-41d4-a716-446655440000",
"currentVersion": "1.1.0",
"currentReleaseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"currentSequence": 1,
"state": "idle",
"error": null
}요청 본문
applicationIdstring · uuid필수보고 대상 앱 ID예요.
currentVersionstring현재 설치된 버전 라벨이에요.
currentReleaseIdstring · uuid현재 설치된 릴리스 ID예요.
currentSequenceinteger현재 설치된 릴리스 순서 값이에요.
statestring기기가 관측한 적용 상태예요.
idlependingupdatingfailederrorstring적용 중 발생한 오류예요.
응답
성공하면 HTTP 201과 아래 필드를 돌려줘요.
update job의 deploy 파라미터
OTA 업데이트가 발생하면 Agent는 기존 SSE deploy 이벤트를 받아요.
그 이벤트의 params는 다음 필드를 가져요.
| 필드 | 타입 | 설명 |
|---|---|---|
artifact | object | 내려받을 아티팩트 참조예요. downloadUrl은 전송할 때마다 새로 주입돼요 (입력 방향 FileRef). |
release_id | string | 적용할 릴리스 ID예요. |
version | string | 릴리스 버전 label이에요. |
channel | string | 릴리스 channel이에요. |
sequence | integer | 릴리스 순서 값이에요. |
forced | boolean | 강제 업데이트 여부예요. 판단은 서버가 하고 집행(앱 차단 등)은 Agent가 해요. |
checksum_sha256 | string | 내려받은 파일을 검증할 체크섬이에요. |
forced 여부와 무관하게 아티팩트를 받아 적용하는 방법은 로컬 workflow가 정해요.
checksum_sha256으로 내려받은 파일을 검증한 뒤 적용해주세요.
워크플로우 결과로 내보내는 FileRef는 이와 형태가 달라요.
출력 방향 FileRef에는 downloadUrl이 없고 id로 다운로드 URL을 따로 받아야 해요. $file 마커로 파일 첨부하기를 참고해주세요.