Chat

Ask a question and get an answer grounded in the workspace's documents.

One endpoint asks a question; two more read back what was asked. Answers are grounded in the workspace's ready resources and carry citations naming the passages behind them.

Send a message

Sends a question and returns both messages of the exchange plus the session they belong to. Omit session_id to start a new thread — the server creates it and titles it from your first message.

POST/workspaces/{workspace_id}/chat/

Field	Type	Description
`external_user_id` (required)	`string`	Your own identifier for the end user asking. Threads are partitioned by it — required on every call.
`message`	`string`	The question. Optional only if you attach an image instead — a request with neither is rejected.
`image`	`file`	One image to ask about. Part of the question, not a workspace source: it is never ingested.
`session_id`	`uuid`	Continue an existing thread. Omit it and the server creates one and titles it from your first message.
`resource_ids`	`uuid[]`	Restrict retrieval to these resources. Each must be ready and in this workspace.
`skill_id`	`uuid`	A prompt preset to apply to this answer. Fetch available ids from the skills endpoint.

external_user_id is required on every call. It is your identifier for whoever is asking, and threads are partitioned by it: two of your users sharing one API key never see each other's history.

You must send a message, an image, or both. A request with neither is a 400.

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?"
  }'

Response

{
  "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"
    }
  }
}

Sometimes the model needs input before it can answer. Then response.type is form instead of answer, and response.form describes the fields to collect. Present them, then send the answers back as an ordinary follow-up message.

Example

{
  "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"]
            }
          ]
        }
      }
    }
  }
}

Field	Type	Description
`id`	`uuid`	Unique identifier, assigned by the server.
`role`	`user \| assistant`	Who wrote the message — user or assistant.
`content`	`string`	The answer as markdown, flattened from response.parts.
`response`	`object`	The structured answer: type, the parts that compose it, and a form when the model needs input.
`citations`	`object[]`	One entry per cited chunk, deduplicated. This is the audit trail behind the answer.
`resource_ids`	`uuid[]`	Resources that contributed to this message.
`image_url`	`string \| null`	URL of the attached image, or null.
`created_at`	`datetime`	ISO 8601 timestamp of creation.

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?"
  }'

List sessions

Lists that end user's threads in this workspace, newest first. The external_user_id query parameter is required — without it you get a 400, not an unfiltered list.

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

Field	Type	Description
`external_user_id` (required)	`string`	The same identifier you sent when creating the thread. Omitting it is a 400, not an empty list.

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"

Response

{
  "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"
      }
    ]
  }
}

List messages in a session

Returns the full transcript of one session, oldest first. Same required query parameter, and a session belonging to a different end user is a 404.

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

Field	Type	Description
`external_user_id` (required)	`string`	The same identifier you sent when creating the thread. Omitting it is a 400, not an empty list.

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

Your own identifier for the end user asking. Threads are partitioned by it — required on every call.

message

string

The question. Optional only if you attach an image instead — a request with neither is rejected.

image

file

One image to ask about. Part of the question, not a workspace source: it is never ingested.

session_id

uuid

Continue an existing thread. Omit it and the server creates one and titles it from your first message.

resource_ids

uuid[]

Restrict retrieval to these resources. Each must be ready and in this workspace.

skill_id

uuid

A prompt preset to apply to this answer. Fetch available ids from the skills endpoint.

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

Unique identifier, assigned by the server.

role

user | assistant

Who wrote the message — user or assistant.

content

string

The answer as markdown, flattened from response.parts.

response

object

The structured answer: type, the parts that compose it, and a form when the model needs input.

citations

object[]

One entry per cited chunk, deduplicated. This is the audit trail behind the answer.

resource_ids

uuid[]

Resources that contributed to this message.

image_url

string | null

URL of the attached image, or null.

created_at

datetime

ISO 8601 timestamp of creation.

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

The same identifier you sent when creating the thread. Omitting it is a 400, not an empty list.

{ "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

The same identifier you sent when creating the thread. Omitting it is a 400, not an empty list.

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"