API

API

Markedfile の API でファイルをマークし、検出します。Business と Enterprise で使えます。

API キー

Business または Enterprise ワークスペースの所有者は、ワークスペース設定でキーを作成し、失効させます。キーは一度だけ表示されます。Markedfile が保存するのは SHA-256 ハッシュ、短い接頭辞、名前です。秘密は保存しません。

キーはちょうど 1 つのワークスペースに属します。そのワークスペースのプラン上限の中で、そこでだけ動作します。個人ワークスペースにキーはありません。所有者でないメンバーは作成も失効もできません。

ワークスペースが有効な 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 分までの動画を受け付けます。サイズ、長さ、ページ数はワークスペースのプランに従います。
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このキーは現在の 1 分間に 40 件を超えるファイルをマークしました。

制限

このキーは 1 分に 40 リクエストです。カウンターは製品のデータベースに保存され、再起動後も残ります。

POST/api/v1/detect

このキーのワークスペースに対してファイルを調べます。本文は multipart/form-data です。

認証

Authorization: Bearer mf_…

このヘッダーを送ります。セッション Cookie はありません。curl と他のサーバークライアントは受け付けます。別のサイトのブラウザは拒否されます。

パラメーター

名前型必須説明
filefileはい調べるファイルです。検索はこのキーのワークスペースだけです。別のワークスペースでマークしたファイルは解決しません。有効な Business または Enterprise ワークスペースは動画ファイルも調べられます。1 フレームのスクリーンショットは画像として調べます。

リクエスト

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このキーは現在の 1 分間に 80 件を超える検出を実行しました。

制限

このキーは 1 分に 80 リクエストです。カウンターは製品のデータベースに保存され、再起動後も残ります。