REST API v1 · 開發者 · API 參考
流程 API 參考
BotGG REST API v1 的所有 3 個 流程 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。
開發者文件
本頁目錄
端點
路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。
| 端點 | 範圍 | 說明 |
|---|---|---|
GET/guilds/{guildId}/flows | flows:read | List flows |
GET/guilds/{guildId}/flows/runs/{executionId} | flows:read | Get a flow run |
POST/guilds/{guildId}/flows/{workflowId}/runs | flows:run | Run a flow |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
List flows
GET/guilds/{guildId}/flows
需要在伺服器上啟用此功能: 流程
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | 是 | |
items[].name | string | 是 | |
items[].description | string | null | 是 | |
items[].enabled | boolean | 是 | |
items[].triggerType | string | null | 是 | e.g. trigger.manual, trigger.webhook, trigger.discord.messageCreated |
items[].runnable | boolean | 是 | Can be run with POST …/runs (enabled + Manual or Webhook trigger) |
items[].updatedAt | string | null | 是 |
{
"items": [
{
"id": 98765,
"name": "Example",
"description": "example",
"enabled": true,
"triggerType": "example",
"runnable": true,
"updatedAt": "2026-10-07T12:00:00.000Z"
}
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/flows" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/flows', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/flows",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get a flow run
GET/guilds/{guildId}/flows/runs/{executionId}
Status of a run (any run of this server’s flows); output is the last node’s output once it finished.
需要在伺服器上啟用此功能: 流程
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
executionId | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
executionId | integer | 是 | |
workflowId | integer | 是 | |
status | string | 是 | running | success | error | stopped | cancelled |
output | any | null | 是 | The last node’s output (finished runs only) |
error | string | null | 是 | |
startedAt | string | null | 是 | |
finishedAt | string | null | 是 | |
durationMs | integer | null | 是 |
{
"executionId": 98765,
"workflowId": 98765,
"status": "example",
"output": null,
"error": "example",
"startedAt": "2026-10-07T12:00:00.000Z",
"finishedAt": "2026-10-07T12:00:00.000Z",
"durationMs": 10
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/flows/runs/234567890123456789" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/flows/runs/234567890123456789', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/flows/runs/234567890123456789",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | FLOW_EXECUTION_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Run a flow
POST/guilds/{guildId}/flows/{workflowId}/runs
Only enabled flows with a Manual or Webhook trigger. A Webhook flow runs as if its webhook URL was called with input as the JSON body. Counts toward the plan’s daily runs. 202 { executionId, status: "running" }, or with wait: true 200 with the final status and output (202 when it is still running after the timeout — poll GET …/flows/runs/{executionId}).
需要在伺服器上啟用此功能: 流程
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
workflowId | 路徑 | string | 是 | |
Idempotency-Key | 標頭 | string | 否 | 選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
input | any | 否 | Trigger data (any JSON): $trigger for Manual flows, $trigger.body for Webhook flows |
wait | boolean | 否 | Wait for the run to finish (default false → 202 right after it started) |
timeoutSeconds | integer | 否 | Longest wait; default = the flow timeout + 5 s 1–120 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
executionId | integer | 是 | |
workflowId | integer | 是 | |
status | string | 是 | running | success | error | stopped | cancelled |
output | any | null | 是 | The last node’s output (finished runs only) |
error | string | null | 是 | |
startedAt | string | null | 是 | |
finishedAt | string | null | 是 | |
durationMs | integer | null | 是 |
{
"executionId": 98765,
"workflowId": 98765,
"status": "example",
"output": null,
"error": "example",
"startedAt": "2026-10-07T12:00:00.000Z",
"finishedAt": "2026-10-07T12:00:00.000Z",
"durationMs": 10
}範例
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/flows/234567890123456789/runs" \
-H "Authorization: Bearer $BOTGG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"input":null,"wait":true,"timeoutSeconds":3600}'// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/flows/234567890123456789/runs', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
},
body: JSON.stringify({
input: null,
wait: true,
timeoutSeconds: 3600,
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os, uuid
import requests
res = requests.post(
"https://console.botgg.app/api/v1/guilds/123456789012345678/flows/234567890123456789/runs",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()), # reuse it when you retry this request
},
json={
"input": None,
"wait": True,
"timeoutSeconds": 3600,
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)