كيف تستخدم REST API

ربطت وكيلًا بلوحتك والآن تحتاجه أن يقرأ المهام ويكتبها دون أن ينقر أحد شيئًا. أي: احصل على مفتاح، واطرق REST API لإدارة المشاريع بالطريقة الصحيحة، ولا تلصق رمزًا في مستودع ولا تُنشئ التذاكر مرتين عند أول إعادة محاولة متعثّرة.

هذا هو المسار كاملًا في Taskfolk. افتح وحدة تحكّم المطوّر، أصدر مفتاحًا محصورًا، انسخه المرة الوحيدة الممكنة، أثبت أنه يعمل بنداء واحد، ثم اسرد المهام وأنشئها وحدّثها في مشروع حقيقي. بالإضافة إلى الأجزاء التي تتخطّاها معظم الوثائق: جعل الكتابات آمنة لإعادة المحاولة، وقراءة ترويسات حدّ المعدّل قبل أن تصطدم بجدار، والحدود الصريحة (نطاقات مجمّدة، أخطاء 401 غامضة، SDK ليست على npm بعد). المثال طوال المقالة هو مساحة العمل taskfolk ومشروعها WEB، الذي أعمدة لوحته Backlog و To Do و In Progress و In Review و Done.

لماذا يتفوّق REST API لإدارة المشاريع على النقر يدويًا

هناك نقطة تتوقّف عندها الواجهة عن كونها أسرع طريقة لتحريك العمل. وكيلٌ يراقب مستودعًا يريد فتح خطأ في الثانية التي يفشل فيها CI. سكربتٌ ليليّ يحتاج مزامنة تذاكر من نظام خارجيّ إلى اللوحة. إرسال نموذج ينبغي أن يقيّد مهمة من تلقاء نفسه. كلها تريد الشيء نفسه: طريقة مستقرّة قابلة للبرمجة لقراءة المهام وكتابتها. هذا ما يمنحه REST API لإدارة المشاريع، و API الخاص بـ Taskfolk هو HTTP بسيط برمز bearer.

تعلّم الشكل مرة واحدة. الرابط الأساسي هو https://taskfolk.ai/api، وكل مسار متداخل تحت /v1/workspaces/{slug}/.... لا يوجد /v1/issues على المستوى الأعلى. المهمة تعيش داخل مشروع، الذي يعيش داخل مساحة عمل، والرابط يقول ذلك:

GET /v1/workspaces/taskfolk/projects/WEB/issues
Host: taskfolk.ai
Authorization: Bearer tfk_live_a1b2...

المصادقة رمز bearer على كل طلب. هذا هو النموذج كاملًا.

REST ليس الطريقة الوحيدة للتحدّث إلى Taskfolk. هناك خادم MCP أيضًا، وهو يلائم أفضل حين يكون وكيل LLM يستدعي أدوات وتريده أن يكتشف العمليات بدل ترميز الروابط بشكل ثابت. إن كنت تختار بين الاثنين، فـMCP أم REST API لوكيلك يمشي في المفاضلة، ولماذا لدى Taskfolk خادم MCP يغطّي لماذا يشحن الاثنان معًا. هذه المقالة هي مسار REST. أنت تملك نداءات HTTP، وهو ما تريده للسكربتات ومهام cron ومزامنة الأنظمة الخارجية.

افتح وحدة تحكّم المطوّر (ولماذا هي تحت Knowledge)

كل ما يتعلّق بالمفاتيح يبدأ في وحدة تحكّم المطوّر. الرابط يجلس في الشريط الجانبي لمساحة العمل، موسومًا Developer، ويوصلك إلى /w/{workspace}/knowledge/developer. للمثال ذلك هو /w/taskfolk/knowledge/developer.

لاحظ المسار، لأنه يُعثِر الناس. تعيش وحدة التحكّم تحت قسم Knowledge، فالرابط هو /w/taskfolk/knowledge/developer، لا /w/taskfolk/developer (ذاك لا يُحلّ). و/developer بلا بادئة /w/{workspace} شيء مختلف تمامًا: الصفحة التسويقية العامة. إن لم تبدُ وحدة التحكّم كما توقّعت، فافحص أيًّا من هذه الروابط الثلاثة فتحت فعلًا.

