에이전트 컴퓨터 API

API Playground에서 사용해 보세요.

기본 URL

https://api.rebyte.ai/v1

인증

모든 요청에는 API_KEY 헤더가 필요합니다. 설정 > API 키에서 키를 받으세요.

curl https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_your_key_here"

헤더 이름은 대소문자를 구분하지 않습니다. API_KEY, api-key, x-api-key 모두 작동합니다.

---

엔드포인트

메서드	경로	설명
POST	/tasks	작업 생성
GET	/tasks	작업 목록 조회
GET	/tasks/:id	상태 및 프롬프트 기록과 함께 작업 가져오기
POST	/tasks/:id/prompts	후속 프롬프트 전송
PATCH	/tasks/:id/visibility	작업 가시성 변경
DELETE	/tasks/:id	작업 소프트 삭제
GET	/tasks/:id/events	실행 이벤트의 SSE 스트림
POST	/files	서명된 파일 업로드 URL 가져오기
POST	/webhooks	웹훅 등록
GET	/webhooks	웹훅 목록 조회
GET	/webhooks/:id	웹훅 세부 정보 가져오기
DELETE	/webhooks/:id	웹훅 삭제
모든 경로는 기본 URL(https://api.rebyte.ai/v1)에 상대적입니다.

---

작업

작업 생성

POST /tasks

새 작업을 생성합니다. 기본적으로 새 VM(에이전트 컴퓨터)을 프로비저닝합니다. 대신 workspaceId를 전달하여 기존 작업 공간에서 작업을 실행할 수 있습니다. 이렇게 하면 프로비저닝이 생략되어 훨씬 빠릅니다.

VM이 프로비저닝되고 첫 번째 프롬프트가 제출될 때까지 호출이 차단됩니다.

요청 본문:

필드	유형	필수	설명
prompt	string	Yes	작업 설명 (최대 100,000자)
executor	string	No	claude (기본값), gemini, codex, opencode
model	string	No	실행자를 위한 모델 티어입니다. 모델을 참조하세요.
workspaceId	string	No	재사용할 기존 작업 공간의 UUID
files	object[]	No	POST /files에서 가져온 파일입니다. 각 항목: {"id": "...", "filename": "..."}
skills	string[]	No	스킬 슬러그 (예: ["deep-research", "pdf"])
githubUrl	string	No	owner/repo 형식의 GitHub 리포지토리
branchName	string	No	브랜치 이름 (기본값: main)

curl -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a REST API with Express and add tests",
    "executor": "claude",
    "skills": ["deep-research"],
    "githubUrl": "your-org/your-repo"
  }'

응답 (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "url": "https://app.rebyte.ai/run/550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "createdAt": "2026-01-28T12:00:00.000Z"
}

응답에서 workspaceId를 저장하여 동일한 에이전트 컴퓨터에서 후속 작업을 생성하세요:

# 첫 번째 작업 -- 새 VM 프로비저닝
RESP=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d '{"prompt": "Set up the project"}')
WS_ID=$(echo $RESP | jq -r '.workspaceId')

# 두 번째 작업 -- 동일한 VM 재사용 (훨씬 빠름)
curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Now add tests\", \"workspaceId\": \"$WS_ID\"}"

모델

사용 가능한 모델은 실행자에 따라 다릅니다:

실행자	사용 가능한 모델	기본값
claude	claude-sonnet-4.6, claude-opus-4.6, gemini-3.1-pro, gpt-5.3-codex, gpt-5.4, minimax-m2.7, kimi-k2.5, glm-5, gemini-3-flash	claude-sonnet-4.6
codex	gpt-5.4, gpt-5.3-codex	gpt-5.4
gemini	auto-gemini-3 (flash와 pro 사이 자동 라우팅)	auto-gemini-3
opencode	claude와 동일	gemini-3.1-pro

BYOK(자체 API 키 사용)를 사용하면 실행자의 기본 제공 모델만 사용할 수 있습니다(예: BYOK를 사용하는 claude 실행자는 claude-sonnet-4.6 및 claude-opus-4.6만 얻습니다).

작업 목록 조회

GET /tasks?limit=50&offset=0

API를 통해 생성된 작업을 생성 시간(최신순)으로 정렬하여 반환합니다.

