API دریافت منابع

API منابع به شما امکان می‌دهد دانش را از هر سیستمی که قادر به ارسال درخواست HTTP است، به فضای کاری Pitchbar ارسال کنید. این روش برای انتقال محتوا از ویکی داخلی، سیستم مدیریت محتوا، یک مسیر داده یا یک فایل CSV انتخاب شده، بدون نیاز به رابط مدیریت، مفید است.

احراز هویت

هر درخواست به یک توکن API فضای کاری نیاز دارد که از بخش تنظیمات → توکن‌های API صادر شده باشد. توکن باید دارای مجوز sources:write باشد. متن ساده توکن فقط یک بار در زمان ایجاد نشان داده می‌شود؛ فقط هش SHA-256 آن ذخیره می‌شود.

Authorization: Bearer pbar_…48-character-token…

توکن‌ها محدود به فضای کاری هستند — هر چیزی که ارسال کنید در فضای کاری همان توکن ذخیره می‌شود و هرگز به فضای کاری دیگری نمی‌رود. از همان صفحه می‌توانید توکن را لغو کنید؛ توکن‌های لغو شده در فراخوانی بعدی موفق نمی‌شوند بدون اینکه بر ردیف‌های حسابرسی قبلی تأثیر بگذارند.

نقاط پایانی

لیست منابع

GET https://{your-pitchbar-host}/api/v1/workspace/sources

تا ۱۰۰ منبع اخیر فضای کاری توکن را باز می‌گرداند.

{
    "data": [
        {
            "id": "019e2000-…",
            "agent_id": "019e1fec-…",
            "kind": "url",
            "status": "indexed",
            "config": { "url": "https://example.com/pricing" },
            "last_synced_at": "2026-05-13T08:00:00+00:00",
            "created_at": "2026-05-13T07:50:00+00:00"
        }
    ]
}

ایجاد منبع

POST https://{your-pitchbar-host}/api/v1/workspace/sources
Content-Type: application/json
Authorization: Bearer pbar_…

سه نوع منبع پشتیبانی می‌شود. agent_id باید به یک دستیار فروش در فضای کاری توکن اشاره کند؛ در غیر این صورت، خطای ۴۰۴ برمی‌گردد.

۱. اسکن یک آدرس

{
    "agent_id": "019e1fec-…",
    "kind": "url",
    "url": "https://example.com/pricing"
}

۲. اسکن نقشه سایت (به تمام آدرس‌های داخل آن گسترش می‌یابد)

{
    "agent_id": "019e1fec-…",
    "kind": "sitemap",
    "url": "https://example.com/sitemap.xml"
}

۳. ارسال متن خام (از خزنده صرف‌نظر می‌کند — مناسب برای صفحات پشت احراز هویت)

{
    "agent_id": "019e1fec-…",
    "kind": "text",
    "title": "جزئیات قیمت‌گذاری سه‌ماهه",
    "content": "پلن شروع ما …",
    "source_url": "https://example.com/internal/pricing"
}

پاسخ (201 Created) منبع جدید را با وضعیت pending برمی‌گرداند. خزنده / پردازشگرساز در صف Pitchbar اجرا شده و زمانی که تکه‌ها در ذخیره‌ساز جستجوی هوشمند ذخیره شوند، وضعیت را به indexed تغییر می‌دهد. منابع موجود با محتوای مشابه براساس هش SHA-256 حذف تکراری می‌شوند، بنابراین اجرای مجدد همان فراخوانی ایمن است.

دریافت یک منبع

GET https://{your-pitchbar-host}/api/v1/workspace/sources/{id}

همان ساختار نقطه‌ی پایانی لیست، اما یک ردیف.

مثال curl

curl -X POST https://app.example.com/api/v1/workspace/sources \
  -H "Authorization: Bearer pbar_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "019e1fec-…",
    "kind": "text",
    "title": "سیاست بازپرداخت",
    "content": "مشتریان تا ۳۰ روز فرصت دارند درخواست بازپرداخت کنند …"
  }'

ساختار خطاها

وضعیت	بدنه	معنی
401	{"error":{"code":"missing_token"}}	توکن در هدر Authorization وجود ندارد.
401	{"error":{"code":"invalid_token"}}	توکن لغو شده یا با فضای کاری مطابقت ندارد.
403	{"error":{"code":"missing_ability"}}	توکن مجوز sources:write را ندارد.
404	{"error":{"code":"agent_not_found"}}	agent_id در فضای کاری توکن وجود ندارد.
422	پوشه اعتبارسنجی لاراول	فیلد کم‌دار یا ناقص.

محدودیت‌های نرخ

محدودیت هر توکن ۱۲۰ درخواست در دقیقه است. درخواست‌های بیش از سهمیه با کد 429 و هدر Retry-After پاسخ داده می‌شوند.

پس از ارسال موفق چه اتفاقی می‌افتد

1. یک ردیف Source در فضای کاری دستیار فروش ایجاد می‌شود.
2. برای kind=url / kind=sitemap یک CrawlSourceJob در صف قرار می‌گیرد. خزنده‌ی Pitchbar به آدرس درخواست می‌دهد (اولویت با Cloudflare Browser Rendering → Browserless → HTTP ساده).
3. برای kind=text یک IndexTextSourceJob از خزنده صرف‌نظر کرده و محتوا را مستقیماً به استخراج تکه‌ها ارسال می‌کند.
4. تکه‌ها با مدل جستجوی هوشمند فضای کاری به بردار تبدیل شده و در Cloudflare Vectorize / Qdrant ذخیره می‌شوند.
5. سوال بعدی بازدیدکننده که با محتوا مطابقت داشته باشد، از آن به‌عنوان منبع استفاده می‌کند.

وضعیت معمولاً بین ۱۰ تا ۶۰ ثانیه پس از ارسال به indexed تغییر می‌کند (برای نقشه‌های سایت بسیار بزرگ که به صفحات زیادی گسترش می‌یابند، زمان بیشتری نیاز است). وضعیت منبع را در داشبورد مشاهده کنید یا نقطه‌ی پایانی GET را بررسی کنید تا زمانی که وضعیت تغییر کند.