هناك بوابة إذن هنا، وتستحقّ القول بوضوح. تحتاج وحدة التحكّم workspace.edit_settings، أي مالك أو مشرف. العضو أو المشاهد لن يرى رابط Developer إطلاقًا، وطرق الرابط مباشرةً يرتدّ بهم إلى صفحة مساحة العمل الرئيسية. فحين يقول زميل «لا أجده»، فالسؤال الأول دوره، لا إشاراته المرجعية.

عبر الأعلى يمرّ شريط علامات التبويب: Overview و API Reference و SDK و Keys و Skills و Webhooks و Apps و Usage و Audit و Marketplace. هذه علامات تبويب فورية من جانب العميل، لا تحميلات صفحات، وكلٌّ يرتبط عميقًا بمعامل استعلام. ?tab=keys يُسقطك على علامة تبويب Keys، و?tab=api-reference على المرجع. مفيد لإشارة مرجعية، أو لتوجيه زميل إلى الموضع بالضبط.

أنشئ مفتاح API محصورًا بأقلّ امتياز

اذهب إلى علامة تبويب Keys. إن لم يكن لهذه المساحة مفتاح قطّ، تحصل على جدول فارغ بالأعمدة التي ستنمو إليها (Name و Prefix و Scopes و Projects و Rate limit و Last used و Created و Status) وزر New API key.

انقر New API key فيُفتح مربّع الإنشاء. أربعة أشياء تضبطها. الأوسطان هما حيث تفعل هذا جيّدًا أو تندم عليه بعد ثلاثة أشهر.

Name. أعطه شيئًا يخبر نفسك المستقبلية لماذا هو. «CI issue bot» يتفوّق على «key1». حين تجلس ستة مفاتيح في ذلك الجدول، الاسم هو الشيء الوحيد الذي عليك أن تفكّر به، فاجعله يحمل ثقله.

Scopes. هذه قائمة مربّعات الاختيار، ووحدة التحكّم تذكر النموذج هناك مباشرةً: «Broad scopes (read, write, admin) include all specific scopes. Use specific scopes for least-privilege access.». فيمكنك أخذ read أو write الخشن، أو انتقاء أدقّ مثل issues:read وissues:write وprojects:read.

لبوت يقرأ اللوحة ويقيّد التذاكر، الجواب الصحيح هو issues:read مع issues:write. لا شيء أكثر. إن كان لا يلمس أبدًا إعدادات المشروع أو الأعضاء أو الـ webhooks، فينبغي ألّا يستطيع.

اختيار تصميميّ واحد لتعرفه: نطاق write الخشن يحبس النطاقات الخاصّة بالمشرف فقط. أشياء مثل workspaces:write وapi_keys:* وwebhooks:* وmembers:write وprojects:admin وforms:write وautomations:write غير مضمّنة. تحتاج تلك إمّا نطاق admin أو النطاق الأدقّ الصريح. فـ write فعلًا درجة «يستطيع تحرير العمل، لا يستطيع إعادة تهيئة مساحة العمل»، وهو عادةً بالضبط ما تريده للأتمتة.

Project access. خياران راديويّان: «All workspace projects» أو «Selected projects only». لمفتاح لا يلمس أبدًا إلا WEB، اختر Selected projects only وأشّر WEB. الآن إن تسرّب المفتاح، فنطاق الانفجار مشروع واحد بدل مساحة العمل كلها.

Expires at (optional). اضبطه. مفتاح يموت خلال 90 يومًا هو مفتاح لا يمكنك نسيانه إلى الأبد. لسكربت هجرة لمرة واحدة، اضبطه للأسبوع المقبل.

إليك القاعدة التي تجعل الحصر مهمًّا: النطاقات وقائمة سماح المشاريع مجمّدة عند الإنشاء. حالما يوجد المفتاح يمكنك تحرير اسمه، وتجاوز حدّ معدّله، وانتهاء صلاحيته. هذا كلّ شيء. لا يمكنك إضافة نطاق أو إضافة مشروع لاحقًا. إن نمت وظيفة البوت، تصدر مفتاحًا جديدًا بالنطاق الأوسع وتُحيل القديم للتقاعد. هذا ليس إزعاجًا، هو المقصود. سلطة المفتاح ثابتة لحظة ولادته، فلا يستطيع أحد توسيعها بهدوء.