매개변수	유형	기본값	설명
limit	number	50	페이지당 결과 (최대 100개)
offset	number	0	페이지네이션 오프셋

curl "https://api.rebyte.ai/v1/tasks?limit=10" \
  -H "API_KEY: rbk_xxx"

응답:

{
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://app.rebyte.ai/run/550e8400-...",
      "title": "Build REST API with Express",
      "executor": "claude",
      "model": "claude-sonnet-4.6",
      "createdAt": "2026-01-28T12:00:00.000000+00:00",
      "completedAt": "2026-01-28T12:05:00.000000+00:00"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

작업 가져오기

GET /tasks/:id

프롬프트 기록 및 파생된 상태를 포함한 전체 작업 세부 정보를 반환합니다.

curl https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

응답:

{
  "id": "550e8400-...",
  "url": "https://app.rebyte.ai/run/550e8400-...",
  "status": "running",
  "title": "Build REST API with Express",
  "executor": "claude",
  "model": "claude-sonnet-4.6",
  "createdAt": "2026-01-28T12:00:00.000000+00:00",
  "completedAt": null,
  "prompts": [
    {
      "id": "660e8400-...",
      "status": "running",
      "submittedAt": "2026-01-28T12:05:00.000000+00:00",
      "completedAt": null
    },
    {
      "id": "550e8400-...",
      "status": "succeeded",
      "submittedAt": "2026-01-28T12:00:01.000000+00:00",
      "completedAt": "2026-01-28T12:03:00.000000+00:00"
    }
  ]
}

작업 상태는 프롬프트 상태에서 파생됩니다:

상태	조건
running	모든 프롬프트가 pending 또는 running 상태입니다.
completed	모든 프롬프트가 종료되었고, 최신 프롬프트가 succeeded 상태입니다.
failed	모든 프롬프트가 종료되었고, 최신 프롬프트가 failed 상태입니다.
canceled	모든 프롬프트가 종료되었고, 최신 프롬프트가 canceled 상태입니다.

후속 프롬프트 전송

POST /tasks/:id/prompts

실행 중이거나 완료된 작업에 후속 프롬프트를 보냅니다. VM이 중지된 경우 자동으로 다시 시작됩니다.

필드	유형	필수	설명
prompt	string	Yes	후속 프롬프트 (최대 100,000자)
skills	string[]	No	이 프롬프트에 대한 추가 스킬 슬러그

curl -X POST https://api.rebyte.ai/v1/tasks/550e8400-.../prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add authentication with JWT"}'

응답 (201):

{
  "promptId": "770f9500-..."
}

이벤트 스트림 (SSE)

GET /tasks/:id/events

작업의 최신 프롬프트에 대한 Server-Sent Events 스트림을 엽니다. 이벤트에는 에이전트 출력(stdout, stderr), 도구 호출 및 완료 신호가 포함됩니다.

curl -N https://api.rebyte.ai/v1/tasks/550e8400-.../events \
  -H "API_KEY: rbk_xxx"

스트림은 두 가지 이벤트 유형을 내보냅니다:

• event — 실행 이벤트 (에이전트 출력, 도구 호출)
• done — 완료 상태를 포함하는 최종 이벤트이며, 그 후 스트림이 닫힙니다.

가시성 변경

PATCH /tasks/:id/visibility

필드	유형	필수	설명
visibility	string	Yes	private, shared, 또는 public

수준	누가 볼 수 있나요
private	API 키 소유자만
shared	모든 조직 구성원 (기본값)
public	링크가 있는 모든 사람 (읽기 전용)

curl -X PATCH https://api.rebyte.ai/v1/tasks/550e8400-.../visibility \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}'

public으로 설정하면 응답에 인증되지 않은 액세스를 위한 shareUrl이 포함됩니다.

작업 삭제

DELETE /tasks/:id

작업을 소프트 삭제합니다. 204 No Content를 반환합니다.

curl -X DELETE https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

---

파일

작업에 첨부할 파일을 업로드합니다. 두 단계의 서명된 URL 흐름을 사용합니다.

1단계: 업로드 URL 가져오기

POST /files

필드	유형	필수	설명
filename	string	Yes	파일 이름 (최대 255자)
contentType	string	No	MIME 유형 (기본값: application/octet-stream)

응답 (201):

{
  "id": "550e8400-...",
  "filename": "data.csv",
  "uploadUrl": "https://storage.googleapis.com/...",
  "maxFileSize": 52428800
}

업로드 URL은 1시간 후에 만료됩니다.

2단계: 파일 업로드

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv

3단계: 작업에 첨부

작업을 생성할 때 1단계의 id와 filename을 전달하세요:

{
  "prompt": "Analyze the uploaded data",
  "files": [
    {"id": "550e8400-...", "filename": "data.csv"}
  ]
}

파일은 실행이 시작될 때 작업의 VM으로 자동으로 복사됩니다.

---

웹훅

작업 이벤트가 발생할 때 HTTP POST 알림을 받습니다. 웹훅은 범용적입니다. API, UI 또는 다른 채널을 통해 생성되었는지 여부에 관계없이 조직의 모든 작업에 대해 실행됩니다.

이벤트

이벤트	발생 시점
task.created	새 작업이 생성될 때
task.running	에이전트가 실행을 시작할 때
task.completed	작업이 성공적으로 완료될 때
task.failed	작업이 실패할 때
task.canceled	사용자가 작업을 취소할 때

웹훅 생성

POST /webhooks

필드	유형	필수	설명
url	string	Yes	HTTPS 엔드포인트 URL
events	string[]	Yes	구독할 이벤트
description	string	No	사람이 읽을 수 있는 레이블 (최대 500자)
secret	string	No	사전 공유 비밀 (최대 500자). 설정된 경우, 모든 전달에서 X-Webhook-Secret 헤더로 포함됩니다.

# 비밀이 없는 웹훅
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"]
  }'

