گفت‌وگو

پرسشی بفرستید و پاسخی بگیرید که بر سندهای همان فضای کاری تکیه دارد.

با یک مسیر پرسش می‌فرستید و با دو مسیر دیگر آنچه پرسیده شده را بازمی‌خوانید. پاسخ‌ها بر سندهای پردازش شده همان فضای کاری تکیه دارند و ارجاع‌هایی می‌آورند که بخش‌های پشتشان را نام می‌برند.

فرستادن پیام

پرسش را می‌فرستد و هر دو پیام این تبادل را همراه با نشستی که به آن تعلق دارند برمی‌گرداند. برای شروع گفت‌وگوی تازه session_id را نفرستید — سرور می‌سازدش و از پیام اولتان برایش عنوان می‌گذارد.

POST/workspaces/{workspace_id}/chat/

فیلد	نوع	توضیح
`external_user_id` (الزامی)	`string`	شناسهٔ خودتان برای کاربر نهایی‌ای که می‌پرسد. گفت‌وگوها بر همین اساس جدا می‌شوند و در هر فراخوانی الزامی است.
`message`	`string`	پرسش. فقط وقتی اختیاری است که به‌جایش تصویر بفرستید؛ درخواستی که هیچ‌کدام را نداشته باشد رد می‌شود.
`image`	`file`	یک تصویر برای پرسیدن دربارهٔ آن. بخشی از پرسش است، نه سندی در فضای کاری: هرگز وارد خط پردازش نمی‌شود.
`session_id`	`uuid`	ادامهٔ یک گفت‌وگوی موجود. اگر ندهید، سرور یکی می‌سازد و از پیام اولتان برایش عنوان می‌گذارد.
`resource_ids`	`uuid[]`	بازیابی را به همین سندها محدود می‌کند. هر کدام باید ready و متعلق به همین فضای کاری باشند.
`skill_id`	`uuid`	پیش‌تنظیم پرامپتی که روی این پاسخ اعمال می‌شود. شناسه‌های در دسترس را از مسیر skills بگیرید.

external_user_id در هر فراخوانی الزامی است. شناسهٔ شماست برای کسی که می‌پرسد و گفت‌وگوها بر همان اساس جدا می‌شوند: دو کاربر شما که یک کلید API مشترک دارند هرگز تاریخچهٔ یکدیگر را نمی‌بینند.

باید message بفرستید، یا image، یا هر دو. درخواستی که هیچ‌کدام را نداشته باشد خطای ۴۰۰ می‌گیرد.

cURL

JavaScript

Python

curl -X POST "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_4821",
    "message": "How long do anticoagulant patients stay under observation?"
  }'

پاسخ

{
  "status": "ok",
  "data": {
    "session": {
      "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37",
      "title": "Anticoagulant discharge window",
      "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f",
      "created_at": "2026-08-05T10:02:11.004Z",
      "updated_at": "2026-08-05T10:02:14.551Z"
    },
    "user_message": {
      "id": "5e2c8a03-49bd-4c17-8f6a-31d0b7e5a924",
      "role": "user",
      "content": "How long do anticoagulant patients stay under observation?",
      "response": null,
      "citations": [],
      "resource_ids": [],
      "image_url": null,
      "created_at": "2026-08-05T10:02:11.219Z"
    },
    "assistant_message": {
      "id": "7c1b4e90-2af6-4d38-b5c1-8e07a3f62d15",
      "role": "assistant",
      "content": "Patients on anticoagulants require a 48-hour observation window before discharge.",
      "response": {
        "type": "answer",
        "parts": [
          {
            "text": "Patients on anticoagulants require a 48-hour observation window before discharge.",
            "source": {
              "chunk_id": "e0c9a71d-5b32-4f88-9a04-6c1d2e83f507",
              "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81",
              "resource_title": "Discharge protocol 2026.pdf",
              "chunk_index": 7,
              "metadata": { "source_type": "pdf", "page": 4 }
            }
          }
        ],
        "form": null
      },
      "citations": [
        {
          "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81",
          "resource_title": "Discharge protocol 2026.pdf",
          "chunk_index": 7,
          "metadata": { "source_type": "pdf", "page": 4 }
        }
      ],
      "resource_ids": ["3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81"],
      "image_url": null,
      "created_at": "2026-08-05T10:02:14.480Z"
    }
  }
}

