Skip to Content
문서API 레퍼런스개요

API 레퍼런스

Deplite 공개 REST API의 경로, 인증 방식, 요청과 응답을 안내해요.
공개 API는 외부 시스템, CI, 자체 스크립트와 Agent에서 호출할 수 있어요.
API Token으로 워크플로우 실행·잡 조회·파일 저장소·파일 릴리스 API를 호출할 수 있어요.
App Deploy 대시보드 API는 로그인 세션으로 호출하고, Agent 배포 API는 Agent 서명으로 호출해요.

Base URLhttps://api.deplite.io인증API Token · Agent 서명 · 대시보드 세션스코프agent · workflow · storage · release

인증 방식

방식인증용도
API TokenAuthorization: Bearer dpl_...외부 시스템·CI·자동화 스크립트
Agent 서명X-Agent-Id, X-Timestamp, X-Nonce, X-SignatureAgent와 Server 사이의 요청
대시보드 세션로그인 세션(JWT)과 조직 roleApp Deploy의 조직 앱·릴리스·기기 관리

API Token은 실행·파일 저장소·앱 릴리스 권한을 grant로 지정해 발급받아요.
평문 토큰은 발급 시점에 한 번만 보이고 이후에는 복원할 수 없어요.
토큰은 안전한 비밀 저장소에 보관해주세요.

토큰 scope 종류

토큰의 scopes는 grant 배열이에요.

type의미
agent지정한 Agent에서 호출이 허용된 워크플로우를 실행하는 권한
workflow지정한 Agent의 특정 워크플로우를 실행하는 권한
storagemanaged 파일 저장소 binding에 접근하는 권한. bindingIds와 read·write·delete로 범위를 정해요
release지정한 앱의 파일 릴리스 생성·게시·회수 권한. appIds와 create·publish·yank로 범위를 정해요

Base URL과 경로 표기

Base URL은 https://api.deplite.io예요.
API 경로에는 버전과 전체 경로가 포함돼요. 예를 들어 /v1/storage/files/presign-upload, /v1/run/{agentName}/{workflowName}, /orgs/{orgId}/apps처럼 호출해주세요.
경로 파라미터는 {name} 표기로 나타내요.
SDK와 files-action의 base-url 옵션은 /v1까지 포함한 https://api.deplite.io/v1이 기본값이에요.

공통 오류 응답

워크플로우 호출은 code 필드를 포함한 응답을 사용해요.
다른 API는 Nest 기본 오류 형태인 statusCode, message, error를 사용해요.
상태별 코드와 엔드포인트는 에러 코드에서 확인해주세요.

HTTP일반적인 상황
400요청 형식 또는 필드 검증 실패
401인증 정보 누락 또는 무효
403토큰 scope·binding 권한 또는 조직 role 부족
404리소스 없음
409리소스 상태 또는 중복 요청 충돌
429호출 한도 또는 Agent 최소 폴링 간격 초과
500서버 오류

공통 레이트 리밋

워크플로우 실행 한도와 토큰 읽기 조회 한도는 서로 다른 규칙으로 적용돼요.
워크플로우 실행 한도는 워크플로우와 토큰에 각각 적용되고, token access 읽기 기본 한도는 토큰당 분당 60회예요.
Agent의 App Deploy desired 조회는 플랜의 최소 폴링 간격보다 자주 호출하면 429와 Retry-After를 돌려줘요.
각 규칙은 토큰 접근 범위, 워크플로우 호출, App Deploy에서 확인해주세요.

엔드포인트

토큰 접근 범위

메서드경로설명인증 · 권한
GET/v1/token현재 토큰의 scope와 제한 정보 조회API Tokenscope 무관
GET/v1/agents토큰 grant가 허용하는 Agent 목록 조회API Tokenscope 무관
GET/v1/devices`/v1/agents`와 같은 Agent 목록을 반환하는 aliasAPI Tokenscope 무관
GET/v1/workflows토큰 grant가 허용하는 워크플로우와 입력 스키마 조회API Tokenscope 무관

파일 저장소

메서드경로설명인증 · 권한
POST/v1/storage/files/presign-upload파일 업로드용 사전 서명 URL 발급API Tokenstorage · write
POST/v1/storage/files/{id}/complete파일 업로드가 끝났음을 알리고 활성화API Tokenstorage · write
GET/v1/storage/files/{id}/download-url파일 다운로드용 사전 서명 URL 발급API Tokenstorage · read
GET/v1/storage/files/{id}파일 메타데이터 한 건 조회API Tokenstorage · read
GET/v1/storage/files허용된 binding의 파일 목록 조회 (최대 200건)API Tokenstorage · read
DELETE/v1/storage/files/{id}파일을 삭제 처리하고 본문 없이 응답API Tokenstorage · delete