# 사전 공유 비밀이 있는 웹훅
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "my-shared-secret-value"
  }'

응답 (201):

{
  "id": "880e8400-...",
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "task.failed"],
  "description": null,
  "hasSecret": true,
  "isActive": true,
  "createdAt": "2026-01-28T12:00:00.000Z",
  "lastTriggeredAt": null,
  "failureCount": 0
}

동작 참고 사항:

• 중복 URL: 동일한 URL을 두 번 등록하면 기존 웹훅이 반환됩니다 (멱등성).
• 제한: 조직당 최대 3개의 웹훅. 4번째 웹훅은 limit_exceeded를 반환합니다.
• 비밀 저장: 비밀 값은 어떤 응답에서도 반환되지 않습니다. hasSecret: true/false만 노출됩니다.

웹훅 목록 조회

GET /webhooks

조직의 모든 웹훅을 상태 정보(lastTriggeredAt, failureCount, isActive)와 함께 반환합니다. 비밀은 절대 노출되지 않습니다.

웹훅 가져오기

GET /webhooks/:id

웹훅 삭제

DELETE /webhooks/:id

204 No Content를 반환합니다. 삭제된 웹훅은 즉시 전달을 중단합니다.

전달

작업 이벤트가 웹훅의 구독된 이벤트와 일치하면 Rebyte는 웹훅 URL로 HTTP POST를 보냅니다.

페이로드:

{
  "event": "task.completed",
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1706443200,
  "data": {
    "status": "succeeded",
    "taskUrl": "https://app.rebyte.ai/run/550e8400-...",
    "result": "Created CSV file with 10 Hacker News posts..."
  }
}

• status — 프롬프트 상태: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
• taskUrl — Rebyte UI의 작업에 대한 직접 링크 (항상 존재)
• result — 최종 AI 출력 텍스트 (종료 이벤트에 존재: task.completed, task.failed, task.canceled; task.created 및 task.running에는 없음)

프롬프트 기록을 포함한 전체 작업 세부 정보를 보려면 GET /tasks/:id를 호출하세요.

전달 헤더:

헤더	항상 존재	설명
Content-Type	Yes	application/json
X-Webhook-Signature	Yes	Base64로 인코딩된 RSA-SHA256 서명
X-Webhook-Timestamp	Yes	Unix 타임스탬프 (초)
X-Webhook-Secret	Only if secret configured	생성 시 설정한 사전 공유 비밀 값

타임아웃: 전달은 10초 후에 타임아웃됩니다.

