콘텐츠로 이동
Revka Revka
Docs
크론, 세션, 첨부 파일 API

크론, 세션, 첨부 파일 API

크론 작업 CRUD 및 실행 기록, 채팅 세션 관리, 파일 첨부 파일 업로드.

이 페이지에서는 Gateway REST API의 세 가지 관련 영역을 다룹니다. /api/cron에서의 작업 스케줄링, /api/sessions에서의 대시보드 채팅 세션 관리, 그리고 해당 세션에 대한 파일 첨부 파일 업로드입니다. 커스텀 대시보드를 구축하거나, HTTP를 통해 예약된 에이전트 작업을 자동화하거나, 커스텀 채팅 클라이언트를 게이트웨이에 연결할 때 이 엔드포인트를 사용하십시오.

아래의 모든 라우트에는 페어링 흐름에서 발급된 베어러 토큰이 필요합니다.

Authorization: Bearer <token>

게이트웨이는 표준 JSON 라우트에 64 KiB 본문 제한과 30초 타임아웃을 적용합니다(REVKA_GATEWAY_TIMEOUT_SECS 환경 변수로 재정의 가능). 첨부 파일 업로드 라우트의 본문 제한은 25 MiB로 높아집니다. API 전체에 대한 내용은 Gateway API 개요를 참조하십시오.

크론 작업

섹션 제목: “크론 작업”

크론 작업은 HTTP API를 통해 두 가지 실행 백엔드 중 하나를 사용합니다.

  • shell — 셸 명령을 실행합니다(보안 정책에 따라 유효성 검사).
  • agent — LLM 프롬프트를 실행하며, 선택적으로 출력을 채널로 전달합니다.

(세 번째 내부 타입인 workflow는 YAML 트리거로 관리되며 이 API를 통해 생성할 수 없습니다. 선언적 작업 및 스케줄러 설정을 참조하십시오.)

작업 목록 조회

섹션 제목: “작업 목록 조회”
GET /api/cron

마지막 실행 메타데이터와 마지막 출력(디스크에 16 KiB로 제한)을 포함하여 등록된 모든 작업을 반환합니다.

{ "jobs": [ { "id": "…", "job_type": "agent", "schedule": { … }, … } ] }

작업 생성

섹션 제목: “작업 생성”
POST /api/cron
Content-Type: application/json
{
  "schedule": "0 9 * * *",
  "job_type": "agent",
  "prompt": "Summarize overnight alerts and post to the team channel",
  "name": "Morning summary",
  "model": null,
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "#ops-alerts",
    "best_effort": true
  },
  "session_target": "isolated",
  "allowed_tools": null,
  "delete_after_run": false
}
필드타입필수 여부설명
schedulestring필수크론 표현식, 예: "0 9 * * *" (문자열 전용 — 아래 참조)
job_typestring선택"shell" 또는 "agent". prompt가 있는 경우 "agent"로 자동 추론
commandstringshell 필수실행할 셸 명령
promptstringagent 필수에이전트 턴으로 실행할 프롬프트
namestring선택사람이 읽을 수 있는 레이블
modelstring선택에이전트 작업에 대한 모델 재정의 (모든 프로바이더/모델 문자열)
deliveryobject선택채널 전달 설정 (아래 참조)
session_targetstring선택에이전트 작업에 대해 "isolated" (기본값) 또는 "main"
allowed_toolsstring[]선택에이전트 작업에서 사용 가능한 도구 제한. 생략하거나 null이면 모든 도구 허용
delete_after_runbool선택한 번 실행 후 자동 삭제 (at 스케줄의 기본값만 true이며, 이 엔드포인트에서는 생성 불가)

성공 시 생성된 작업을 반환합니다.

{ "status": "ok", "job": { "id": "…", … } }

delivery 객체는 mode ("none" 또는 "announce"), channel (telegram, discord, slack, mattermost, signal, matrix, qq), to (채널별 대상 — Slack 채널 이름, Discord/Telegram 채팅 ID, Matrix 룸 ID 등), best_effort (기본값 true. false로 설정하면 전달 실패 시 전체 실행이 error로 표시)를 지원합니다. 작업 출력은 전달 전에 자격 증명 유출 여부를 검사하고 필요 시 난독화됩니다. 에이전트 작업 및 전달을 참조하십시오.