حين يبدو المربّع صحيحًا، انقر Create key.

انسخ المفتاح مرة، لأنك لن تراه ثانيةً

الإرسال لا يعيدك إلى الجدول. يفتح مربّع الكشف، المعنون Save your API key، وهذه اللحظة الوحيدة التي يوجد فيها المفتاح النصّي على الشاشة إطلاقًا.

يقولها المربّع صريحًا: «This is the only time you will see this key.». يحتفظ Taskfolk بتجزئة SHA-256 فقط. لا يوجد زر «show key» في أي مكان في المنتج، ولا مسار دعم لاستعادته. أغلق هذا دون نسخ فيذهب المفتاح؛ تصنع جديدًا.

فانسخه الآن وضعه حيث ينتمي السرّ. مدير أسرار. سرّ CI. متغيّر بيئة في تهيئة نشرك. لا تعليق كود، لا رسالة Slack لنفسك، لا مُودَع في مستودع. كامل سبب رفض المنتج إظهاره مرتين هو دفعك نحو معاملته كالاعتماد الذي هو.

لن يدعك المربّع تغادر حتى تؤشّر I saved this key somewhere safe. وتنقر Done. ذلك المربّع احتكاك عمدًا، فرصة أخيرة للصقه فعلًا في مكان قبل أن يختفي للأبد.

مفاتيح مساحة العمل تحمل البادئة tfk_live_، فمفتاح حقيقيّ يُقرأ مثل tfk_live_a1b2.... تعرّف على تلك البادئة في السجلّات والتهيئة: تخبرك بلمحة أن هذا مفتاح محصور بمساحة عمل، مقابل رمز شخصيّ، الذي نصل إليه في النهاية.

صادق وأكّد مفتاحك بـ GET /v1/me

الآن لديك مفتاح. كل طلب يحمله كرمز bearer في ترويسة Authorization، مقابل الرابط الأساسي https://taskfolk.ai/api.

أول نداء لك على الإطلاق ينبغي أن يكون GET /v1/me. لا يحتاج نطاقًا سوى مفتاح صالح، ويعيد هوية المفتاح ذاته: keyId وname وworkspaceSlug وscopes وexpiresAt. إنها أرخص طريقة ممكنة لتأكيد أن الرمز موصول صحيحًا قبل أن تقترب من المهام.

curl https://taskfolk.ai/api/v1/me \
  -H "Authorization: Bearer tfk_live_a1b2..."

استجابة جيّدة:

{
  "keyId": "key_9f2c...",
  "name": "CI issue bot",
  "workspaceSlug": "taskfolk",
  "scopes": ["issues:read", "issues:write"],
  "expiresAt": "2026-10-15T00:00:00Z"
}

اجعل /v1/me فحص سلامتك، وإليك لماذا يهمّ أكثر من المعتاد. كل فشل مصادقة في Taskfolk ينهار إلى 401 غامض واحد برسالة متطابقة: «Invalid or missing API key.». ذلك السطر الواحد يغطّي كل هذه:

• ترويسة Authorization مفقودة
• رمز مشوّه
• مفتاح غير معروف
• مفتاح مُبطَل
• مفتاح منتهي الصلاحية

الـ API لن يخبرك أيّها هو. ذلك اختيار أمنيّ متعمّد (لا يسرّب إن كان مفتاح معيّن موجودًا)، لكنه يعني أنك لا تستطيع تصحيح المصادقة بقراءة الخطأ. فحين يعيد شيء 401، عالجه هكذا بدلًا من ذلك:

flowchart TD
    A[A request returns 401] --> B[Call GET /v1/me with the same token]
    B --> C{Does /v1/me succeed}
    C -->|Yes| D[Token is fine, check scope and path]
    C -->|No| E[Token problem, fix or mint the key]

إن عمل /v1/me وأعاد endpoint حقيقيّ 401، فرمزك سليم وأنت تنظر إلى مشكلة نطاق أو مسار، لا مشكلة مصادقة.

