# API 參考

HakoRun 三個 HTTP 端點的請求欄位與狀態碼；回應格式見 [回應與 SSE](/zh/responses)。

## POST /upload

儲存函式並產生新版本。

| 欄位 | 型別 | 必要 | 說明 |
|------|------|------|------|
| `path` | `string` | 是 | 函式路徑，不可含 `..` |
| `code` | `string` | 是 | 原始碼 |
| `language` | `string` | 是 | `python`、`javascript`、`typescript` |

| 狀態碼 | 內容 | 情境 |
|--------|------|------|
| `200` | `{"path", "language", "version"}` | 儲存成功 |
| `400` | `Invalid request payload` | 缺欄位或 JSON 錯誤 |
| `400` | `Invalid path` | `path` 含 `..`，或 `language` 不支援（同一訊息） |
| `500` | `Failed to save function` | 儲存後端寫入失敗 |

## POST /run/*path

執行已儲存的函式。body 必須是 JSON；沒有輸入時傳 `{}`。

| 參數 | 位置 | 型別 | 說明 |
|------|------|------|------|
| `version` | query | `int64` | 目標版本；省略或非整數時取最新 |
| `input` | body | `string` | JSON 字串，腳本內為 `event`／`input` |
| `stream` | body | `bool` | `true` 時以 SSE 回應 |

| 狀態碼 | 情境 |
|--------|------|
| `200` | 執行成功（JSON 或 SSE） |
| `400` | body 不是合法 JSON，或超過 `CODE_MAX_SIZE` |
| `404` | `script not found`、`assign version not found` |
| `500` | 非串流模式執行失敗或逾時（`failed to run: ...`） |

## POST /run-now

不儲存，直接執行請求中的程式碼。

| 欄位 | 型別 | 必要 | 說明 |
|------|------|------|------|
| `code` | `string` | 是 | 原始碼，不可為空白 |
| `language` | `string` | 是 | `python`、`javascript`、`typescript` |
| `input` | `string` | 否 | JSON 字串輸入 |
| `stream` | `bool` | 否 | `true` 時以 SSE 回應 |

| 狀態碼 | 情境 |
|--------|------|
| `200` | 執行成功（JSON 或 SSE） |
| `400` | body 錯誤、`unsupported language`、`code is required` |
| `500` | 非串流模式執行失敗或逾時 |

## 相關頁面

- [回應與 SSE](/zh/responses)
- [核心概念](/zh/core-concepts)