session_target에는 "main" (공유 인터랙티브 세션에서 실행)과 "isolated" (새로운 빈 컨텍스트, 기본값)만 인식됩니다. 그 외 값은 isolated로 대체됩니다.

작업 수정

섹션 제목: “작업 수정”
PATCH /api/cron/{id}
Content-Type: application/json
{
  "name": "New label",
  "schedule": "0 8 * * *",
  "command": "echo updated",
  "enabled": true
}
필드타입설명
namestring새 레이블
schedulestring새 크론 표현식 (문자열 전용)
commandstring새 값. 에이전트 작업의 경우 프롬프트로 라우팅됨
promptstring에이전트 작업에서 command의 별칭
enabledbool작업 활성화 또는 비활성화

게이트웨이는 작업의 저장된 타입에 따라 수정된 텍스트를 명령(셸 작업) 또는 프롬프트(에이전트 작업)로 라우팅합니다. { "status": "ok", "job": { … } }를 반환합니다.

작업 삭제

섹션 제목: “작업 삭제”
DELETE /api/cron/{id}

작업을 영구적으로 제거하고 실행 기록도 함께 삭제합니다. { "status": "ok" }를 반환합니다.

실행 기록

섹션 제목: “실행 기록”
GET /api/cron/{id}/runs?limit=20

최근 실행 기록을 최신순으로 반환합니다. limit은 1–100 범위로 제한됩니다(기본값 20). 존재하지 않는 작업 ID는 404를 반환합니다.

{
  "runs": [
    {
      "id": "…",
      "job_id": "…",
      "started_at": "2026-06-18T09:00:00+00:00",
      "finished_at": "2026-06-18T09:00:03+00:00",
      "status": "ok",
      "output": "…",
      "duration_ms": 3120
    }
  ]
}

status는 "ok" 또는 "error"입니다. 저장된 출력은 실행당 16 KiB로 제한되며, 작업당 보관되는 기록 수는 max_run_history(설정 참조)로 관리됩니다. 스토리지 및 정리에 대한 자세한 내용은 에이전트 작업 및 전달을 참조하십시오.

크론 설정

섹션 제목: “크론 설정”

런타임에 서브시스템의 전역 플래그를 읽거나 변경합니다.

GET   /api/cron/settings
PATCH /api/cron/settings
{ "enabled": true, "catch_up_on_startup": false, "max_run_history": 100 }
필드타입설명
enabledbool전체 크론 서브시스템의 전역 켜기/끄기 스위치
catch_up_on_startupbool데몬이 오프라인 상태일 때 누적된 작업을 부팅 시 한 번 실행
max_run_historyint작업당 보관되는 기록 수. 오래된 실행 기록은 자동으로 정리됨

PATCH는 이 필드들의 일부만 허용하며, 디스크 설정에 저장하고 데몬 재시작 없이 즉시 라이브 설정에 적용합니다. 응답은 결과 설정을 그대로 반환합니다.

String vs. object schedules

섹션 제목: “String vs. object schedules”

스케줄 형식은 HTTP API와 에이전트 도구 / CLI / 설정 파일 사이의 가장 중요한 차이점입니다.

  • Gateway API (POST / PATCH /api/cron): schedule은 단순 크론 표현식 문자열입니다. 예: "0 9 * * *". 게이트웨이는 이를 UTC 기준의 크론 스케줄로 래핑합니다. 타임존 설정이 불가능하며, at (일회성) 또는 every (인터벌) 작업을 이 API를 통해 생성할 수 없습니다.

  • 에이전트 도구, CLI, [[cron.jobs]] 설정: schedule은 kind 구분자를 가진 타입이 있는 객체입니다.

    { "kind": "cron",  "expr": "0 9 * * *", "tz": "America/New_York" }
    { "kind": "every", "every_ms": 3600000 }
    { "kind": "at",    "at": "2026-12-31T23:59:00Z" }