شيء آخر تخبرك به الاستجابة بهدوء. النطاقات تُقاطَع مع دور منشئ المفتاح الحيّ في مساحة العمل وقت النداء. إن أنشأ مشرف مفتاحًا بنطاقات بدرجة المشرف ثم خُفّض لاحقًا إلى عضو، يفقد المفتاح تلك الدرجة تلقائيًا. لا يمكن للمفتاح أبدًا أن يمنح أكثر ممّا يملكه الشخص خلفه حاليًا. فقوّة المفتاح الحقيقية هي «ما حُصر له» AND «ما ما زال منشئه يستطيعه اليوم»، أيّهما أضيق.

اسرد المهام واقرأها في مشروع WEB

بنطاق issues:read على المفتاح، تستطيع قراءة اللوحة. الـ endpoint هو GET /v1/workspaces/taskfolk/projects/WEB/issues، ويأخذ كومةً من مرشّحات الاستعلام التي تنعكس على ما تبحث عنه فعلًا:

• ?status= حسب العمود أو الفئة
• ?type= (task، bug، story، epic، subtask)
• ?priority=
• ?assignee=، الذي يقبل user_id أو email أو الحرفيّ me
• ?reporter=
• ?label=
• ?milestone=
• ?sprint=
• ?parent=، مفتاح مهمة أب، أو none للمستوى الأعلى فقط
• ?q=، بحث نصّيّ حرّ

تتراكب. لنقل تريد كل خطأ في عمود In Progress مسند إلى هوية المفتاح نفسه:

curl "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues?type=bug&status=In+Progress&assignee=me" \
  -H "Authorization: Bearer tfk_live_a1b2..."

أو أنت تصطاد تذكرة محدّدة بكلمات في عنوانها. لإيجاد قصة «Timeline + Summary tab» على لوحة WEB:

curl "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues?q=Timeline+Summary" \
  -H "Authorization: Bearer tfk_live_a1b2..."

القائمة مصفّحة بالمؤشّر، keyset على createdAt, id تنازليًا، فتبقى سريعة على لوحة كبيرة بدل التباطؤ صفحةً صفحة. تحمل الاستجابة pagination.next_cursor. حين يكون غير فارغ، مرّره ثانيةً كمؤشّر في طلبك التالي للمشي في الصفحة التالية. حين يعود فارغًا، تكون قد قرأت كل شيء.

ملاحظة صدق واحدة على ?q=. البحث النصّيّ الحرّ يمرّ عبر Typesense و Typesense فقط. لا احتياطيّ SQL LIKE. ذلك جيّد للسرعة (مسح نصّيّ عبر ملايين المهام هو بالضبط الاستعلام الذي كان يأخذ دقيقة)، لكن له نتيجة: إن كان فهرس البحث معطّلًا، يعيد ?q= فارغًا بدل الرجوع إلى مسح بطيء. النتائج الفارغة من استعلام نصّيّ ليست دليلًا على عدم وجود التذكرة. قد تعني أيضًا أن البحث غير متاح مؤقتًا. المرشّحات المُهيكلة (status وtype وassignee والباقي) لا تعتمد على Typesense، فتبقى تعمل بصرف النظر.

أنشئ المهام وحدّثها عبر الـ API

القراءة نصف العمل. للكتابة، يحتاج المفتاح issues:write.

إنشاء مهمة هو POST إلى المجموعة نفسها: POST /v1/workspaces/taskfolk/projects/WEB/issues. الجسم يأخذ { type, title, description_md?, status?, priority?, assignee?, labels?, parent?, due_at?, estimate_minutes? } وإنشاء جيّد يعيد 201 بالمهمة الجديدة، بما فيها مفتاحها المُسنَد حديثًا مثل WEB-142.

إليك المثال المُنفَّذ. قيّد مهمة اسمها «Timeline + Summary tab» وأسقطها مباشرةً في عمود To Do.

curl -X POST "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues" \
  -H "Authorization: Bearer tfk_live_a1b2..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "task",
    "title": "Timeline + Summary tab",
    "description_md": "Add the combined Timeline and Summary view to the project shell.",
    "status": "To Do",
    "priority": "medium"
  }'

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer tfk_live_a1b2...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "task",
      title: "Timeline + Summary tab",
      description_md:
        "Add the combined Timeline and Summary view to the project shell.",
      status: "To Do",
      priority: "medium",
    }),
  }
);
const issue = await res.json(); // 201, includes the new key like WEB-142

