API 레퍼런스
Deplite 공개 REST API의 경로, 인증 방식, 요청과 응답을 안내해요.
공개 API는 외부 시스템, CI, 자체 스크립트와 Agent에서 호출할 수 있어요.
API Token으로 워크플로우 실행·잡 조회·파일 저장소·파일 릴리스 API를 호출할 수 있어요.
App Deploy 대시보드 API는 로그인 세션으로 호출하고, Agent 배포 API는 Agent 서명으로 호출해요.
https://api.deplite.io인증API Token · Agent 서명 · 대시보드 세션스코프agent · workflow · storage · release인증 방식
| 방식 | 인증 | 용도 |
|---|---|---|
| API Token | Authorization: Bearer dpl_... | 외부 시스템·CI·자동화 스크립트 |
| Agent 서명 | X-Agent-Id, X-Timestamp, X-Nonce, X-Signature | Agent와 Server 사이의 요청 |
| 대시보드 세션 | 로그인 세션(JWT)과 조직 role | App Deploy의 조직 앱·릴리스·기기 관리 |
API Token은 실행·파일 저장소·앱 릴리스 권한을 grant로 지정해 발급받아요.
평문 토큰은 발급 시점에 한 번만 보이고 이후에는 복원할 수 없어요.
토큰은 안전한 비밀 저장소에 보관해주세요.
토큰 scope 종류
토큰의 scopes는 grant 배열이에요.
| type | 의미 |
|---|---|
agent | 지정한 Agent에서 호출이 허용된 워크플로우를 실행하는 권한 |
workflow | 지정한 Agent의 특정 워크플로우를 실행하는 권한 |
storage | managed 파일 저장소 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 Token |
| GET | /v1/agents | 토큰 grant가 허용하는 Agent 목록 조회 | API Token |
| GET | /v1/devices | `/v1/agents`와 같은 Agent 목록을 반환하는 alias | API Token |
| GET | /v1/workflows | 토큰 grant가 허용하는 워크플로우와 입력 스키마 조회 | API Token |
파일 저장소
| 메서드 | 경로 | 설명 | 인증 · 권한 |
|---|---|---|---|
| POST | /v1/storage/files/presign-upload | 파일 업로드용 사전 서명 URL 발급 | API Token |
| POST | /v1/storage/files/{id}/complete | 파일 업로드가 끝났음을 알리고 활성화 | API Token |
| GET | /v1/storage/files/{id}/download-url | 파일 다운로드용 사전 서명 URL 발급 | API Token |
| GET | /v1/storage/files/{id} | 파일 메타데이터 한 건 조회 | API Token |
| GET | /v1/storage/files | 허용된 binding의 파일 목록 조회 (최대 200건) | API Token |
| DELETE | /v1/storage/files/{id} | 파일을 삭제 처리하고 본문 없이 응답 | API Token |
잡 조회
| 메서드 | 경로 | 설명 | 인증 · 권한 |
|---|---|---|---|
| GET | /v1/jobs/{jobId} | 같은 토큰으로 생성한 Job의 상태와 결과 조회 | API Token |
| GET | /v1/jobs/{jobId}/logs | Job 로그를 seq 커서로 이어서 조회 | API Token |
파일 릴리스 (API Token)
| 메서드 | 경로 | 설명 | 인증 · 권한 |
|---|---|---|---|
| POST | /v1/apps/{app}/releases | 파일을 참조하는 draft 릴리스 생성 | API Token |
| GET | /v1/apps/{app}/releases/{releaseId} | 앱의 파일 릴리스 정보 조회 | API Token |
| POST | /v1/apps/{app}/releases/{releaseId}/publish | draft 파일 릴리스를 게시 | API Token |
| POST | /v1/apps/{app}/releases/{releaseId}/yank | 게시 파일 릴리스를 회수 | API Token |
App Deploy
워크플로우 호출
| 메서드 | 경로 | 설명 | 인증 · 권한 |
|---|---|---|---|
| GET | /v1/run/{agentName}/{workflowName} | 호출 허용 정보와 입력 스키마 조회 | API Token |
| POST | /v1/run/{agentName}/{workflowName} | 이름으로 허용된 워크플로우 실행 | API Token |
워크플로우 호출
이름 기반 실행 API는 POST /v1/run/{agentName}/{workflowName}이에요.
Agent와 워크플로우 이름을 경로에 넣고 Authorization: Bearer dpl_...로 인증해주세요.
요청 필드, 대기 동작, 응답, 오류와 예시는 워크플로우 호출에서 확인해주세요.
Job 상태와 파일 릴리스
비동기 실행 응답의 jobId를 같은 실행 토큰으로 조회하면 상태와 로그를 확인할 수 있어요.
요청 필드와 커서 기반 로그 조회는 잡 조회 API를 참고해주세요.
파일 릴리스 API는 release grant를 사용하고 파일 binding의 storage 권한도 확인해요.
앱별 권한, 요청 필드와 릴리스 흐름은 App Deploy API에서 확인해주세요.