실패 처리:

• 전달은 발사 후 망각 방식입니다 — 실패 시 자동 재시도가 없습니다.
• 2xx가 아닌 응답은 failureCount를 증가시킵니다.
• 10회 연속 실패 후, 웹훅은 자동으로 비활성화됩니다 (isActive: false).
• 성공적인 전달은 failureCount를 0으로 재설정합니다.

서명 확인

모든 전달은 사전 공유 비밀이 구성되었는지 여부와 관계없이 조직의 RSA-2048 키 쌍으로 서명됩니다.

작동 방식:

1. Rebyte는 {timestamp}.{body}를 연결합니다 (예: 1706443200.{"event":"task.completed",...}).
2. 조직의 개인 키를 사용하여 RSA-SHA256으로 문자열에 서명합니다.
3. X-Webhook-Signature에 base64로 인코딩된 서명을 보냅니다.

공개 키 가져오기: 지원팀에 문의하거나 Rebyte 대시보드에서 검색하세요. RSA-2048 키 쌍은 첫 웹훅 생성 시 자동으로 생성되며 조직에 영구적으로 유지됩니다.

확인 예시 (Node.js):

const crypto = require('crypto');

function verifyWebhook(rawBody, timestamp, signature, publicKey) {
  const payload = `${timestamp}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(payload);
  return verifier.verify(publicKey, signature, 'base64');
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // 파싱된 JSON이 아닌 원시 문자열이어야 합니다.
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhook(rawBody, timestamp, signature, PUBLIC_KEY)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log(`Task ${event.taskId}: ${event.event}`);
  res.status(200).send('OK');
});

확인 예시 (Python):

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def verify_webhook(raw_body: str, timestamp: str, signature: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    payload = f"{timestamp}.{raw_body}".encode()
    try:
        public_key.verify(
            base64.b64decode(signature),
            payload,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception:
        return False

2단계 보안

웹훅은 함께 사용할 수 있는 두 가지 독립적인 확인 방법을 지원합니다:

방법	헤더	작동 방식	사용 사례
RSA 서명	X-Webhook-Signature	페이로드가 Rebyte에서 왔다는 암호화 증명	변조 방지 확인
사전 공유 비밀	X-Webhook-Secret	생성 시 설정한 정적 문자열로, 모든 전달에서 다시 반환됩니다.	간단한 공유 비밀 확인

RSA 서명은 항상 존재합니다. 사전 공유 비밀은 선택 사항입니다. 더 간단한 확인 경로를 원하면 웹훅 생성 시 설정하세요.

---

폴링 예시

전체 예시: 작업을 생성하고, 완료될 때까지 폴링한 다음, 후속 프롬프트를 보냅니다.

# 작업 생성
TASK_ID=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a Python CLI that converts CSV to JSON"}' | jq -r '.id')

echo "Task: https://app.rebyte.ai/run/$TASK_ID"

# 완료될 때까지 폴링
while true; do
  STATUS=$(curl -s https://api.rebyte.ai/v1/tasks/$TASK_ID \
    -H "API_KEY: rbk_xxx" | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 5
done

# 후속 프롬프트 전송
curl -s -X POST https://api.rebyte.ai/v1/tasks/$TASK_ID/prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add support for nested JSON objects"}'

---

오류 형식

모든 오류는 다음 구조를 따릅니다:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

코드	HTTP 상태	설명
missing_api_key	401	API_KEY 헤더가 제공되지 않았습니다.
invalid_api_key	401	유효하지 않거나 만료된 API 키
validation_error	400	요청 본문 유효성 검사 실패
not_found	404	리소스가 존재하지 않거나 액세스할 수 없습니다.
limit_exceeded	400	조직 제한에 도달했습니다 (예: 최대 웹훅 수).
agent_disabled	403	요청된 실행자가 이 조직에 대해 비활성화되었습니다.
internal_error	500	서버 측 실패

속도 제한

API는 현재 키별 속도 제한을 적용하지 않습니다. 각 POST /tasks는 실제 VM을 프로비저닝하므로 비용은 사용량에 따라 증가합니다. 불필요한 요청을 줄이려면 적극적인 폴링 대신 웹훅을 사용하세요.