import requests

res = requests.post(
    "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues",
    headers={"Authorization": "Bearer tfk_live_a1b2..."},
    json={
        "type": "task",
        "title": "Timeline + Summary tab",
        "description_md": "Add the combined Timeline and Summary view to the project shell.",
        "status": "To Do",
        "priority": "medium",
    },
)
issue = res.json()  # 201, includes the new key like WEB-142

التحديث هو PATCH للمهمة المنفردة: PATCH /v1/workspaces/taskfolk/projects/WEB/issues/WEB-142. إنه دمج متناثر، وذلك الجزء الواجب استيعابه. ترسل فقط الحقول التي تغيّرها، وكل ما تحذفه يبقى تمامًا كما كان. لرفع تلك التذكرة إلى أولوية عالية وتسليمها لأحدهم، ترسل هذين الحقلين ولا شيء آخر:

curl -X PATCH "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues/WEB-142" \
  -H "Authorization: Bearer tfk_live_a1b2..." \
  -H "Content-Type: application/json" \
  -d '{ "priority": "high", "assignee": "[email protected]" }'

لا إعادة إرسال للعنوان أو الوصف. PATCH المتناثر يعني أنك لا تُفرّغ حقلًا أبدًا لمجرّد أنك تركته.

بضع عمليات إضافية تكمّل السطح:

• GET .../issues/WEB-142 يجلب مهمة منفردة. المهام المؤرشفة ما زالت تُحلّ عند القراءة، فرابط لتذكرة قديمة لا يعطي 404.
• DELETE .../issues/WEB-142 أرشفة ناعمة، لا حذف قاسٍ. يضبط archived_at ويُطلق webhook بـ issue.archived. المهمة قابلة للاستعادة، والاستعادة endpoint منفصل (الحذف والاستعادة ليسا النداء نفسه عمدًا).
• POST .../issues/WEB-142/transition هي الطريقة المخصّصة لنقل الحالة عبر سير العمل، أنظف من PATCH حالة خام حين يملك المشروع قواعد انتقال.

وللاستيراد الجماعيّ، يوجد POST .../issues/bulk. يعيد غلافًا متعدّد الحالات بأسلوب 207، فدفعةٌ بثلاثة صفوف صالحة وواحد مشوّه لا تفشل جملةً واحدة. تحصل على نتيجة لكل عنصر وتعيد محاولة الصفوف التي فشلت فقط.

اجعل الكتابات آمنة: مفاتيح idempotency وحدود المعدّل

ترويستان تفصلان سكربتًا لعبةً عن شيء تثق به في الإنتاج. كلاهما يهمّ أكثر لحظة يقود النداءات وكيلٌ، لا إنسان.

الأولى Idempotency-Key. ضعها على أي طلب مُعدِّل (POST، PUT، PATCH، DELETE) وإن أُعيدت محاولة ذلك الطلب بالضبط بالمفتاح نفسه، يعيد Taskfolk النتيجة الأصلية بدل تنفيذ الكتابة ثانيةً. هذا هو حلّ الإنشاء المزدوج الكلاسيكيّ. يرسل وكيلك POST لمهمة جديدة، تتعثّر الشبكة قبل عودة الاستجابة، يعيد الوكيل المحاولة، وبلا idempotency تملك الآن تذكرتَي «Timeline + Summary tab» متطابقتين. مع مفتاح idempotency، تعيد المحاولة المهمة الأولى، لا ثانية.

sequenceDiagram
    participant A as Agent
    participant U as Taskfolk API
    A->>U: POST issue with Idempotency Key
    U->>U: creates WEB 142
    U--xA: response lost in transit
    A->>U: retry, same Idempotency Key
    U-->>A: 201 with the original WEB 142

curl -X POST "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues" \
  -H "Authorization: Bearer tfk_live_a1b2..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-timeline-tab-2026-07-15" \
  -d '{ "type": "task", "title": "Timeline + Summary tab", "status": "To Do" }'