타임존, 인터벌, 또는 일회성 스케줄이 필요한 경우 revka cron CLI(add --tz, add-every, add-at, once) 또는 cron_add 에이전트 도구로 작업을 생성하십시오. 이렇게 생성된 작업도 이후 HTTP를 통해 목록 조회, 검사, 삭제가 가능합니다. 크론 표현식은 표준 5필드 crontab 구문을 허용합니다(Revka는 1 = 월요일 사용). 정규화 및 요일 규칙은 크론 개요 및 표현식을 참조하십시오.

채팅 세션

섹션 제목: “채팅 세션”

이 엔드포인트들은 대시보드의 Operator 채팅을 지원하는 영구 WebSocket 채팅 세션을 관리합니다. 세션 지속성이 활성화된 경우에만 사용 가능합니다(세션 TTL 및 지속성 참조). 비활성화된 경우 목록 엔드포인트는 빈 집합을 반환하고 항목 엔드포인트는 404를 반환합니다.

대시보드 세션은 gw_ 키 접두사 하에 저장되며, API는 이를 베어 ID로 노출합니다. 채널 세션 지속성이 활성화된 경우 목록 엔드포인트는 채널 세션(Telegram, Discord, Slack 등)도 함께 표시합니다. 개념 모델은 세션 및 대화 상태를 참조하십시오.

세션 목록 조회

섹션 제목: “세션 목록 조회”
GET /api/sessions
{
  "sessions": [
    {
      "id": "…",
      "channel": "dashboard",
      "name": "My session",
      "started_at": "2026-06-18T08:00:00+00:00",
      "last_activity": "2026-06-18T09:12:00+00:00",
      "status": "active",
      "message_count": 14
    }
  ],
  "archived_session_ids": ["…"]
}

status는 최근성에 따라 결정됩니다. 마지막 활동이 5분 이내이면 "active", 그 외에는 "idle"입니다. name은 세션이 이름이 변경된 경우에만 존재합니다. archived_session_ids는 소프트 삭제된 세션(삭제 참조)을 나열합니다.

실행 중인 세션 목록 조회

섹션 제목: “실행 중인 세션 목록 조회”
GET /api/sessions/running

현재 진행 중인 턴이 있는 세션만 반환합니다.

{ "sessions": [ { "session_id": "…", "created_at": "…", "last_activity": "…", "message_count": 14 } ] }

메시지 로드

섹션 제목: “메시지 로드”
GET /api/sessions/{id}/messages

저장된 대화 기록을 반환합니다.

{
  "session_id": "…",
  "messages": [ { "role": "user", "content": "…" }, { "role": "assistant", "content": "…" } ],
  "session_persistence": true
}

지속성이 비활성화된 경우에도 messages 배열이 비어 있고 "session_persistence": false인 상태로 200을 반환하므로, 클라이언트가 정상적으로 저하됩니다.

세션 상태 조회

섹션 제목: “세션 상태 조회”
GET /api/sessions/{id}/state
{ "session_id": "…", "state": "running", "turn_id": "…", "turn_started_at": "2026-06-18T09:12:00+00:00" }

state는 라이브 실행 상태를 반영합니다(예: idle 또는 running). turn_id와 turn_started_at은 턴이 진행 중일 때만 존재합니다. 알 수 없는 ID는 404를 반환합니다.

세션 이름 변경

섹션 제목: “세션 이름 변경”
PUT /api/sessions/{id}
Content-Type: application/json


{ "name": "Quarterly planning" }

name은 필수이며 비어 있으면 안 됩니다(그렇지 않으면 400). 알 수 없는 ID는 404를 반환합니다. 성공 시 { "session_id": "…", "name": "Quarterly planning" }을 반환합니다.

세션 삭제

섹션 제목: “세션 삭제”
DELETE /api/sessions/{id}

이 작업은 세션을 완전히 삭제하는 것이 아니라 보관(소프트 삭제)합니다. 따라서 기록은 복구 가능한 상태로 유지되며, ID는 목록 응답의 archived_session_ids에 표시됩니다.

{ "deleted": true, "archived": true, "archived_at": "2026-06-18T09:30:00+00:00", "session_id": "…" }

Session TTL & persistence

섹션 제목: “Session TTL & persistence”

