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}/flowsflows:readList flows
GET/guilds/{guildId}/flows/runs/{executionId}flows:readGet a flow run
POST/guilds/{guildId}/flows/{workflowId}/runsflows:runRun a flow

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

List flows

GET/guilds/{guildId}/flows

範圍: flows:read

需要在伺服器上啟用此功能: 流程

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].namestring是
items[].descriptionstring | null是
items[].enabledboolean是
items[].triggerTypestring | null是e.g. trigger.manual, trigger.webhook, trigger.discord.messageCreated
items[].runnableboolean是Can be run with POST …/runs (enabled + Manual or Webhook trigger)
items[].updatedAtstring | null是
回應 · 200
{
  "items": [
    {
      "id": 98765,
      "name": "Example",
      "description": "example",
      "enabled": true,
      "triggerType": "example",
      "runnable": true,
      "updatedAt": "2026-10-07T12:00:00.000Z"
    }
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/flows" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Get a flow run

GET/guilds/{guildId}/flows/runs/{executionId}

範圍: flows:read

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是

回應

回應欄位 · 200
欄位類型必填說明
executionIdinteger是
workflowIdinteger是
statusstring是running | success | error | stopped | cancelled
outputany | null是The last node’s output (finished runs only)
errorstring | null是
startedAtstring | null是
finishedAtstring | null是
durationMsinteger | null是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/flows/runs/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Run a flow

POST/guilds/{guildId}/flows/{workflowId}/runs

範圍: flows:run敏感Idempotency-Key

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
inputany否Trigger data (any JSON): $trigger for Manual flows, $trigger.body for Webhook flows
waitboolean否Wait for the run to finish (default false → 202 right after it started)
timeoutSecondsinteger否Longest wait; default = the flow timeout + 5 s
1–120

回應

回應欄位 · 202
欄位類型必填說明
executionIdinteger是
workflowIdinteger是
statusstring是running | success | error | stopped | cancelled
outputany | null是The last node’s output (finished runs only)
errorstring | null是
startedAtstring | null是
finishedAtstring | null是
durationMsinteger | null是
回應 · 202
{
  "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
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}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。