استخدم مفتاحًا مستقرًّا للعملية المنطقية. إن كان يمثّل «مهمة تشغيل CI هذا» أو «هذا الصفّ من الاستيراد»، فاشتقّ مفتاح idempotency من تلك الهوية كي تعيد محاولةُ العمل المنطقيّ نفسه استخدامه. الشبكات المتعثّرة وحلقات إعادة المحاولة المتحمّسة للوكلاء هي بالضبط الظروف التي وُجد هذا لها.

الثانية حدّ المعدّل. كل استجابة تحمل ثلاث ترويسات: X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (طابع زمنيّ بثواني unix لموعد إعادة ضبط النافذة). الميزانية الافتراضية 600 طلب في الدقيقة ما لم يُضبَط تجاوز لكل مفتاح، وذلك التجاوز يمكن أن يكون أي شيء من 1 إلى 100,000. اقرأ X-RateLimit-Remaining وأبطئ كلّما اقترب من الصفر بدل المطرقة حتى تُقطَع.

إن تجاوزت الحدّ فعلًا تحصل على 429، وتضمّ الاستجابة ترويسة Retry-After تخبرك كم ثانية تنتظر. العملاء المهذّبون يحترمونها. النمط بسيط: عند 429، نم لـ Retry-After ثانية، ثم أعِد المحاولة، ويُفضّل بمفتاح idempotency ما زال مُرفقًا كي تبقى المحاولة آمنة.

إن كنت توصل هذا في وكيل مستقلّ يدور على اللوحة، فانضباط إعادة المحاولة والتراجع هو معظم اللعبة. دع وكلاء الذكاء الاصطناعي يديرون لوحتك عبر REST API يتعمّق في النمط.

تصفّح المواصفة الكاملة وولّد عميلًا مُصنّفًا

لست مضطرًّا لحفظ أيٍّ من هذه الـ endpoints. علامة تبويب API Reference تُضمّن الوثائق الحيّة، مولّدةً مباشرةً من مواصفة OpenAPI على /api/v1/openapi.json، فلا تنجرف أبدًا عمّا يفعله الخادم فعلًا. زران عليها: Raw OpenAPI لأخذ المواصفة نفسها، وOpen in new tab لإظهار المرجع بملء الشاشة.

المرجع على /api/v1/reference عامّ ولا يحتاج مصادقة، فيمكنك تصفّح كل endpoint في v1 وأشكال طلبه واستجابته قبل أن تكون قد أنشأت مفتاحًا حتى. إنه مكان جيّد لبدء القراءة.

الآن الجزء الصريح عن الأدوات. حزمة @taskfolk/sdk-node الرسمية موسومة Coming soon. ليست على npm اليوم. فلا تذهب باحثًا عن npm install @taskfolk/sdk-node؛ لن يُحلّ. ما تستطيع فعله الآن هو توليد عميل TypeScript مُصنّف من مواصفة OpenAPI بأداة مثل openapi-typescript:

npx openapi-typescript https://taskfolk.ai/api/v1/openapi.json -o src/taskfolk-api.d.ts

ذلك يمنحك أشكال طلب واستجابة مُصنّفة لكل endpoint، وهو معظم ما تشتريه لك SDK، ويبقى متزامنًا لأنه مولّد من المواصفة نفسها التي ينشرها الخادم.

علامة تبويب Webhooks هي نظير الدفع لكل هذا الاستطلاع. بدل السؤال «أي مهام جديدة؟» في حلقة، تسجّل endpoint بـ https فقط، وتنتقي أنواع أحداثك، ويرسل Taskfolk POST إليك حين يحدث شيء: issue.created وissue.updated وissue.archived وأحداث comment.* والمزيد.

كل تسليم موقّع بأسلوب Stripe بترويسة X-Taskfolk-Signature: t=<unix>, v1=<hmac_hex> كي تتحقّق أنه جاء من Taskfolk فعلًا، وسرّ التوقيع يُعرَض مرة عند الإنشاء (قاعدة انسخه-الآن نفسها كالمفاتيح). لأي شيء قريب من المباشر، الـ webhooks تتفوّق على الاستطلاع في كلٍّ من الكمون وميزانية حدّ المعدّل.

الرموز الشخصية، والإبطال، والحدود الجديرة بالمعرفة