세션 스토리지는 게이트웨이 설정으로 제어됩니다.

설정 키타입설명
[gateway] session_persistencebooltrue이면 대시보드 채팅 세션이 SQLite 백엔드에 저장됩니다. false이면 세션 엔드포인트에 관리할 내용이 없습니다.
[gateway] session_ttl_hoursint세션이 정리 대상이 되기 전까지 보관되는 시간.

채널 세션은 채널 세션 지속성도 활성화된 경우에만 GET /api/sessions에 표시됩니다. 관련 게이트웨이 설정은 TLS, 속도 제한, WebAuthn 및 정적 서빙을 참조하고, 턴 간 상태 유지 방식은 세션 및 대화 상태를 참조하십시오.

채팅 첨부 파일 업로드

섹션 제목: “채팅 첨부 파일 업로드”

첨부 파일을 사용하면 채팅 턴에 이미지나 문서를 포함할 수 있습니다. 흐름은 두 단계입니다. 파일을 업로드하여 file_id를 받은 후, 다음 WebSocket 메시지에서 해당 ID를 참조합니다.

파일 업로드

섹션 제목: “파일 업로드”
POST /api/sessions/{session_id}/attachments
Content-Type: multipart/form-data

file이라는 이름의 파일 필드를 정확히 하나 전송하십시오. 파일당 최대 크기는 25 MiB입니다. 빈 파일이나 file 필드 누락 시 400을 반환하며, 크기 초과 파일은 413을 반환합니다.

Terminal window
curl -X POST "https://<gateway>/api/sessions/<session_id>/attachments" \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]"

성공 시 서버는 파일을 <workspace>/attachments/<session_id>/ 하에 저장하고 201을 반환합니다.

{
  "file_id": "…",
  "filename": "report.pdf",
  "size": 184320,
  "mime": "application/pdf",
  "session_id": "…",
  "created_at": "2026-06-18T09:40:00+00:00"
}

The file_id flow

섹션 제목: “The file_id flow”

  1. 위의 요청으로 파일을 업로드하고 반환된 file_id를 보관합니다.

  2. WebSocket을 통해 다음 채팅 메시지에서 attachments 배열에 ID를 포함하여 참조합니다.

    { "type": "message", "content": "Summarize this report", "attachments": ["<file_id>"] }

  3. 게이트웨이는 각 file_id를 동일한 session_id에 대해 확인하고, 에이전트 턴 전에 마커로 재작성합니다.

    • image/로 시작하는 MIME 타입은 [IMAGE:…] 마커가 되어 기존 비전 파이프라인을 통해 처리되므로, 비전 지원 모델이 콘텐츠 블록으로 인식합니다.
    • 그 외에는 [DOCUMENT:…] 마커가 됩니다(텍스트는 모델에 인라인으로 포함).

메시지 프로토콜, 스트리밍 이벤트, 브라우저 WebSocket에서 베어러 토큰을 전달하는 방법은 실시간: WebSocket, SSE 및 라이브 캔버스를 참조하십시오. 대시보드 UI에서 채팅을 사용하려면 대시보드 실행과 에이전트와 채팅하기를 참조하십시오.

Built by Kumiho. Revka is open source under MIT/Apache-2.0.
Home revka.ai GitHub

시작하기

Revka 문서 설치 빠른 시작 온보딩 마법사 (revka onboard) Python MCP 사이드카 설치 macOS 업데이트 및 제거 Revka 작동 방식

핵심 개념

에이전트 루프 자율성 수준 및 승인 에이전트, 팀, 스웜 세션 및 대화 상태 보안 모델

가이드

대시보드 실행 에이전트와 대화하기 메시징 채널 연결 Telegram 및 Matrix 설정 Mattermost 및 Nextcloud Talk 설정 브라우저 자동화 Kumiho 그래프 메모리 커스텀 프로바이더 및 로컬 LLM 터널로 게이트웨이 노출

CLI 참조

CLI 개요 및 환경 revka agent revka gateway, daemon, service revka cron revka channel 및 integrations revka models, providers, auth revka memory 및 estop revka skills, workflows, sop revka doctor, status, self-test revka hardware 및 peripheral revka install, update, migrate, completions & ACP

