REST API 레퍼런스
REST API는 POST 요청으로 에러 메시지 · 실행 로그 · 출력값 · 커스텀 메트릭 을 함께 전송할 수 있는 고급 연동 방식입니다.
- 베이스 URL:
https://api.cronbark.com - 인증: URL 경로 안의 토큰 (
/api/v1/health/{token}/...) — 별도 헤더 불필요 - Content-Type:
application/json
API 토큰은 Cronjob 생성과 동시에 자동으로 1개 발급됩니다. 생성 직후의 응답(POST /api/v1/cronjobs)에 포함된 tokens[0].token 값을 그대로 쓰면 됩니다. 추가 토큰이 필요하면 POST /api/v1/cronjobs/{id}/tokens 로 새 토큰을 더 만들 수 있습니다.
엔드포인트 요약
| Method | Path | 설명 |
|---|---|---|
| POST | /api/v1/health/{token}/start | 실행 시작 알림 |
| POST | /api/v1/health/{token}/success | 성공 완료 (output, metrics 첨부 가능) |
| POST | /api/v1/health/{token}/complete | success 별칭 (Cronitor 호환) |
| POST | /api/v1/health/{token}/fail | 실패 알림 (error_message, log_content, output 첨부 가능) |
| POST | /api/v1/health/{token}/tick | 하트비트 — start 없이 즉시 성공 기록 |
| POST | /api/v1/health/{token}/log | 실행 중 로그 추가 (장기 실행 잡용) |
POST /health/{token}/start
실행 시작을 기록합니다. Cronjob을 RUNNING 상태로 바꾸고 새 Execution 레코드를 만듭니다.
Body (선택)
{
"execution_id": "550e8400-e29b-41d4-a716-446655440000"
}execution_id는 UUID 형식이며, 생략 시 서버가 자동 생성합니다.
예제
curl -X POST https://api.cronbark.com/api/v1/health/abc123/start \
-H "Content-Type: application/json" \
-d '{}'POST /health/{token}/success
실행 성공을 기록합니다. output과 metrics를 첨부할 수 있습니다.
Body (선택)
{
"output": "Backup completed: 1,234 rows",
"metrics": {
"rows_processed": 1234,
"duration_sec": 45.2
}
}예제
curl -X POST https://api.cronbark.com/api/v1/health/abc123/success \
-H "Content-Type: application/json" \
-d '{"output":"OK","metrics":{"rows":1234}}'POST /health/{token}/complete
success의 별칭입니다. Cronitor 호환용으로 제공되며 동작은 success와 동일합니다 (output·metrics 첨부 가능).
curl -X POST https://api.cronbark.com/api/v1/health/abc123/complete \
-H "Content-Type: application/json" \
-d '{"output":"OK"}'POST /health/{token}/fail
실행 실패를 기록합니다. 에러 메시지와 상세 로그를 함께 보냅니다.
Body
{
"error_message": "DB connection refused",
"log_content": "Traceback (most recent call last):\n File \"backup.py\", line 42, ...",
"output": "stdout/stderr 내용..."
}error_message(선택) — 실패 원인 요약log_content(선택) — 상세 로그 (최대 20MB, 플랜별 보관 기간 적용)output(선택) — stdout/stderr 출력 (최대 1MB)
log_content는 최대 20MB까지 저장됩니다. 플랜별 보관 기간(Free 30일 / Team 90일 / Business 180일 / Enterprise 1년+) 경과 후 자동 삭제됩니다.
예제
curl -X POST https://api.cronbark.com/api/v1/health/abc123/fail \
-H "Content-Type: application/json" \
-d '{
"error_message": "Connection refused",
"log_content": "Full stack trace here..."
}'POST /health/{token}/tick
start 이벤트 없이 즉시 성공으로 기록합니다. 주기적 하트비트용.
curl -X POST https://api.cronbark.com/api/v1/health/abc123/tick별도 body가 필요 없습니다.
POST /health/{token}/log
장기 실행되는 잡에서 중간 로그를 누적 전송합니다. 최신 RUNNING Execution에 append됩니다.
Body
{
"output": "[2026-04-14 10:32:15] Processing batch 3/10...",
"level": "INFO"
}output(필수) — 로그 내용 (최대 1MB)level(선택, 기본INFO) — 로그 레벨.INFO/WARNING/ERROR/DEBUG
curl -X POST https://api.cronbark.com/api/v1/health/abc123/log \
-H "Content-Type: application/json" \
-d '{"output":"batch 3/10 완료","level":"INFO"}'응답 형식
모든 엔드포인트는 아래와 같은 JSON을 반환합니다:
{
"status": "ok",
"message": "실행이 시작되었습니다.",
"execution_id": "550e8400-e29b-41d4-a716-446655440000"
}execution_id는 UUID 형식입니다.
에러 코드
| HTTP | 상황 |
|---|---|
| 200 | 정상 접수 |
| 400 | 잘못된 요청 body |
| 401 | 토큰이 유효하지 않음 |
| 404 | 토큰이 삭제된 Cronjob에 연결됨 |
| 429 | 레이트 리밋 초과 |
| 5xx | 서버 오류 — SDK는 자동 재시도 |
완전한 Bash 예제
#!/bin/bash
set -e
TOKEN="abc123"
BASE="https://api.cronbark.com/api/v1/health/$TOKEN"
# 1) 시작
curl -s -X POST "$BASE/start" -H "Content-Type: application/json" -d '{}'
# 2) 작업 수행 (stdout/stderr 캡처)
LOG=$(./my_script.sh 2>&1)
EXIT=$?
# 3) 결과 보고
if [ $EXIT -eq 0 ]; then
curl -s -X POST "$BASE/success" \
-H "Content-Type: application/json" \
-d "{\"output\":$(echo "$LOG" | jq -Rs .)}"
else
curl -s -X POST "$BASE/fail" \
-H "Content-Type: application/json" \
-d "{\"error_message\":\"script exited $EXIT\",\"log_content\":$(echo "$LOG" | jq -Rs .)}"
fi다음 단계
- Python SDK — POST API를 깔끔하게 감싸는 파이썬 래퍼
- 알림 조건 — 실패/지연/타임아웃 알림 규칙 설정