Chat

All chat endpoints are under the /api/chat prefix. Streaming responses use newline-delimited JSON (NDJSON) over text/event-stream.

Create a chat session

POST /api/chat/create-chat-session

Creates a new chat session and returns its ID. You must create a session before sending messages to it, or pass chat_session_info inline in send-chat-message to create a session implicitly.

Request body

integer

default:"0"

ID of the agent (persona) to use for this session. Defaults to 0 (the default Hadiq.io assistant).

string

Optional human-readable name for the session.

integer

Optional project ID to associate the session with.

Response

string (UUID)

Unique identifier for the new session.

curl -X POST https://cloud.hadiq.io/api/chat/create-chat-session \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{"persona_id": 0, "description": "Onboarding questions"}'

import requests

resp = requests.post(
    "https://cloud.hadiq.io/api/chat/create-chat-session",
    headers={"Authorization": "Bearer hadiqk-..."},
    json={"persona_id": 0, "description": "Onboarding questions"},
)
session_id = resp.json()["chat_session_id"]

Send a chat message

POST /api/chat/send-chat-message

Sends a message in a chat session. When stream is true (the default), the response is a streaming text/event-stream of NDJSON packets. When stream is false, the full response is returned as a single JSON object.

Request body

string

required

The user message to send.

string (UUID)

ID of an existing session. Provide either chat_session_id or chat_session_info, not both.

object

Create a session implicitly alongside the message. Provide either this or chat_session_id, not both.

Show chat_session_info fields

integer

default:"0"

Agent (persona) ID for the new session.

string

Human-readable name for the new session.

boolean

default:"true"

When true, returns a streaming text/event-stream. When false, returns a complete ChatFullResponse JSON object.

integer

default:"-1"

Placement of the new message in the conversation tree. -1 appends after the latest message. null regenerates from the root.

object

Override the LLM model for this message.

Show llm_override fields

string

Model identifier (e.g. gpt-4o).

string

Provider name (e.g. openai).

number

Sampling temperature (0–2).

boolean

default:"true"

When false, citation markers and CitationInfo packets are suppressed.

object

Optional filters to restrict which documents are searched.

array

Uploaded files to attach to the message.

string

Extra context injected into the LLM call but not stored in chat history.

boolean

default:"false"

Enable deep research mode for more thorough retrieval.

Streaming response

Each event is a NDJSON line representing one packet in the response stream. Packet types include answer tokens, citations, search results, and tool call info.

Non-streaming response (`stream: false`)

string

The complete assistant answer.

integer

ID of the created assistant message.

object

Search results used to generate the answer.

object

Map of citation number to document ID.

curl -X POST https://cloud.hadiq.io/api/chat/send-chat-message \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "What is our PTO policy?",
    "stream": true
  }'

curl -X POST https://cloud.hadiq.io/api/chat/send-chat-message \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "What is our PTO policy?",
    "stream": false
  }'

import requests
import json

resp = requests.post(
    "https://cloud.hadiq.io/api/chat/send-chat-message",
    headers={"Authorization": "Bearer hadiqk-..."},
    json={
        "chat_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message": "What is our PTO policy?",
        "stream": True,
    },
    stream=True,
)
for line in resp.iter_lines():
    if line:
        print(json.loads(line))

import requests

resp = requests.post(
    "https://cloud.hadiq.io/api/chat/send-chat-message",
    headers={"Authorization": "Bearer hadiqk-..."},
    json={
        "chat_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message": "What is our PTO policy?",
        "stream": False,
    },
)
data = resp.json()
print(data["answer"])

The correct path is /api/chat/send-chat-message (note: send-chat-message, not send-message).

Get a chat session

GET /api/chat/get-chat-session/{session_id}

Returns the full history of a session including all messages.

Path parameters

string (UUID)

required

The session to retrieve.

Query parameters

boolean

default:"false"

Set to true to retrieve a publicly shared session without authentication.

boolean

default:"false"

Include sessions that have been soft-deleted.

Response

string (UUID)

Session identifier.

string

Session name or description.

integer

Agent associated with this session.

string

Display name of the agent.

array

Ordered list of messages in the session.

Show message fields

integer

Unique message identifier.

string

Text content of the message.

string

Either user or assistant.

string (ISO 8601)

When the message was sent.

object

Map of citation number to document ID, if applicable.

