API · Markedfile

API

Đánh dấu và phát hiện tệp bằng API Markedfile. Có trên gói Business và Enterprise.

Khóa API

Chủ không gian làm việc Business hoặc Enterprise tạo và thu hồi khóa trong cài đặt không gian. Khóa chỉ được hiển thị một lần. Markedfile lưu bản tóm tắt SHA-256, tiền tố ngắn, và một tên. Bí mật không được lưu.

Khóa thuộc đúng một không gian. Khóa chỉ hoạt động ở đó, với giới hạn gói của không gian đó. Không gian cá nhân không có khóa. Thành viên không phải chủ không thể tạo hoặc thu hồi khóa.

Khi không gian mất gói Business hoặc Enterprise đang hoạt động, mọi khóa lập tức không còn hoạt động, ngay cả khi tệp hiện có vẫn có thể phát hiện trong ứng dụng trong 30 ngày. Khi trở lại gói Business hoặc Enterprise, khóa bạn chưa thu hồi hoạt động lại.

Xác thực

Gửi bí mật dưới dạng token Bearer trên header Authorization. Đường này không dùng cookie phiên. Trình duyệt từ trang khác bị từ chối.

Kiểm toán

Việc tạo, thu hồi, đánh dấu, và phát hiện ghi một dòng kiểm toán mà chủ không gian có thể đọc. Dòng đó không chứa tệp.

MCP từ xa

MCP từ xa cần gói Business hoặc Enterprise đang hoạt động trên không gian bạn cấp.

Dán URL đầu nối vào máy khách nói MCP qua Streamable HTTP. Markedfile đăng nhập bằng cùng tài khoản, gồm SSO và ứng dụng xác thực, rồi hỏi ứng dụng được dùng không gian nào. https://markedfile.com/api/mcp

Máy khách tự đăng ký, dùng PKCE và nhận mã truy cập ngắn hạn cho không gian đó. Thu hồi kết nối cạnh khóa API. Không có CLI cho tệp.

Claude

Trên claude.ai, mở Cài đặt, rồi Đầu nối, và thêm đầu nối tùy chỉnh. Trong Claude Desktop, mở Cài đặt, rồi Đầu nối, và thêm đầu nối tùy chỉnh.
Dán URL đầu nối. Để máy khách hoàn tất đăng nhập trong trình duyệt.
Đăng nhập Markedfile, qua SSO hoặc ứng dụng xác thực nếu tài khoản dùng chúng, và chọn không gian.

Cursor

Mở cài đặt Cursor, rồi MCP, và thêm máy chủ.
Chọn Streamable HTTP và dán URL đầu nối.
Hoàn tất đăng nhập trình duyệt và chọn không gian. Cursor lưu mã làm mới tại máy.

VS Code

Trong VS Code, chạy MCP: Add Server từ bảng lệnh, hoặc thêm máy chủ HTTP trong mcp.json.
Đặt loại là http và URL là URL đầu nối.
Hoàn tất đăng nhập trình duyệt và chọn không gian.

ChatGPT

Trong ChatGPT, mở Cài đặt rồi Đầu nối. Chế độ nhà phát triển cũng có thể thêm đầu nối hoặc ứng dụng tùy chỉnh.
Thêm URL đầu nối và bắt đầu đăng nhập.
Đăng nhập Markedfile và chọn không gian. Đánh dấu và phát hiện chỉ chạy khi không gian đó là Business hoặc Enterprise.

Grok Bot

Trong Grok Bot, hãy nhắn bot trong cuộc trò chuyện thêm đầu nối với URL https://markedfile.com/api/mcp.
Ủy quyền tài khoản Markedfile trên màn hình OAuth vừa mở.

Endpoint

POST`/api/v1/mark`

Đánh dấu một tệp và trả về bản sao đã đánh dấu. Nội dung yêu cầu là multipart/form-data.

Xác thực

Authorization: Bearer mf_…

Gửi dòng header này. Không có cookie phiên. curl và máy khách máy chủ khác được chấp nhận. Trình duyệt từ trang khác bị từ chối.

Tham số

Tên	Loại	Bắt buộc	Giải thích
file	file	Có	Tệp sẽ đánh dấu. Business nhận tối đa 100 MB, 500 trang PDF, và video tối đa 10 phút. Ở Enterprise, kích thước tệp, số trang PDF, độ dài video và kích thước tệp video là Tùy chỉnh. Kích thước tải lên, thời lượng video, và số trang PDF theo gói của không gian làm việc.
identifier	string	Có	1–32 ký tự, không có ký tự điều khiển. Đây là nhãn bạn thấy khi bản sao này sau đó được phát hiện. Không được ghi vào tệp dưới dạng văn bản có thể đọc.

