API

API

用 Markedfile API 標記並檢查檔案。可在 Business 與 Enterprise 方案使用。

API 金鑰

Business 或 Enterprise 工作區的擁有者在工作區設定建立並撤銷金鑰。金鑰只顯示一次。Markedfile 儲存 SHA-256 雜湊、短前綴與名稱。不儲存密鑰。

金鑰恰好屬於一個工作區。它只在那個工作區運作，並受那個工作區方案的限制。個人工作區沒有金鑰。不是擁有者的成員不能建立或撤銷金鑰。

工作區失去有效的 Business 或 Enterprise 方案時，所有金鑰會立刻停止運作。即使既有檔案在應用程式裡還能偵測 30 天，也是如此。回到 Business 或 Enterprise 後，沒有撤銷的金鑰會再運作。

驗證

在 Authorization 標頭把密鑰當成 Bearer 權杖送出。這條路徑不使用工作階段 cookie。其他頁面的瀏覽器會被拒絕。

稽核

建立、撤銷、標記與偵測會寫下工作區擁有者可以讀的稽核列。那些列不含檔案。

端點

POST/api/v1/mark

在檔案上標記，並交回標記後的副本。本文是 multipart/form-data。

驗證

Authorization: Bearer mf_…

請送出這一行標頭。沒有工作階段 cookie。curl 與其他伺服器用戶端可以。其他頁面的瀏覽器會被拒絕。

參數

名稱類型必填說明
filefile是要標記的檔案。Business 與 Enterprise 接受最多 100 MB、PDF 500 頁，以及最長 10 分鐘的影片。上傳大小、影片長度與 PDF 頁數依工作區方案。
identifierstring是1–32 個字元，不含控制字元。這份副本日後被檢查時會看到的標籤。它不會以可讀文字寫進檔案。

請求

curl -X POST https://markedfile.com/api/v1/mark \
  -H "Authorization: Bearer mf_…" \
  -F "file=@contract.pdf" \
  -F "identifier=northwind"

回應

{
  "file": "JVBERi0xLjQK…",
  "mime": "application/pdf",
  "name": "contract.pdf",
  "kind": "pdf",
  "layers": [
    {
      "name": "Metadata",
      "detail": "Authenticated workspace reference; the identifier stays on the server",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "remaining": 1
}

file 是 base64 的標記後位元組。mime、name 與 kind 說明下載檔。layers 顯示寫入的層。方案若沒有有效檔案上限，remaining 是這次標記之後的有效檔案數。若有上限，remaining 是剩下的新標記數。Business 與 Enterprise 沒有有效檔案上限。刪除檔案就結束偵測。

錯誤

JSON 回應裡 error 欄位的文字是英文。

狀態說明
400檔案是空的，或識別碼是空的、超過 32 個字元，或含有控制字元。
401金鑰不存在、已撤銷，或無法辨識。JSON 回應含有 "code": "api-key"。
403工作區沒有有效的 Business 或 Enterprise 方案（回應含有 "code": "enterprise"）。或者瀏覽器送出了 cross-site 或 same-site 請求。
413檔案超過方案的上傳上限，或 PDF 頁數多於方案上限。
422無法處理檔案。
429這把金鑰在目前這一分鐘內標記了超過 40 個檔案。

呼叫上限

這把金鑰每分鐘 40 次。計數存在產品資料庫，重新啟動後仍在。

POST/api/v1/detect

在這把金鑰的工作區檢查檔案。本文是 multipart/form-data。

驗證

Authorization: Bearer mf_…

請送出這一行標頭。沒有工作階段 cookie。curl 與其他伺服器用戶端可以。其他頁面的瀏覽器會被拒絕。

參數

名稱類型必填說明
filefile是要檢查的檔案。相符只在這把金鑰的工作區尋找。在其他工作區標記的檔案不會被辨出。有效的 Business 或 Enterprise 工作區也可以檢查影片檔。單幀的螢幕截圖會當成圖片檢查。

請求

curl -X POST https://markedfile.com/api/v1/detect \
  -H "Authorization: Bearer mf_…" \
  -F "file=@leaked.pdf"

回應

{
  "id": "northwind",
  "confidence": 0.95,
  "layers": [
    {
      "name": "Metadata",
      "hit": true,
      "detail": "Authenticated metadata matched this workspace",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "notes": [
    "Confidence is 99% for an exact file or when an authenticated mark agrees with another mark. A visual match alone stays lower, and weak bit agreement stays far from a high score."
  ]
}

id 是標記副本時指定的識別碼。這個工作區沒有相符時是 null。檔案完全相同，或已驗證的標記與另一個標記一致時，confidence 是 99%。只有視覺相符會較低。layers 顯示各層，相符層的 hit 是 true。notes 說明這次檢查做了什麼。已刪除的檔案不會被辨出。

錯誤

JSON 回應裡 error 欄位的文字是英文。

狀態說明
400檔案是空的。
401金鑰不存在、已撤銷，或無法辨識。JSON 回應含有 "code": "api-key"。
403工作區沒有有效的 Business 或 Enterprise 方案（回應含有 "code": "enterprise"）。或者瀏覽器送出了 cross-site 或 same-site 請求。
413檔案超過方案的上傳上限，或 PDF 頁數多於方案上限。
422無法處理檔案。
429這把金鑰在目前這一分鐘內做了超過 80 次偵測。

呼叫上限

這把金鑰每分鐘 80 次。計數存在產品資料庫，重新啟動後仍在。