API
API
علّم الملفات واكشفها بواجهة API في Markedfile. متاحة فقط على خطتي Business و Enterprise.
مفاتيح API
ينشئ مالك مساحة عمل Business أو Enterprise المفاتيح ويلغيها في إعدادات مساحة العمل. يُعرض المفتاح مرة واحدة. يخزّن Markedfile تجزئة SHA-256 وبادئة قصيرة والاسم. لا يخزّن السر.
ينتمي المفتاح إلى مساحة عمل واحدة بالضبط. يعمل هناك فقط، بحدود خطة تلك المساحة. مساحات العمل الشخصية ليس لها مفاتيح. العضو الذي ليس المالك لا يستطيع إنشاءها أو إلغاءها.
إذا فقدت مساحة العمل خطة Business أو Enterprise النشطة، تتوقف كل المفاتيح عن العمل فوراً، بما في ذلك خلال الأيام الثلاثين التي تبقى فيها الملفات الحالية قابلة للكشف في التطبيق. العودة إلى Business أو Enterprise تعيد عمل المفاتيح التي لم تُلغَ.
المصادقة
أرسل السر في ترويسة Authorization كرمز Bearer. هذه المسارات لا تستخدم ملف تعريف ارتباط للجلسة. يُرفض متصفح على موقع آخر.
التدقيق
الإنشاء والإلغاء والتعليم والكشف تكتب صف تدقيق يستطيع مالك مساحة العمل قراءته. الصف لا يتضمن الملف.
MCP البعيد
يتطلب MCP البعيد خطة Business أو Enterprise نشطة في مساحة العمل التي تمنحها.
الصق عنوان الموصل في عميل يتحدث MCP عبر Streamable HTTP. يسجّل Markedfile دخولك بالحساب نفسه، بما في ذلك SSO وتطبيق المصادقة، ثم يسأل أي مساحة يمكن للتطبيق استخدامها. https://markedfile.com/api/mcp
يسجّل العميل نفسه، ويستخدم PKCE، ويتلقى رمز وصول قصير العمر لتلك المساحة. ألغِ الاتصال بجانب مفاتيح API. لا توجد واجهة سطر أوامر للملفات.
Claude
- في claude.ai افتح الإعدادات ثم الموصلات وأضف موصلاً مخصصًا. في Claude Desktop افتح الإعدادات ثم الموصلات وأضف موصلاً مخصصًا.
- الصق عنوان الموصل. دع العميل يُكمل تسجيل الدخول في المتصفح.
- سجّل الدخول في Markedfile، مع SSO أو تطبيق المصادقة إذا كان الحساب يستخدمهما، واختر مساحة العمل.
Cursor
- افتح إعدادات Cursor ثم MCP وأضف خادمًا.
- اختر Streamable HTTP والصق عنوان الموصل.
- أكمل تسجيل الدخول في المتصفح واختر مساحة العمل. يحتفظ Cursor برمز التحديث محليًا.
VS Code
- في VS Code شغّل MCP: Add Server من لوحة الأوامر، أو أضف خادم HTTP في mcp.json.
- اضبط النوع على http والعنوان على عنوان الموصل.
- أكمل تسجيل الدخول في المتصفح واختر مساحة العمل.
ChatGPT
- في ChatGPT افتح الإعدادات ثم الموصلات. يمكن لوضع المطوّر أيضًا إضافة موصل أو تطبيق مخصص.
- أضف عنوان الموصل وابدأ تسجيل الدخول.
- سجّل الدخول في Markedfile واختر مساحة العمل. يعمل التعليم والاكتشاف فقط ما دامت المساحة Business أو Enterprise.
Grok Bot
- في Grok Bot، اطلب من روبوتك في الدردشة إضافة موصل بالعنوان https://markedfile.com/api/mcp.
- فوّض حساب Markedfile على شاشة OAuth التي تُفتح.
المسارات
POST/api/v1/mark
يعلّم ملفاً ويعيد النسخة المعلَّمة. الجسم بصيغة multipart/form-data.
المصادقة
Authorization: Bearer mf_…أرسل هذه الترويسة. لا يوجد ملف تعريف ارتباط للجلسة. يُقبل curl وعملاء الخادم الآخرون. يُرفض متصفح على موقع آخر.
المعاملات
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| file | file | نعم | الملف المراد تعليمه. تقبل Business حتى 100 MB، و500 صفحة PDF، وفيديو حتى 10 دقائق. في Enterprise، حجم الملف وصفحات PDF ومدة الفيديو وحجم ملف الفيديو مخصص. يتبع حجم الرفع ومدة الفيديو وعدد صفحات PDF خطة مساحة العمل. |
| identifier | string | نعم | من 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 حد للملفات النشطة. حذف الملف هو ما ينهي الكشف.
الأخطاء
حقل error في جسم JSON بالإنجليزية.
| الحالة | الوصف |
|---|---|
| 400 | الملف فارغ، أو المعرّف فارغ أو أطول من 32 محرفاً أو يحتوي محرف تحكم. |
| 401 | المفتاح مفقود أو ملغى أو غير معروف. يتضمن جسم JSON الحقل "code": "api-key". |
| 403 | لم تعد مساحة العمل على خطة Business أو Enterprise نشطة (يتضمن الجسم "code": "enterprise")، أو أرسل المتصفح طلباً cross-site أو same-site. |
| 413 | يتجاوز الملف حد الرفع في الخطة، أو يحتوي PDF على صفحات أكثر مما تسمح به الخطة. |
| 422 | تعذّر معالجة الملف. |
| 503 | الخادم مشغول، أو الوسم متوقف للصيانة. |
| 429 | علّم هذا المفتاح أكثر من 40 ملفاً في الدقيقة الحالية. |
حد المعدل
40 طلباً في الدقيقة لهذا المفتاح. يُخزَّن العداد في قاعدة بيانات المنتج ويبقى بعد إعادة التشغيل.
POST/api/v1/detect
يفحص ملفاً ضمن مساحة عمل هذا المفتاح. الجسم بصيغة multipart/form-data.
المصادقة
Authorization: Bearer mf_…أرسل هذه الترويسة. لا يوجد ملف تعريف ارتباط للجلسة. يُقبل curl وعملاء الخادم الآخرون. يُرفض متصفح على موقع آخر.
المعاملات
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| file | file | نعم | الملف المراد فحصه. يُبحث عن التطابق في مساحة عمل هذا المفتاح فقط. الملف المعلَّم في مساحة عمل أخرى لا يُحل. يمكن لمساحة عمل 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 ما فعله الفحص. الملف المحذوف لا يُحل.
الأخطاء
حقل error في جسم JSON بالإنجليزية.
| الحالة | الوصف |
|---|---|
| 400 | الملف فارغ. |
| 401 | المفتاح مفقود أو ملغى أو غير معروف. يتضمن جسم JSON الحقل "code": "api-key". |
| 403 | لم تعد مساحة العمل على خطة Business أو Enterprise نشطة (يتضمن الجسم "code": "enterprise")، أو أرسل المتصفح طلباً cross-site أو same-site. |
| 413 | يتجاوز الملف حد الرفع في الخطة، أو يحتوي PDF على صفحات أكثر مما تسمح به الخطة. |
| 422 | تعذّر معالجة الملف. |
| 503 | الخادم مشغول، أو الوسم متوقف للصيانة. |
| 429 | أجري هذا المفتاح أكثر من 80 عملية كشف في الدقيقة الحالية. |
حد المعدل
80 طلباً في الدقيقة لهذا المفتاح. يُخزَّن العداد في قاعدة بيانات المنتج ويبقى بعد إعادة التشغيل.