API Máy tính Agent

Base URL

https://api.rebyte.ai/v1

Authentication

Mọi yêu cầu đều cần một header API_KEY. Lấy khóa của bạn từ Cài đặt > Khóa API.

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

Tên header không phân biệt chữ hoa chữ thường. API_KEY, api-key và x-api-key đều hoạt động.

Endpoints

Phương thức	Đường dẫn	Mô tả
POST	`/tasks`	Tạo một tác vụ
GET	`/tasks`	Liệt kê các tác vụ
GET	`/tasks/:id`	Lấy tác vụ với trạng thái và lịch sử lời nhắc
POST	`/tasks/:id/prompts`	Gửi một lời nhắc tiếp theo
PATCH	`/tasks/:id/visibility`	Thay đổi khả năng hiển thị của tác vụ
DELETE	`/tasks/:id`	Xóa mềm một tác vụ
GET	`/tasks/:id/events`	Luồng SSE của các sự kiện thực thi
POST	`/files`	Lấy URL tải lên tệp đã ký
POST	`/webhooks`	Đăng ký một webhook
GET	`/webhooks`	Liệt kê các webhook
GET	`/webhooks/:id`	Lấy chi tiết webhook
DELETE	`/webhooks/:id`	Xóa một webhook
Tất cả các đường dẫn đều tương đối so với URL cơ sở (`https://api.rebyte.ai/v1`).

Tasks

Create Task

POST /tasks

Tạo một tác vụ mới. Theo mặc định, cung cấp một VM mới (Máy tính Agent). Truyền workspaceId để chạy tác vụ trên một không gian làm việc hiện có thay vì — điều này bỏ qua việc cung cấp và nhanh hơn đáng kể.

Cuộc gọi sẽ chặn cho đến khi VM được cung cấp và lời nhắc đầu tiên được gửi.

Nội dung yêu cầu:

Trường	Kiểu	Bắt buộc	Mô tả
`prompt`	string	Yes	Mô tả tác vụ (tối đa 100.000 ký tự)
`executor`	string	No	`claude` (mặc định), `gemini`, `codex`, `opencode`
`model`	string	No	Cấp mô hình cho trình thực thi. Xem Mô hình.
`workspaceId`	string	No	UUID của một không gian làm việc hiện có để sử dụng lại
`files`	object[]	No	Các tệp từ `POST /files`. Mỗi tệp: `{"id": "...", "filename": "..."}`
`skills`	string[]	No	Slug kỹ năng (ví dụ: `["deep-research", "pdf"]`)
`githubUrl`	string	No	Kho lưu trữ GitHub ở định dạng `owner/repo`
`branchName`	string	No	Tên nhánh (mặc định: `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"
  }'

Phản hồi (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"
}

Lưu workspaceId từ phản hồi để tạo các tác vụ tiếp theo trên cùng một Máy tính Agent:

# Tác vụ đầu tiên -- cung cấp một VM mới
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')

# Tác vụ thứ hai -- sử dụng lại cùng một VM (nhanh hơn nhiều)
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\"}"

Models

Các mô hình có sẵn phụ thuộc vào trình thực thi:

Trình thực thi	Mô hình có sẵn	Mặc định
`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` (auto-routes between flash and pro)	`auto-gemini-3`
`opencode`	Same as `claude`	`gemini-3.1-pro`

Với BYOK (mang theo khóa API của riêng bạn), chỉ các mô hình nhà cung cấp gốc của trình thực thi mới có sẵn (ví dụ: trình thực thi claude với BYOK chỉ nhận được claude-sonnet-4.6 và claude-opus-4.6).

List Tasks

GET /tasks?limit=50&offset=0

Trả về các tác vụ được tạo qua API, sắp xếp theo thời gian tạo (mới nhất trước).

Tham số	Kiểu	Mặc định	Mô tả
`limit`	number	50	Kết quả mỗi trang (tối đa 100)
`offset`	number	0	Độ lệch phân trang

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

Phản hồi:

{
  "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 Task

GET /tasks/:id

Trả về chi tiết tác vụ đầy đủ bao gồm lịch sử lời nhắc và trạng thái dẫn xuất.

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

Phản hồi:

{
  "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"
    }
  ]
}

Trạng thái tác vụ được dẫn xuất từ trạng thái lời nhắc:

Trạng thái	Điều kiện
`running`	Bất kỳ lời nhắc nào đang `pending` hoặc `running`
`completed`	Tất cả lời nhắc đã kết thúc, lời nhắc mới nhất là `succeeded`
`failed`	Tất cả lời nhắc đã kết thúc, lời nhắc mới nhất là `failed`
`canceled`	Tất cả lời nhắc đã kết thúc, lời nhắc mới nhất là `canceled`

Send Follow-Up

POST /tasks/:id/prompts

Gửi một lời nhắc tiếp theo cho một tác vụ đang chạy hoặc đã hoàn thành. Nếu VM bị dừng, nó sẽ tự động được tiếp tục.

Trường	Kiểu	Bắt buộc	Mô tả
`prompt`	string	Yes	Lời nhắc tiếp theo (tối đa 100.000 ký tự)
`skills`	string[]	No	Các slug kỹ năng bổ sung cho lời nhắc này

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"}'

Phản hồi (201):

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

Stream Events (SSE)

GET /tasks/:id/events

Mở một luồng Server-Sent Events cho lời nhắc mới nhất của tác vụ. Các sự kiện bao gồm đầu ra của agent (stdout, stderr), các lệnh gọi công cụ và tín hiệu hoàn thành.

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

Luồng phát ra hai loại sự kiện:

event — các sự kiện thực thi (đầu ra của agent, các lệnh gọi công cụ)
done — sự kiện cuối cùng với trạng thái hoàn thành, sau đó luồng đóng lại

Change Visibility

PATCH /tasks/:id/visibility

Trường	Kiểu	Bắt buộc	Mô tả
`visibility`	string	Yes	`private`, `shared`, hoặc `public`

Cấp độ	Ai có thể xem
`private`	Chỉ chủ sở hữu khóa API
`shared`	Tất cả thành viên tổ chức (mặc định)
`public`	Bất kỳ ai có liên kết (chỉ đọc)

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

Khi được đặt thành public, phản hồi bao gồm một shareUrl để truy cập không cần xác thực.

Delete Task

DELETE /tasks/:id

Xóa mềm tác vụ. Trả về 204 No Content.

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

Files

Tải lên tệp để đính kèm vào tác vụ. Sử dụng quy trình URL đã ký hai bước.

Step 1: Get Upload URL

POST /files

Trường	Kiểu	Bắt buộc	Mô tả
`filename`	string	Yes	Tên tệp (tối đa 255 ký tự)
`contentType`	string	No	Kiểu MIME (mặc định: `application/octet-stream`)

Phản hồi (201):

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

URL tải lên hết hạn sau 1 giờ.

Step 2: Upload the File

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

Step 3: Attach to Task

Truyền id và filename từ Bước 1 khi tạo một tác vụ:

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

Các tệp được tự động sao chép vào VM của tác vụ khi quá trình thực thi bắt đầu.

Webhooks

Nhận thông báo HTTP POST khi các sự kiện tác vụ xảy ra. Webhook là phổ quát — chúng kích hoạt cho tất cả các tác vụ trong tổ chức của bạn, cho dù được tạo qua API, UI hay bất kỳ kênh nào khác.

Events

Sự kiện	Kích hoạt khi
`task.created`	Một tác vụ mới được tạo
`task.running`	Agent bắt đầu thực thi
`task.completed`	Tác vụ hoàn thành thành công
`task.failed`	Tác vụ thất bại
`task.canceled`	Tác vụ bị người dùng hủy

Create Webhook

POST /webhooks

Trường	Kiểu	Bắt buộc	Mô tả
`url`	string	Yes	URL điểm cuối HTTPS
`events`	string[]	Yes	Các sự kiện để đăng ký
`description`	string	No	Nhãn dễ đọc (tối đa 500 ký tự)
`secret`	string	No	Mã bí mật được chia sẻ trước (tối đa 500 ký tự). Khi được đặt, được bao gồm dưới dạng header `X-Webhook-Secret` trong mỗi lần gửi.

# Webhook không có mã bí mật
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"]
  }'

# Webhook với mã bí mật được chia sẻ trước
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"
  }'

Phản hồi (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
}

Lưu ý về hành vi:

URL trùng lặp: đăng ký cùng một URL hai lần sẽ trả về webhook hiện có (idempotent)
Giới hạn: tối đa 3 webhook cho mỗi tổ chức. Cái thứ 4 trả về limit_exceeded.
Lưu trữ mã bí mật: giá trị mã bí mật không bao giờ được trả về trong bất kỳ phản hồi nào. Chỉ hasSecret: true/false được hiển thị.

List Webhooks

GET /webhooks

Trả về tất cả các webhook cho tổ chức của bạn với thông tin trạng thái (lastTriggeredAt, failureCount, isActive). Mã bí mật không bao giờ được hiển thị.

Get Webhook

GET /webhooks/:id

Delete Webhook

DELETE /webhooks/:id

Trả về 204 No Content. Các webhook đã xóa ngay lập tức ngừng nhận các lần gửi.

Delivery

Khi một sự kiện tác vụ khớp với các sự kiện đã đăng ký của webhook, Rebyte sẽ gửi một HTTP POST đến URL webhook.

Tải trọng:

{
  "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 — trạng thái lời nhắc: pending (task.created), running (task.running), succeeded (task.completed), failed (task.failed), canceled (task.canceled)
taskUrl — liên kết trực tiếp đến tác vụ trong giao diện người dùng Rebyte (luôn có)
result — văn bản đầu ra AI cuối cùng (có mặt trong các sự kiện kết thúc: task.completed, task.failed, task.canceled; vắng mặt trong task.created và task.running)

Gọi GET /tasks/:id để biết chi tiết tác vụ đầy đủ bao gồm lịch sử lời nhắc.

Header gửi:

Header	Luôn có mặt	Mô tả
`Content-Type`	Có	`application/json`
`X-Webhook-Signature`	Có	Chữ ký RSA-SHA256 được mã hóa Base64
`X-Webhook-Timestamp`	Có	Dấu thời gian Unix (giây)
`X-Webhook-Secret`	Chỉ khi mã bí mật được cấu hình	Giá trị mã bí mật được chia sẻ trước mà bạn đã đặt khi tạo

Thời gian chờ: các lần gửi hết thời gian sau 10 giây.

Xử lý lỗi:

Việc gửi là fire-and-forget — không có thử lại tự động khi thất bại
Các phản hồi không phải 2xx làm tăng failureCount
Sau 10 lần thất bại liên tiếp, webhook sẽ tự động bị vô hiệu hóa (isActive: false)
Các lần gửi thành công đặt lại failureCount về 0

Signature Verification

Mỗi lần gửi đều được ký bằng cặp khóa RSA-2048 của tổ chức bạn, bất kể mã bí mật được chia sẻ trước có được cấu hình hay không.

Cách hoạt động:

Rebyte nối {timestamp}.{body} (ví dụ: 1706443200.{"event":"task.completed",...})
Ký chuỗi bằng RSA-SHA256 sử dụng khóa riêng của tổ chức bạn
Gửi chữ ký được mã hóa base64 trong X-Webhook-Signature

Lấy khóa công khai của bạn: liên hệ hỗ trợ hoặc truy xuất từ bảng điều khiển Rebyte. Cặp khóa RSA-2048 được tạo tự động khi tạo webhook lần đầu và tồn tại cho tổ chức.

Ví dụ xác minh (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');
}

// Trong trình xử lý webhook của bạn:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // phải là chuỗi thô, không phải JSON đã phân tích cú pháp
  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');
});

Ví dụ xác minh (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

Two-layer security

Webhook hỗ trợ hai phương pháp xác minh độc lập có thể được sử dụng cùng nhau:

Phương pháp	Header	Cách hoạt động	Trường hợp sử dụng
Chữ ký RSA	`X-Webhook-Signature`	Bằng chứng mật mã rằng tải trọng đến từ Rebyte	Xác minh chống giả mạo
Mã bí mật được chia sẻ trước	`X-Webhook-Secret`	Chuỗi tĩnh bạn đặt khi tạo, được lặp lại trong mỗi lần gửi	Kiểm tra mã bí mật đơn giản

Chữ ký RSA luôn có mặt. Mã bí mật được chia sẻ trước là tùy chọn — hãy đặt nó khi tạo webhook nếu bạn muốn một đường dẫn xác minh đơn giản hơn.

Polling Example

Ví dụ hoàn chỉnh: tạo một tác vụ, thăm dò cho đến khi hoàn thành, sau đó gửi một lời nhắc tiếp theo.

# Tạo tác vụ
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"

# Thăm dò cho đến khi hoàn thành
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

# Gửi một lời nhắc tiếp theo
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 Format

Tất cả các lỗi đều tuân theo cấu trúc này:

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

Mã	Trạng thái HTTP	Mô tả
`missing_api_key`	401	Header `API_KEY` không được cung cấp
`invalid_api_key`	401	Khóa API không hợp lệ hoặc đã hết hạn
`validation_error`	400	Nội dung yêu cầu không vượt qua xác thực
`not_found`	404	Tài nguyên không tồn tại hoặc không thể truy cập
`limit_exceeded`	400	Đã đạt giới hạn tổ chức (ví dụ: số webhook tối đa)
`agent_disabled`	403	Trình thực thi được yêu cầu bị vô hiệu hóa cho tổ chức này
`internal_error`	500	Lỗi phía máy chủ

Rate Limiting

API hiện không áp dụng giới hạn tốc độ cho mỗi khóa. Mỗi POST /tasks cung cấp một VM thực, vì vậy chi phí tăng theo mức sử dụng. Sử dụng webhook thay vì thăm dò tích cực để giảm các yêu cầu không cần thiết.