게이트웨이 API

게이트웨이 API 개요 페어링 및 인증 상태, 헬스, 구성, 도구 엔드포인트 크론, 세션, 첨부 파일 API 에이전트, 스킬, 팀 API 워크플로우 및 Architect API 메모리 그래프 및 에셋 브라우저 API MCP 프록시 및 디스커버리 API 웹훅 수신 실시간: WebSocket, SSE, 라이브 캔버스 비용, 감사, ClawHub, 자격 증명 API TLS, 속도 제한, WebAuthn, 정적 서빙

대시보드

대시보드 개요 워크플로우, 편집기, 실행 에이전트, 팀, 캔버스 에셋 및 메모리 탐색기 스킬, 도구, 통합 페이지 크론, 비용, 구성 페이지 오퍼레이터 채팅 어시스턴트 로그, 감사, 닥터, 페어링, 스킨 페이지

채널

채널 개요 Telegram, Discord, Slack Matrix, Mattermost, Nextcloud Talk Signal, Nostr, IRC WhatsApp (Cloud API 및 Web) Lark, Feishu, DingTalk, WeCom, QQ, Mochat Bluesky, X/Twitter, Reddit 이메일, iMessage, Linq, 자동화 음성, TTS, 전사

프로바이더 및 모델

프로바이더 빠른 시작 프로바이더 카탈로그 클라우드 API 프로바이더 (Gemini, Bedrock, Azure) 로컬, 자체 호스팅, 커스텀 엔드포인트 OAuth 및 구독 프로바이더 중국 지역 프로바이더 라우팅, 안정성, 튜닝

도구

도구 개요 파일시스템 및 코드 도구 브라우저 및 웹 도구 미디어 및 비전 도구 스케줄링 및 SOP 도구 코드 에이전트, 위임, 파이프라인 커뮤니케이션 및 에스컬레이션 도구 생산성 통합 도구 클라우드, 보안, 데이터, 런타임 도구

메모리

메모리 개요 Kumiho 설정 Kumiho 메모리 도구 그래프 모델: 스페이스, 아이템, 출처 응답 캐시, 하드웨어 RAG, 격리

워크플로우 및 SOP

워크플로우 및 SOP 개요 첫 번째 워크플로우 워크플로우 YAML 참조 스텝 타입 참조 변수, 표현식, 트리거 실행, 승인, 체크포인트 내장 워크플로우 및 오케스트레이션 패턴 SOP 참조: 구문, 트리거, 실행 검증 가능한 의도 (커머스 게이팅)

크론 및 스케줄링

크론 개요 및 표현식 에이전트 작업 및 전달 선언적 작업 및 스케줄러 구성

보안 및 감사

정책, 명령, 샌드박싱 OTP 게이팅 및 비상 정지 시크릿, 페어링, 디바이스 인증 감사 로그 프롬프트 인젝션, 유출 탐지, 신뢰 엔터프라이즈 IAM (Nevis)

배포 및 운영

런타임 모드, 어댑터, 리소스 제한 백그라운드 서비스로 실행 Docker, Compose, 원클릭 PaaS 네트워크 배포, Raspberry Pi, 프록시 업데이트, 런북, 문제 해결 관측성 및 트레이싱 비용 추적 및 예산 하트비트 및 라이프사이클 훅

하드웨어

하드웨어 빠른 시작 지원 보드 참조 펌웨어 플래싱 GPIO 도구 Raspberry Pi (자체 호스팅) Aardvark I2C/SPI/GPIO 및 데이터시트 로봇 키트

MCP 및 확장성

MCP 서버로서의 Revka 외부 MCP 서버 연결 스킬 시스템 WASM 플러그인 통합 카탈로그

에코시스템

데스크톱 앱 오퍼레이터 MCP 에이전트 생성 및 조정 A2A 프로토콜 및 클라우드 에이전트 특수 제품군: CanonWorks, Manus, 노드

참조

구성 개요 구성: 프로바이더, 에이전트, 라우팅 구성: 채널, 도구, 통합 구성: 게이트웨이, 메모리, 보안, 플랫폼 Cargo 기능 플래그 및 ADR