مفاتيح مساحة العمل هي الأداة الصحيحة لبوت ينتمي إلى مساحة عمل واحدة. لكنك أحيانًا إنسان يكتب سكربتًا يلمس عدّة مساحات عمل خاصّة بك، وإصدار مفتاح منفصل في كلٍّ منها مُتعب. لهذا وُجدت الرموز الشخصية.

الرموز الشخصية (PATs) تعيش على /me/tokens، مربوطةً من علامة تبويب Keys كـ Manage tokens. يعمل PAT عبر كل مساحات عملك، يحمل البادئة tfp_live_ (لاحظ utt_، لا utp_ الخاصّ بمفتاح مساحة العمل)، ويرث عضويتك في كل مساحة عمل تنتمي إليها. لا قائمة سماح مشاريع على PAT (هو على نطاق مساحة العمل بطبيعته) ويستخدم حدّ المعدّل الافتراضيّ العالميّ. يمكنك الاحتفاظ بحتى 25 رمزًا نشطًا.

فالاختيار يتلخّص في هذا:

	مفتاح مساحة العمل	الرمز الشخصيّ
البادئة	tfk_live_	tfp_live_
المدى	مساحة عمل واحدة	كل مساحة عمل تنتمي إليها
النطاقات	مجمّدة عند الإنشاء	تتبع عضويتك الحيّة
قائمة سماح المشاريع	اختيارية، مجمّدة عند الإنشاء	لا يوجد
حدّ المعدّل	600/دقيقة افتراضيًا، تجاوز لكل مفتاح	الافتراضيّ العالميّ
الأفضل لـ	بوت أو أتمتة CI	سكربتاتك الخاصّة عبر مساحات العمل

لبوت CI، استخدم مفتاح مساحة عمل. لسكربت هجرتك الشخصيّ الذي يتنقّل بين مساحتَي عمل تملكهما، استخدم PAT.

الإبطال فوريّ ودائم. اضغط Revoke key على أي مفتاح فيتوقّف عن العمل فورًا؛ لا تراجع. الإبطال ناعم في قاعدة البيانات (يسجّل revoked_at وسببًا لأثر التدقيق) لكن لأغراضك المفتاح ميت لحظة نقرك. هذا مفتاح إيقافك إن تسرّب مفتاح.

بضع حدود صريحة أخيرة تحملها معك:

• النطاقات والمشاريع غير قابلة للتغيير. تغيير امتيازات مفتاح يعني إنشاء مفتاح جديد. فقط الاسم وحدّ المعدّل وانتهاء الصلاحية قابلة للتحرير بعد الإنشاء.
• النسخ-مرة حقيقيّ. المفتاح النصّيّ يظهر مرة واحدة بالضبط، عند الإنشاء. تُخزَّن تجزئة فقط. خطّط لذلك.
• أخطاء 401 غامضة. كل فشل مصادقة يعيد الرسالة نفسها «Invalid or missing API key.». استخدم /v1/me للتشخيص، لا نصّ الخطأ.
• البادئة utp_test_ محجوزة لكنها ليست حيّة. لا يوجد وضع مفتاح صندوق رمليّ اليوم. لا تبنِ حول واحد.
• علامتا تبويب Usage و Audit أفضل جهد ممكن. تلك البيانات (بما فيها موجز النشاط الأخير في Overview) تعيش في ClickHouse. إن كانت غير قابلة للوصول في بيئتك، تُعرض تلك العلامات في حالة فارغة، فقد تتأخّر أو تبدو فارغة. لا تقرأ علامة تبويب Usage فارغة كدليل على أن شيئًا لم يحدث.

إن أردت الصورة الأكبر لربط وكيل من طرف إلى طرف، لا نداءات HTTP فقط بل الإعداد حولها، فـكيف تربط وكيل ذكاء اصطناعي يغطّيه.

هذه هي الحلقة كاملةً: احصر مفتاحًا، انسخه مرة، أكّده بـ /v1/me، ثم اقرأ المهام واكتبها بأمان بمفاتيح idempotency وعين على ترويسات حدّ المعدّل. افتح وحدة تحكّم المطوّر تحت /w/{workspace}/knowledge/developer وأنشئ أول مفتاح لك حين تكون جاهزًا لوصله.