گاهی مدل پیش از پاسخ دادن به ورودی نیاز دارد. آن‌وقت response.type به‌جای answer برابر form است و response.form فیلدهایی را که باید جمع کنید توصیف می‌کند. آن‌ها را نشان بدهید و پاسخ‌ها را در قالب یک پیام معمولی بعدی بفرستید.

نمونه

{
  "status": "ok",
  "data": {
    "assistant_message": {
      "role": "assistant",
      "content": "Which department should I answer for?",
      "response": {
        "type": "form",
        "parts": [{ "text": "Which department should I answer for?", "source": null }],
        "form": {
          "title": "Narrow the question",
          "fields": [
            {
              "name": "department",
              "label": "Department",
              "type": "select",
              "required": true,
              "options": ["Cardiology", "Neurology", "Oncology"]
            }
          ]
        }
      }
    }
  }
}

فیلد	نوع	توضیح
`id`	`uuid`	شناسهٔ یکتا که سرور تولید می‌کند.
`role`	`user \| assistant`	نویسندهٔ پیام — user یا assistant.
`content`	`string`	پاسخ به‌صورت markdown، حاصل به‌هم‌پیوستن response.parts.
`response`	`object`	پاسخ ساختاریافته: نوع آن، بخش‌هایی که می‌سازندش، و فرم — وقتی مدل به ورودی نیاز دارد.
`citations`	`object[]`	برای هر بخشِ ارجاع‌داده‌شده یک ورودی، بدون تکرار. این همان ردّ حسابرسی پشت پاسخ است.
`resource_ids`	`uuid[]`	سندهایی که در ساخت این پیام نقش داشته‌اند.
`image_url`	`string \| null`	نشانی تصویر پیوست‌شده، یا null.
`created_at`	`datetime`	زمان ساخت، با قالب ISO 8601.

cURL

JavaScript

Python

curl -X POST "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_4821",
    "session_id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37",
    "message": "And for patients over 70?"
  }'

فهرست نشست‌ها

گفت‌وگوهای آن کاربر نهایی در این فضای کاری را از جدیدترین فهرست می‌کند. پارامتر کوئری external_user_id الزامی است — بدون آن خطای ۴۰۰ می‌گیرید، نه فهرست فیلترنشده.

GET/workspaces/{workspace_id}/chat/sessions/

فیلد	نوع	توضیح
`external_user_id` (الزامی)	`string`	همان شناسه‌ای که هنگام ساخت گفت‌وگو فرستادید. اگر نفرستید خطای ۴۰۰ می‌گیرید، نه فهرست خالی.

cURL

JavaScript

Python

curl "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/sessions/?external_user_id=user_4821" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL"

پاسخ

{
  "status": "ok",
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37",
        "title": "Anticoagulant discharge window",
        "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f",
        "created_at": "2026-08-05T10:02:11.004Z",
        "updated_at": "2026-08-05T10:02:14.551Z"
      }
    ]
  }
}

فهرست پیام‌های یک نشست

متن کامل یک نشست را از قدیمی‌ترین برمی‌گرداند. همان پارامتر کوئری الزامی است و نشستی که به کاربر نهایی دیگری تعلق دارد خطای ۴۰۴ می‌دهد.

GET/workspaces/{workspace_id}/chat/sessions/{session_id}/messages/

فیلد	نوع	توضیح
`external_user_id` (الزامی)	`string`	همان شناسه‌ای که هنگام ساخت گفت‌وگو فرستادید. اگر نفرستید خطای ۴۰۰ می‌گیرید، نه فهرست خالی.

cURL

JavaScript

Python

curl "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/sessions/b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37/messages/?external_user_id=user_4821" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL"

فرستادن پیام

external_user_id

string

شناسهٔ خودتان برای کاربر نهایی‌ای که می‌پرسد. گفت‌وگوها بر همین اساس جدا می‌شوند و در هر فراخوانی الزامی است.

message

string

پرسش. فقط وقتی اختیاری است که به‌جایش تصویر بفرستید؛ درخواستی که هیچ‌کدام را نداشته باشد رد می‌شود.

image

file

یک تصویر برای پرسیدن دربارهٔ آن. بخشی از پرسش است، نه سندی در فضای کاری: هرگز وارد خط پردازش نمی‌شود.

session_id

uuid

ادامهٔ یک گفت‌وگوی موجود. اگر ندهید، سرور یکی می‌سازد و از پیام اولتان برایش عنوان می‌گذارد.

