قرارداد کوچک و خواندنی

احراز هویت

کلید را از پنل با حداقل scope لازم بسازید و در هدر X-API-Key بفرستید. کلیدهای قدیمی بدون scope کار نمی‌کنند و باید rotate شوند.

curl --request GET \
+  --url 'https://hamkalam.site/api/v1/external/agents?limit=50' \
+  --header 'X-API-Key: hk_live_REPLACE_ME'

scopeها و endpointها

• agents:read — GET /api/v1/external/agents
• knowledge:read — GET /api/v1/external/knowledge
• conversations:read — GET /api/v1/external/conversations
• products:read — GET /api/v1/external/products

صفحه‌بندی

پارامتر limit بین ۱ تا ۱۰۰ است. اگر next_cursor مقدار داشت، همان مقدار opaque را بدون تغییر در درخواست بعدی با پارامتر cursor بفرستید.

{
  "items": [{ "id": "…", "name": "همیار فروش" }],
  "next_cursor": "opaque-value"
}

خطاها

• 401 کلید نامعتبر یا لغوشده
• 403 scope ناکافی
• 422 cursor یا پارامتر نامعتبر
• 429 عبور از سقف نرخ
• 5xx خطای موقت سرویس؛ با backoff تلاش کنید

محدودیت نرخ

هر کلید حداکثر ۱۲۰ درخواست در دقیقه دارد. متن کلید، payload حساس و اطلاعات مشتری را در log عمومی ذخیره نکنید.