잡 조회

메서드경로설명인증 · 권한
GET/v1/jobs/{jobId}같은 토큰으로 생성한 Job의 상태와 결과 조회API Token워크플로우 실행 권한 · Job 생성 토큰
GET/v1/jobs/{jobId}/logsJob 로그를 seq 커서로 이어서 조회API Token워크플로우 실행 권한 · Job 생성 토큰

파일 릴리스 (API Token)

메서드경로설명인증 · 권한
POST/v1/apps/{app}/releases파일을 참조하는 draft 릴리스 생성API Tokenrelease · create + storage · read
GET/v1/apps/{app}/releases/{releaseId}앱의 파일 릴리스 정보 조회API Tokenrelease · create · publish · yank 중 하나
POST/v1/apps/{app}/releases/{releaseId}/publishdraft 파일 릴리스를 게시API Tokenrelease · publish
POST/v1/apps/{app}/releases/{releaseId}/yank게시 파일 릴리스를 회수API Tokenrelease · yank

App Deploy

메서드경로설명인증 · 권한
GET/orgs/{orgId}/apps조직의 앱 목록 조회대시보드 세션owner · member
POST/orgs/{orgId}/appsApp Deploy 앱 생성대시보드 세션owner · member
GET/orgs/{orgId}/apps/{appId}앱 상세 정보 조회대시보드 세션owner · member
PATCH/orgs/{orgId}/apps/{appId}앱 설정 수정대시보드 세션owner · member
DELETE/orgs/{orgId}/apps/{appId}앱 삭제대시보드 세션owner
GET/orgs/{orgId}/apps/{appId}/releases릴리스 목록 조회 (`channel`, `status` 필터)대시보드 세션owner · member
POST/orgs/{orgId}/apps/{appId}/releasesdraft 릴리스 생성대시보드 세션owner · member
GET/orgs/{orgId}/apps/{appId}/releases/{releaseId}릴리스 상세 정보 조회대시보드 세션owner · member
POST/orgs/{orgId}/apps/{appId}/releases/{releaseId}/publishdraft 릴리스를 게시대시보드 세션owner · member
POST/orgs/{orgId}/apps/{appId}/releases/{releaseId}/yank게시 릴리스를 회수대시보드 세션owner · member
GET/orgs/{orgId}/apps/{appId}/devices앱에 바인딩된 기기 목록 조회대시보드 세션owner · member
POST/orgs/{orgId}/apps/{appId}/devicesAgent를 앱에 바인딩대시보드 세션owner · member
PATCH/orgs/{orgId}/apps/{appId}/devices/{deviceId}기기 바인딩의 구독 채널 변경대시보드 세션owner · member
DELETE/orgs/{orgId}/apps/{appId}/devices/{deviceId}앱과 Agent의 연결 해제대시보드 세션owner · member
POST/orgs/{orgId}/apps/{appId}/devices/{deviceId}/reconcile기기의 desired 상태를 다시 계산대시보드 세션owner · member
GET/v1/agent/deploy/desiredAgent가 담당하는 앱의 서명된 desired 매니페스트 조회Agent 서명
POST/v1/agent/deploy/reportAgent가 관측한 앱 설치 상태 보고Agent 서명

워크플로우 호출

메서드경로설명인증 · 권한
GET/v1/run/{agentName}/{workflowName}호출 허용 정보와 입력 스키마 조회API Tokenworkflow 실행 권한
POST/v1/run/{agentName}/{workflowName}이름으로 허용된 워크플로우 실행API Tokenagent · workflow

워크플로우 호출

이름 기반 실행 API는 POST /v1/run/{agentName}/{workflowName}이에요.
Agent와 워크플로우 이름을 경로에 넣고 Authorization: Bearer dpl_...로 인증해주세요.
요청 필드, 대기 동작, 응답, 오류와 예시는 워크플로우 호출에서 확인해주세요.

Job 상태와 파일 릴리스

비동기 실행 응답의 jobId를 같은 실행 토큰으로 조회하면 상태와 로그를 확인할 수 있어요.
요청 필드와 커서 기반 로그 조회는 잡 조회 API를 참고해주세요.
파일 릴리스 API는 release grant를 사용하고 파일 binding의 storage 권한도 확인해요.
앱별 권한, 요청 필드와 릴리스 흐름은 App Deploy API에서 확인해주세요.

관련 문서

최종 수정 일자: