REST API
Veilus có thể chạy một REST API nhỏ ngay trên máy của bạn, để các chương trình khác bạn chạy — script, ứng dụng khác, agent LLM — có thể quản lý profile và pool proxy, điều khiển trang của profile đang chạy, và chạy, đặt lịch script Veilus Flow.
API này tắt theo mặc định. Bật nó từ trang API & MCP trong sidebar của app — trang này hiện cổng đang lắng nghe, cho bạn đúc và thu hồi token có tên, và đưa sẵn đoạn cấu hình để dán.
Chỉ cục bộ
Phần tiêu đề “Chỉ cục bộ”API chỉ lắng nghe trên 127.0.0.1 — không thứ gì ngoài máy bạn chạm tới được. Nó chạm được mọi profile, nên chỉ mở cho gói Pro trở lên và luôn tắt cho tới khi bạn bật.
Xác thực
Phần tiêu đề “Xác thực”Mọi request cần một bearer token, đúc từ trang API & MCP. Mỗi token có tên riêng (để phân biệt công cụ nào dùng token nào) và thu hồi được độc lập — giá trị đầy đủ của token chỉ hiện đúng một lần, lúc tạo.
Authorization: Bearer <token>Giới hạn tốc độ
Phần tiêu đề “Giới hạn tốc độ”Mỗi token được tối đa 30 lời gọi nặng trong 60 giây: POST để mở profile, tạo profile, tạo pool proxy, chạy script, chạy hàng loạt, hoặc chạy lịch ngay. Quá mức đó API trả 429 kèm header Retry-After. Lời gọi đọc và lời gọi nhẹ như đóng profile không bị đếm.
Base URL
Phần tiêu đề “Base URL”Cổng được chọn khi bạn bật API và hiện trên trang API & MCP. Thay <port> bên dưới bằng giá trị đó.
http://127.0.0.1:<port>Ví dụ
Phần tiêu đề “Ví dụ”curl -X GET \ -H "Authorization: Bearer $VEILUS_API_TOKEN" \ http://127.0.0.1:<port>/v1/profilesDanh sách route
Phần tiêu đề “Danh sách route” GET /v1/profiles
List Veilus browser profiles, with their running state; a running profile carries `cdpUrl`.
GET /v1/capacity
Return the current browser pool capacity and usage.
GET /v1/dsl/schema
Return the JSON schema for the drag-and-drop DSL.
POST /v1/dsl/compile
Compile a drag-and-drop DSL script into runnable code.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
dsl | object | có | DSL script body |
target | string | có |
POST /v1/profiles/:id/launch
Launch a profile's browser and wait for it to start; returns `{pid, cdpUrl}`, a full pool fails with 409 rather than queuing.
POST /v1/profiles/:id/stop
Stop a running profile's browser.
POST /v1/scripts/run
Start a script run on given profiles; returns the run immediately (its `id` is the run_id).
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
profile_ids | string[] | không | |
script_id | string (uuid) | có | |
variables | object | không |
POST /v1/scripts
Save an agent-authored Raw script into Veilus Flow.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
description | string | không | |
name | string | có | |
script_id | string (uuid) | không | Script to replace; omit to create a new one |
source | string | có | Full TypeScript source |
GET /v1/scripts
List every script without its source: id, name, version, mode (raw or dsl), origin and whether it is approved.
GET /v1/scripts/:id
Read a Raw script's source and approval state.
GET /v1/runs/:id
Read a script run's result by run_id.
POST /v1/profiles
Create 1-50 profiles; with a proxy pool, timezones follow each slot's geo.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
content_dataset_id | string (uuid) | không | Consume dataset for the Content slot |
count | integer | có | |
identity_dataset_id | string (uuid) | không | Fixed dataset: one unassigned row per new profile |
name_template | string | không | {n} becomes 1, 2, ... |
os | string | không | |
proxy_pool_id | string (uuid) | không | |
tags | string[] | không |
GET /v1/profiles/:id/proxy
Show a profile's proxy: pool, slot, host:port and geo, never the password.
GET /v1/proxy-pools
List proxy pools with entry counts and detected countries.
POST /v1/proxy-pools
Create a static proxy pool from proxy lines; bad lines are reported by number.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
lines | string[] | có | |
name | string | có | |
type | string | không |
POST /v1/proxy-pools/:id/assign
Assign a proxy pool to profiles; refuses profiles that already have a proxy unless force.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
force | boolean | không | |
profile_ids | string[] | có |
POST /v1/proxy-pools/:id/test
Test every proxy in a pool now: alive, latency, exit IP and geo.
GET /v1/schedules
List schedules with their script, target profiles, timing and next run.
POST /v1/schedules
Create a schedule for an approved script on explicit profiles; a once schedule turns itself off after it runs.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
concurrency | integer | không | |
cron_expr | string | không | 5 fields, e.g. "0 * * * *" |
daily_hour | integer | không | |
daily_minute | integer | không | |
enabled | boolean | không | |
interval_minutes | integer | không | interval: count of interval_unit |
interval_unit | string | không | |
name | string | có | |
profile_ids | string[] | có | |
run_at | string (date-time) | không | RFC 3339 with offset, e.g. 2026-10-04T09:00:00+07:00; required for once |
schedule_type | string | có | |
script_id | string (uuid) | có | An approved script |
stagger_ms | integer | không | |
weekly_day | integer | không | 0 = Sunday |
POST /v1/schedules/:id/enabled
Turn a schedule on or off; turning it on recomputes its next run.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
enabled | boolean | có |
POST /v1/schedules/:id/run
Run a schedule once now; returns the run immediately.
POST /v1/scripts/batch
Run an approved script on many profiles; returns the run immediately.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
concurrency | integer | không | |
profile_ids | string[] | có | |
script_id | string (uuid) | có | |
stagger_ms | integer | không | |
variables | object | không |
POST /v1/profiles/:id/variables
Replace all stored variables of a profile; returns the variable names only.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
variables | object | có |
GET /v1/runs
List recent runs, newest first; query schedule_id and limit (default 20, max 100).
GET /v1/openapi.json
Return the OpenAPI 3.1 document describing this REST API.
GET /v1/profiles/:id/snapshot
Accessibility snapshot of a running profile's page, with [id=N] per element.
POST /v1/profiles/:id/click
Click the element with a node id from snapshot or wait-for-element, with a real mouse; refuses hidden or covered elements.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
node_id | integer | có |
POST /v1/profiles/:id/type
Focus an element by node id and type text into it.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
node_id | integer | có | |
text | string | có |
POST /v1/profiles/:id/press-key
Press one named key (Enter, Tab, Escape, arrows, Backspace, Delete, Space).
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
key | string | có |
POST /v1/profiles/:id/scroll
Scroll a running profile's page by a number of pixels in one direction.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
amount | integer | có | |
direction | string | có |
POST /v1/profiles/:id/evaluate
Run JavaScript in a running profile's page; 64 KiB result cap, 10 s timeout.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
expression | string | có |
POST /v1/profiles/:id/wait-for-element
Wait until a CSS selector matches and return the element's node id.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
selector | string | có | |
timeout_ms | integer | không |
POST /v1/profiles/:id/set-file
Attach a file from the app's uploads folder to a file input by node id.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
node_id | integer | có | |
path | string | có |
GET /v1/datasets
List datasets with their columns and row counts by state; never row values.
POST /v1/datasets
Create a fixed or consume dataset from columns and rows; bad rows are reported by number.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
columns | object[] | có | |
mode | string | có | |
name | string | có | |
rows | object[] | không | One object per row, keyed by column name; every value must be a string — convert numbers and dates to text before sending |
rows_per_run | integer | không |
GET /v1/datasets/:id/rows
Read a dataset's rows by page (query offset, limit); secret columns are never returned.
POST /v1/datasets/:id/rows
Append rows to a dataset; bad rows are reported by number.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
rows | object[] | có | One object per row, keyed by column name; every value must be a string — convert numbers and dates to text before sending |
POST /v1/datasets/:id/assign
Assign a dataset to profiles, into the slot its mode implies; a taken slot is refused unless force.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
force | boolean | không | |
profile_ids | string[] | có |
POST /v1/datasets/:id/unassign
Remove a dataset from profiles; their fixed rows become unassigned again.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
profile_ids | string[] | có |
POST /v1/datasets/:id/reset
Return every used row of a consume dataset to available.
OpenAPI
Phần tiêu đề “OpenAPI”GET /v1/openapi.json trả về tài liệu OpenAPI 3.1 mô tả API này (cũng cần token như mọi route khác). Trang API & MCP còn có nút Copy OpenAPI JSON nếu bạn không muốn tự curl.