resource_ids

uuid[]

بازیابی را به همین سندها محدود می‌کند. هر کدام باید ready و متعلق به همین فضای کاری باشند.

skill_id

uuid

پیش‌تنظیم پرامپتی که روی این پاسخ اعمال می‌شود. شناسه‌های در دسترس را از مسیر skills بگیرید.

curl -X POST "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/" \ -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \ -H "Content-Type: application/json" \ -d '{ "external_user_id": "user_4821", "message": "How long do anticoagulant patients stay under observation?" }'

{ "status": "ok", "data": { "session": { "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37", "title": "Anticoagulant discharge window", "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f", "created_at": "2026-08-05T10:02:11.004Z", "updated_at": "2026-08-05T10:02:14.551Z" }, "user_message": { "id": "5e2c8a03-49bd-4c17-8f6a-31d0b7e5a924", "role": "user", "content": "How long do anticoagulant patients stay under observation?", "response": null, "citations": [], "resource_ids": [], "image_url": null, "created_at": "2026-08-05T10:02:11.219Z" }, "assistant_message": { "id": "7c1b4e90-2af6-4d38-b5c1-8e07a3f62d15", "role": "assistant", "content": "Patients on anticoagulants require a 48-hour observation window before discharge.", "response": { "type": "answer", "parts": [ { "text": "Patients on anticoagulants require a 48-hour observation window before discharge.", "source": { "chunk_id": "e0c9a71d-5b32-4f88-9a04-6c1d2e83f507", "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81", "resource_title": "Discharge protocol 2026.pdf", "chunk_index": 7, "metadata": { "source_type": "pdf", "page": 4 } } } ], "form": null }, "citations": [ { "resource_id": "3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81", "resource_title": "Discharge protocol 2026.pdf", "chunk_index": 7, "metadata": { "source_type": "pdf", "page": 4 } } ], "resource_ids": ["3c9a1b77-0d24-4e8b-b0f1-7a5e9c2d4b81"], "image_url": null, "created_at": "2026-08-05T10:02:14.480Z" } } }

{ "status": "ok", "data": { "assistant_message": { "role": "assistant", "content": "Which department should I answer for?", "response": { "type": "form", "parts": [{ "text": "Which department should I answer for?", "source": null }], "form": { "title": "Narrow the question", "fields": [ { "name": "department", "label": "Department", "type": "select", "required": true, "options": ["Cardiology", "Neurology", "Oncology"] } ] } } } } }

id

uuid

شناسهٔ یکتا که سرور تولید می‌کند.

role

user | assistant

نویسندهٔ پیام — user یا assistant.

content

string

پاسخ به‌صورت markdown، حاصل به‌هم‌پیوستن response.parts.

response

object

پاسخ ساختاریافته: نوع آن، بخش‌هایی که می‌سازندش، و فرم — وقتی مدل به ورودی نیاز دارد.

citations

object[]

برای هر بخشِ ارجاع‌داده‌شده یک ورودی، بدون تکرار. این همان ردّ حسابرسی پشت پاسخ است.

resource_ids

uuid[]

سندهایی که در ساخت این پیام نقش داشته‌اند.

image_url

string | null

نشانی تصویر پیوست‌شده، یا null.

created_at

datetime

زمان ساخت، با قالب ISO 8601.

curl -X POST "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/" \ -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \ -H "Content-Type: application/json" \ -d '{ "external_user_id": "user_4821", "session_id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37", "message": "And for patients over 70?" }'

external_user_id

string

همان شناسه‌ای که هنگام ساخت گفت‌وگو فرستادید. اگر نفرستید خطای ۴۰۰ می‌گیرید، نه فهرست خالی.

{ "status": "ok", "data": { "count": 1, "next": null, "previous": null, "results": [ { "id": "b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37", "title": "Anticoagulant discharge window", "workspace_id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f", "created_at": "2026-08-05T10:02:11.004Z", "updated_at": "2026-08-05T10:02:14.551Z" } ] } }

external_user_id

string

همان شناسه‌ای که هنگام ساخت گفت‌وگو فرستادید. اگر نفرستید خطای ۴۰۰ می‌گیرید، نه فهرست خالی.

curl "https://api.daneshyar.info/api/v1/workspaces/8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f/chat/sessions/b6d2e1a4-77c3-4f59-9a10-2e8d6c4b0f37/messages/?external_user_id=user_4821" \ -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL"