快速入門

公開讀取 API 是匿名的——每個讀取端點無需登入就會傳回專案資料，這正是專案廣場能向未登入訪客開放的原因。所有與帳戶繫結的內容都需要攜帶權杖。下面分五步，每一步都以你能親眼看到的結果收尾。

每個路徑都相對於此建置所指向的應用程式主機，如下所示。請求都是針對它寫的，所以你可以原樣複製。

https://app.motir.co

1. 產生權杖

在「設定」→「帳戶」→「權杖」中產生一個個人存取權杖，選擇它所繫結的工作區，並授予它所需的權限——與「角色與權限」介面顯示的是同樣的 resource:action 名稱。請授予能完成工作的最窄集合：授權只會收窄你自己的角色而不會放寬，所以權杖不能做你本人做不到的事。

金鑰只在建立權杖時顯示一次。 請當時就複製；之後無法再次讀取，遺失的權杖只能替換，無法找回。

2. 你的第一次認證呼叫

請先發出這個呼叫。它會回答權杖是誰、繫結到哪個工作區，以及它究竟帶有哪些權限——這樣你無需逐個端點試探、收集一堆拒絕，就能知道自己的憑證可以做什麼。

curl https://app.motir.co/api/v1/me \
  -H "Authorization: Bearer $MOTIR_TOKEN"

{
  "user": { "id": "usr_…", "name": "Ada", "email": "ada@example.com" },
  "workspaceId": "wsp_…",
  "permissions": ["project:browse"]
}

權杖缺失、格式錯誤、未知、已撤銷或已過期，都會傳回同樣的 401 和同樣的訊息。這是有意為之：如果區分它們，端點就會變成一個能回答「這個金鑰是否存在？」的探測器。

3. 對集合分頁

集合採用遊標分頁。用 limit 指定頁面大小（預設是 50，超過 100 的值會被限制為 100，而不是被拒絕），然後把上一次回應中的 nextCursor 作為 cursor 發回。nextCursor 為 null 表示這是最後一頁。

curl "https://app.motir.co/api/v1/projects/MOTIR/work-items?limit=2" \
  -H "Authorization: Bearer $MOTIR_TOKEN"

{
  "items": [ { "key": "MOTIR-1", … }, { "key": "MOTIR-2", … } ],
  "nextCursor": "eyJjIjoid29ya0l0ZW1zIiwicCI6…"
}

curl "https://app.motir.co/api/v1/projects/MOTIR/work-items?limit=2&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOTIR_TOKEN"

遊標是不透明且經過簽名的。不要解析它、自行構造，也不要在不同集合之間沿用——在別處簽發的遊標會得到 422，而絕不會悄悄傳回一個錯誤的頁面。請原樣發回你拿到的內容。

有一處不對稱常讓人意外，值得在遇到之前先知道：有些集合還會報告 totalCount，而大多數有意不報告。當某個集合背後的讀取本來就以有界聚合的方式算出了總數時，才會報告它；否則這個欄位會被整個省略——是缺失，絕不是 null，也絕不是 0，因此用戶端總能區分「沒有承諾提供總數」和「總數為零」。

4. 讀懂錯誤

每次失敗都傳回相同的回應本文：機器可讀的 code 和面向人的 error。請根據 code 分支處理——它是穩定的，更改它屬於破壞性變更。絕不要解析 error；它是寫給在終端機前閱讀的開發者的一句話，可以隨意改寫。

{ "code": "WORK_ITEM_NOT_FOUND", "error": "Work item not found." }

404 表示資源不存在 或者 位於你的權杖所繫結的工作區之外——這是有意給出同樣的回答，這樣就無法利用 API 去列舉其他租戶的資料。403 則是相反的一類拒絕：你的權杖有效，但它的授權缺少這個操作所需的權限，回應中會指明該權限的鍵。422 是你可以修正的請求，它的 code 會指出是哪個部分。

500 是唯一沒有 code 的失敗。 意外故障沒有穩定的契約，所以回應本文只帶一條訊息，別無其他——不要據此分支處理。

5. 讀取回應標頭

額度是按權杖計算的，而且這些回應標頭會出現在每一個回應中——無論是成功、拒絕、已對應的錯誤還是故障。你無需專門發出請求來檢視自己的處境；上一個請求已經告訴了你。

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 594
X-RateLimit-Reset:     1785312000
X-Request-Id:          c7771231-e18c-48bc-90c9-c1a9720436a4
X-Motir-Api-Version:   1.74.0

遇到 429 時，請退避到 X-RateLimit-Reset——這是以秒為單位的 Unix 時間戳記。這裡有意沒有 Retry-After 回應標頭：絕對時刻不會像相對時長那樣在傳輸途中過時。

X-Request-Id 也在每個回應中。如果你需要就某個具體呼叫向我們諮詢，請引用它——它是能找到該呼叫的唯一識別碼。

X-Motir-Api-Version 是服務該回應的契約版本——採用 MAJOR.MINOR.PATCH 格式，與規格中的 info.version 相同，而不是我們的釋出版本號。可以從任何回應（包括失敗的回應）中讀取它，以檢查版本偏差。如果出現你不認識的 MAJOR，說明已有 /api/v2；更高的 MINOR 則表示契約以增量方式擴充了，你的用戶端依然正確。如果上面的區塊顯示的是預留位置而不是版本號，說明轉譯本頁時規格無法存取，此時 API 參考會直接從文件中讀取目前版本。

下一步

API 參考列出每個操作及其參數、請求本文和狀態。穩定性與棄用說明了該契約承諾不會對你做的事。如果你要串接的是代理程式而不是撰寫用戶端，MCP 伺服器是另一半。