관리형 Postgres API

인증

모든 요청은 Authorization: Bearer <api-key> 헤더 필수. API key는 콘솔 /api-keys 페이지에서 발급해요. (CLI도 같은 키 사용: ~/.onpod/config.yaml)

Base URL

https://api.onpod.ai

모든 path 앞에 /v1 가 붙어요. Content-Type 은 application/json.

리소스 모델

• DB instance — Postgres 한 대. id (UUID) 와 slug (영소문자·숫자·하이픈) 양쪽으로 접근. 공개 호스트 {slug}.db.onpod.ai.
• Backup — base / wal / snapshot 3종. 매분 WAL push + 매일 base + 사용자 즉시 snapshot.

POST /v1/databases — 만들기

새 DB 인스턴스 생성. 응답에 비밀번호이 1회만 노출돼요.

요청 본문

{
  "name": "myapp-db",
  "slug": "myapp-db",
  "engine": "postgres",
  "version": "17",
  "size": "basic",
  "storage_gb": 50,
  "pitr_retention_days": 7
}

• name (required) — 영소문자·숫자·하이픈, 3-40자
• slug (optional) — 비우면 name과 동일
• engine — postgres (only)
• version — 16 또는 17 (default)
• size — dev / basic / pro / business
• storage_gb — 정수, default = size 별 (10/50/100/500)
• pitr_retention_days — 1-35, default 7

응답 (201)

{
  "id": "01HXY...",
  "name": "myapp-db",
  "slug": "myapp-db",
  "state": "creating",
  "public_host": "myapp-db.db.onpod.ai",
  "internal_host": "myapp-db.db.onpod.local",
  "port": 5432,
  "password": "JR4QO7...",                  // 1회만!
  "superuser_password": "K2P5X...",         // 1회만!
  "database_url": "postgres://app_user:[email protected]:5432/postgres?sslmode=require",
  "database_url_public": "postgres://app_user:[email protected]:5432/postgres?sslmode=require"
}

curl 예시

curl -X POST https://api.onpod.ai/v1/databases \
  -H "Authorization: Bearer $ONPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"myapp-db","size":"basic","version":"17"}'

GET /v1/databases — 목록

내 모든 DB 인스턴스 (removed 제외). 응답 = 배열.

curl https://api.onpod.ai/v1/databases \
  -H "Authorization: Bearer $ONPOD_API_KEY"

GET /v1/databases/{id} — 상세

id 또는 slug 양쪽 OK. 응답에 최근 백업 20개 포함.

curl https://api.onpod.ai/v1/databases/myapp-db \
  -H "Authorization: Bearer $ONPOD_API_KEY"

DELETE /v1/databases/{id} — 삭제 (7일 grace)

soft delete. 7일 안에는 POST /restore 로 복구 가능. 7일 지나면 백업까지 영구 삭제.

curl -X DELETE https://api.onpod.ai/v1/databases/myapp-db \
  -H "Authorization: Bearer $ONPOD_API_KEY"

POST /v1/databases/{id}/rotate-password — 비밀번호 재발급

새 비밀번호 발급 + 옛 비밀번호 즉시 무효. --attach-db 로 연결된 Onpod 앱 들은 rolling restart로 자동 갱신. 응답에 새 비밀번호이 1회만 노출.

curl -X POST https://api.onpod.ai/v1/databases/myapp-db/rotate-password \
  -H "Authorization: Bearer $ONPOD_API_KEY"

POST /v1/databases/{id}/backup — 즉시 snapshot

curl -X POST https://api.onpod.ai/v1/databases/myapp-db/backup \
  -H "Authorization: Bearer $ONPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"v1.2 release 전"}'

응답 = command_id (비동기). 보통 1-5분.

POST /v1/databases/{id}/restore — PITR (준비 중)

자동 시점 복구는 아직 준비 중이라 501 restore_not_ready 를 돌려줘요. 백업(매일 스냅샷 + 매분 WAL)은 계속 안전하게 보관되고 있으니, 복구가 필요하면 [email protected]로 요청해 주세요.

POST /v1/databases/{id}/stop · /start

Dev 플랜만 지원. 안 쓸 땐 잠시 멈춰두세요 — 새 접속만 차단되고 데이터는 그대로 보존돼요. 다시 켜면 기다림 없이 바로 연결돼요. Basic 이상은 항상 켜져 있어요.

curl -X POST https://api.onpod.ai/v1/databases/myapp-db/stop \
  -H "Authorization: Bearer $ONPOD_API_KEY"
# ~30s cold start 후 start 가능
curl -X POST https://api.onpod.ai/v1/databases/myapp-db/start \
  -H "Authorization: Bearer $ONPOD_API_KEY"

PATCH /v1/databases/{id}/allowlist — IP 허용 목록

curl -X PATCH https://api.onpod.ai/v1/databases/myapp-db/allowlist \
  -H "Authorization: Bearer $ONPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowlist":[{"cidr":"1.2.3.0/24","label":"office"},{"cidr":"4.5.6.7/32","label":"home"}]}'

빈 배열 ([]) = 모든 IP 허용 (Supabase default와 동일). 내 Onpod 앱은 항상 허용.

에러 코드

• 400 bad_json — JSON 파싱 실패
• 400 bad_slug — slug 규칙 위반 (영소문자·숫자·하이픈, 3-40자)
• 400 bad_size — size 값 잘못
• 400 bad_version — version 16/17 아님
• 400 bad_time — restore to 가 RFC3339 아님
• 400 out_of_retention — restore 시점이 보존 기간 밖
• 400 future_time — restore 시점이 미래
• 400 stop_not_supported — basic 이상에 stop 시도
• 400 not_running — 켜져 있을 때만 가능한 작업 (backup·stop)
• 400 not_stopped — 멈춰 있을 때만 가능 (start)
• 401 auth_required — API key 누락 또는 무효
• 404 not_found — 그 id/slug의 DB 없음 (다른 사용자 소유일 수도)
• 409 slug_taken — 이미 쓰이는 slug
• 503 provision_failed — 인프라 확보 실패 (capacity 또는 quota)

비동기 패턴

backup·restore·stop·start·allowlist는 모두 202 Accepted +command_id 반환 후 비동기로 진행. 진행 상황은 GET /v1/databases/{id} 의 state 필드 polling.

• creating → running (1-2분)
• running → paused (stop, 즉시)
• paused → running (start, 즉시)

Rate limit

사용자당 100 RPS. 초과 시 429 too_many_requests + Retry-After 헤더.

AI 에이전트를 위한 한 줄 부트스트랩

Claude Code · Codex 첫 메시지에 「이 페이지 URL + API key 1개」 만 주면 모든 CRUD 자율 운영 가능해요. 추천 시스템 프롬프트:

너는 Onpod 관리형 Postgres를 운영하는 에이전트야.
- API key: $ONPOD_API_KEY (HTTP 헤더 Authorization: Bearer $ONPOD_API_KEY)
- Base URL: https://api.onpod.ai
- 문서: https://console.onpod.ai/docs/api/db (이 페이지)
- DB 만들 때 비밀번호은 응답에서 1회만 노출 — 즉시 안전한 곳에 저장하거나 다음 단계 명령에 바로 써.
- 백업·복구는 비동기. command_id 받고 GET /v1/databases/{slug} polling으로 state 추적.
- DB 삭제 7일 grace — 사용자 의도가 확실치 않으면 먼저 확인.