Yêu cầu

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

Phản hồi

{
  "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 là byte đã đánh dấu ở dạng base64. mime, name, và kind mô tả bản tải xuống. layers cho thấy lớp được dùng. Nếu gói không giới hạn tệp đang hoạt động, remaining là số tệp đang hoạt động sau dấu này. Nếu có giới hạn, remaining là số dấu mới còn lại. Business và Enterprise không giới hạn tệp đang hoạt động. Xóa tệp kết thúc phát hiện.

Lỗi

Văn bản ở cột error trong phản hồi JSON là tiếng Anh.

Trạng thái	Giải thích
400	Tệp trống, hoặc mã định danh trống, dài hơn 32 ký tự, hoặc chứa ký tự điều khiển.
401	Khóa không có, khóa đã thu hồi, hoặc không được nhận ra. Phản hồi JSON chứa "code": "api-key".
403	Không gian làm việc không còn gói Business hoặc Enterprise đang hoạt động (phản hồi chứa "code": "enterprise") hoặc trình duyệt gửi yêu cầu cross-site hoặc same-site.
413	Tệp vượt giới hạn tải lên của gói, hoặc PDF có nhiều trang hơn mức gói cho phép.
422	Tệp không thể xử lý.
503	Máy chủ đang bận, hoặc việc đánh dấu tạm dừng để bảo trì.
429	Khóa này đánh dấu hơn 40 tệp trong cùng một phút.

Giới hạn lệnh gọi

40 yêu cầu mỗi phút cho khóa này. Bộ đếm nằm trong cơ sở dữ liệu sản phẩm và vẫn còn sau khi khởi động lại.

POST`/api/v1/detect`

Kiểm tra tệp trong không gian làm việc thuộc khóa này. Nội dung yêu cầu là multipart/form-data.

Xác thực

Authorization: Bearer mf_…

Gửi dòng header này. Không có cookie phiên. curl và máy khách máy chủ khác được chấp nhận. Trình duyệt từ trang khác bị từ chối.

Tham số

Tên	Loại	Bắt buộc	Giải thích
file	file	Có	Tệp sẽ kiểm tra. Khớp chỉ được tìm trong không gian thuộc khóa này. Tệp đánh dấu ở không gian khác không được nhận ra. Không gian Business hoặc Enterprise đang hoạt động cũng có thể kiểm tra tệp video. Ảnh một khung hình được kiểm tra bằng hình ảnh.

Yêu cầu

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

Phản hồi

{
  "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 là mã định danh bạn ghi khi bản sao được đánh dấu, hoặc null nếu không có khớp trong không gian này. confidence là 99% trên tệp nguyên vẹn hoặc khi dấu đã xác thực khớp với dấu khác. Chỉ khớp hình ảnh thì vẫn thấp hơn. layers cho thấy lớp và hit thành true trên lớp khớp. notes giải thích việc kiểm tra đã làm gì. Tệp đã xóa không được nhận ra.

Lỗi

Văn bản ở cột error trong phản hồi JSON là tiếng Anh.

Trạng thái	Giải thích
400	Tệp trống.
401	Khóa không có, khóa đã thu hồi, hoặc không được nhận ra. Phản hồi JSON chứa "code": "api-key".
403	Không gian làm việc không còn gói Business hoặc Enterprise đang hoạt động (phản hồi chứa "code": "enterprise") hoặc trình duyệt gửi yêu cầu cross-site hoặc same-site.
413	Tệp vượt giới hạn tải lên của gói, hoặc PDF có nhiều trang hơn mức gói cho phép.
422	Tệp không thể xử lý.
503	Máy chủ đang bận, hoặc việc đánh dấu tạm dừng để bảo trì.
429	Khóa này thực hiện hơn 80 lần phát hiện trong cùng một phút.

Giới hạn lệnh gọi

80 yêu cầu mỗi phút cho khóa này. Bộ đếm nằm trong cơ sở dữ liệu sản phẩm và vẫn còn sau khi khởi động lại.

Khóa API

Xác thực

Kiểm toán

MCP từ xa

Claude

Cursor

VS Code

ChatGPT

Grok Bot

POST/api/v1/mark

Xác thực

Tham số

Yêu cầu

Phản hồi

Lỗi

Giới hạn lệnh gọi

POST/api/v1/detect

Xác thực

Tham số

Yêu cầu

Phản hồi

Lỗi

Giới hạn lệnh gọi

POST`/api/v1/mark`

POST`/api/v1/detect`