array

Search documents used for this message, if applicable.

array

Files attached to the message.

string (ISO 8601)

When the session was created.

string

Sharing state: private or public.

curl https://cloud.hadiq.io/api/chat/get-chat-session/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer hadiqk-..."

import requests

session_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
resp = requests.get(
    f"https://cloud.hadiq.io/api/chat/get-chat-session/{session_id}",
    headers={"Authorization": "Bearer hadiqk-..."},
)
session = resp.json()
for msg in session["messages"]:
    print(msg["message_type"], ":", msg["message"])

List chat sessions

GET /api/chat/get-user-chat-sessions

Returns a paginated list of the authenticated user’s chat sessions.

Query parameters

integer

default:"50"

Number of sessions per page. Minimum 1, maximum 100.

string (ISO 8601)

Cursor for pagination. Pass the time_created of the last session from the previous page to fetch older sessions.

integer

Filter by a specific project.

boolean

default:"true"

When true, excludes sessions that belong to a project.

boolean

default:"false"

Include sessions that ended in an error state.

Response

array

List of session summaries.

Show session fields

string (UUID)

Session identifier.

string

Session name or description.

integer

Agent used in the session.

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last update timestamp.

string

Sharing state: private or public.

string

Override LLM model in use for this session, if any.

boolean

Whether more sessions are available. Use the time_created of the last session as before for the next page.

curl "https://cloud.hadiq.io/api/chat/get-user-chat-sessions?page_size=20" \
  -H "Authorization: Bearer hadiqk-..."

import requests

resp = requests.get(
    "https://cloud.hadiq.io/api/chat/get-user-chat-sessions",
    headers={"Authorization": "Bearer hadiqk-..."},
    params={"page_size": 20},
)
data = resp.json()
for session in data["sessions"]:
    print(session["id"], session["name"])

if data["has_more"]:
    oldest = data["sessions"][-1]["time_created"]
    # fetch next page with before=oldest

Delete a chat session

DELETE /api/chat/delete-chat-session/{session_id}

Deletes a chat session. By default, performs a soft delete (recoverable). Pass hard_delete=true to permanently remove the session.

Path parameters

string (UUID)

required

The session to delete.

Query parameters

boolean

When true, permanently deletes the session and all its messages. When omitted, the default behavior is controlled by your instance’s deletion policy.

Returns 204 No Content on success.

curl -X DELETE \
  "https://cloud.hadiq.io/api/chat/delete-chat-session/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer hadiqk-..."

import requests

session_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
requests.delete(
    f"https://cloud.hadiq.io/api/chat/delete-chat-session/{session_id}",
    headers={"Authorization": "Bearer hadiqk-..."},
)

Stop a running chat session

POST /api/chat/stop-chat-session/{chat_session_id}

Signals the server to stop generating a response for a streaming session (equivalent to clicking “Stop” in the UI).

Path parameters

string (UUID)

required

The session whose generation to stop.

Returns {"message": "Chat session stopped"}.

Error codes

Status	Cause
`400`	Invalid input, e.g. providing both `chat_session_id` and `chat_session_info`.
`403`	Session belongs to another user, or session is not publicly shared.
`404`	Session not found or has been deleted.
`422`	Malformed `before` timestamp.
`429`	Token or API rate limit exceeded.

Overview

Endpoints

Create a chat session

Request body

Response

Send a chat message

Request body

Streaming response

Non-streaming response (`stream: false`)

Get a chat session

Path parameters

Query parameters

Response

List chat sessions

Query parameters

Response

Delete a chat session

Path parameters

Query parameters

Stop a running chat session

Path parameters

Error codes

​Create a chat session

​Request body

​Response

​Send a chat message

​Request body

​Streaming response

​Non-streaming response (stream: false)

​Get a chat session

​Path parameters

​Query parameters

​Response

​List chat sessions

​Query parameters

​Response

​Delete a chat session

​Path parameters

​Query parameters

​Stop a running chat session

​Path parameters

​Error codes

Create a chat session

Request body

Response

Send a chat message

Request body

Streaming response

Non-streaming response (`stream: false`)

Get a chat session

Path parameters

Query parameters

Response

List chat sessions

Query parameters

Response

Delete a chat session

Path parameters

Query parameters

Stop a running chat session

Path parameters

Error codes