API 參考文件

基礎網址

所有端點均在 https://freehire.me/api/v1 下提供服務。 API 是先讀且開放的：職缺、搜尋、facet 和公司端點不需要驗證，可以稱為跨來源。

經過驗證的端點接受瀏覽器工作階段 cookie（透過登入設置，同源）或作為承載權杖發送的個人 API 金鑰 - 請參閱下面的驗證和 API 金鑰。

回應格式

單一項目包裝為 { "data": ... }。集合新增分頁中繼資料：{ "data": [...], "meta": { "total", "limit", "offset" } }。錯誤是具有匹配 HTTP 狀態的 { "error": "message" }。

{ "data": { "...": "single item" } }

{ "data": [ ... ], "meta": { "total": 4213, "limit": 20, "offset": 0 } }

{ "error": "job not found" }

分頁

使用 limit（預設 20，最多 100）和 offset（預設 0）列出和搜尋端點頁面。 meta.total 會報告目前篩選器符合的總數，因此您可以計算頁數。

搜尋分頁有界：offset + limit 不得超過 10000 (pagination too deep → 400)。這是深度分頁保護，而不是報告總數的上限——使用篩選條件來縮小範圍，而不是分頁那麼遠。

錯誤

錯誤使用標準 HTTP 狀態代碼：400（錯誤請求/無效值）、401（缺少或無效憑證）、403（已驗證但不允許，例如非審核者）、404（沒有此類職缺、公司或擁有的資源）和 503（搜尋暫時不可用）。主體始終為 { "error": ... }。

驗證方式

瀏覽器用戶端使用登入時設定的 HttpOnly 工作階段 cookie 進行驗證（同源；SPA 無法讀取它）。非瀏覽器用戶端使用個人 API 金鑰作為 Authorization: Bearer <token>。

標記為「工作階段或 API 金鑰」的端點接受其中之一；標記為「僅限工作階段」的端點（API 金鑰管理、儲存的搜尋、訂閱）僅接受 cookie，因此洩漏的金鑰無法管理憑證。 「審核人員」端點還需要審核人員角色。

本文件不包含的內容

This reference covers every endpoint you can call. A handful are deliberately left out because calling them directly is meaningless: the Gmail and calendar consent redirects (/me/gmail/connect, /me/calendar/connect, and their callbacks), which only a browser can complete; the Telegram bot webhook and the Discord interaction webhook; the browser-tool websocket relay; the sitemap-cursor helpers behind /sitemap.xml; and the /og/*.png social-preview cards, which render an image rather than answer with JSON.

/jobs/{slug}/fit 端點是 /jobs/{slug}/match-analysis 的預重命名別名，並且命中相同的處理程序。它們仍然有效，因此現有客戶端不會中斷 - 在新程式碼中使用匹配分析路徑。

該 API 的大部分也是 CLI。如果您正在編寫代理程式而不是集成，freehire 可以透過一個 API 金鑰以更少的儀式覆蓋相同的表面 - 搜尋、追蹤、收件匣和履歷自訂。