NISIRA Assistant Chat API: Send and Receive Messages

The Chat API provides two entry points for user–assistant interactions. POST /api/chat/ is the basic endpoint that routes messages through a keyword-response generator without document retrieval — it is lightweight, fast, and suitable for simple exchanges like greetings. For full Retrieval-Augmented Generation with document citations and adaptive context retrieval, use POST /api/rag/chat/ (documented in the RAG section). Both endpoints require a valid JWT Bearer token and scope all messages to the authenticated user’s conversations.

POST /api/chat/

Send a user message to an existing conversation and receive a basic assistant reply. The conversation_id field is required — this endpoint does not auto-create conversations. To start a new thread first, call POST /api/conversations/create/ and then use the returned slug here.

POST /api/chat/ uses a keyword-based response generator (generate_basic_response), not the RAG pipeline. It does not retrieve documents or produce citations. Use POST /api/rag/chat/ for grounded, document-backed answers.

Request

Endpoint: POST /api/chat/ Authentication: Authorization: Bearer <access_token>

content

string

required

The user’s question or message. Must be a non-empty string. Leading and trailing whitespace is stripped automatically.

conversation_id

string

required

The slug (preferred) or legacy numeric ID of an existing conversation to append the message to. This field is required — omitting it returns 400 Bad Request.

Response

user_message

object

The saved user message record.

Show user_message fields

integer

Database ID of the user Message record.

content

string

The message text as stored (same as the submitted content).

is_user

boolean

Always true for the user message.

timestamp

string

ISO 8601 creation timestamp.

rating

null

Always null — user messages cannot be rated.

rating_issue_tag

string

Always "none" for the user message.

assistant_message

object

The saved assistant reply record.

Show assistant_message fields

integer

Database ID of the bot Message record. Use this ID to submit a rating via POST /api/ratings/.

content

string

The assistant’s reply text.

is_user

boolean

Always false for the assistant message.

timestamp

string

ISO 8601 creation timestamp.

rating

null

null immediately after creation (no rating submitted yet).

rating_issue_tag

string

"none" immediately after creation.

conversation_id

string

URL-safe slug of the conversation (11 characters, randomly generated). Always prefer this over the numeric ID for subsequent requests.

numeric_id

integer

Legacy numeric primary key of the conversation.

slug

string

Same as conversation_id — the conversation’s public slug.

Error Responses

HTTP	`error` value
`400`	`"El mensaje no puede estar vacío"`
`400`	`"ID de conversación requerido"`
`404`	`"Conversación no encontrada"`

Example

cURL
Response

curl -X POST http://localhost:8000/api/chat/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hola, ¿cómo estás?",
    "conversation_id": "aB3dEfGhIjK"
  }'

{
  "user_message": {
    "id": 481,
    "content": "Hola, ¿cómo estás?",
    "is_user": true,
    "timestamp": "2024-11-10T14:22:05.123Z",
    "rating": null,
    "rating_issue_tag": "none"
  },
  "assistant_message": {
    "id": 482,
    "content": "¡Hola! Soy tu asistente virtual. ¿En qué puedo ayudarte hoy?",
    "is_user": false,
    "timestamp": "2024-11-10T14:22:05.456Z",
    "rating": null,
    "rating_issue_tag": "none"
  },
  "conversation_id": "aB3dEfGhIjK",
  "numeric_id": 47,
  "slug": "aB3dEfGhIjK"
}

GET /api/documents/<filename>/

Serves the raw binary file for a document stored in the system — used by the frontend PDF viewer to display a source cited in a chat response. The filename path parameter is the document’s filename as stored in the system (as returned in the sources[].filename field of POST /api/rag/chat/ responses). Authentication: This endpoint accepts the JWT token either via the standard Authorization: Bearer <token> header or via a ?token=<token> query parameter. The query-parameter method is required for browser <iframe> PDF embeds, which cannot send custom headers.

token

string

JWT access token as a query parameter. Only needed when the Authorization header cannot be set (e.g., inside an <iframe src="...">).

Example

Header auth (cURL)
Query param (iframe)

curl -X GET \
  "http://localhost:8000/api/documents/reglamento_construccion_2024.pdf/" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --output reglamento.pdf

<iframe
  src="http://localhost:8000/api/documents/reglamento_construccion_2024.pdf/?token=eyJhbGci...#page=14"
  width="100%"
  height="600px"
/>

The response Content-Disposition header is set to inline, allowing browsers to render PDFs natively rather than downloading them. The #page=N URL fragment works in most PDF viewers to jump directly to the cited page.

The backend resolves the file from three locations in order: the UploadedDocument database record (which may point to a PostgreSQL binary store or a filesystem path), a direct PostgreSQL file store lookup, and finally a legacy filesystem directory fallback.

Overview

Endpoints

NISIRA Assistant Chat API: Send and Receive Messages

POST /api/chat/

Request

Response

Error Responses

Example

GET /api/documents/<filename>/

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/chat/

​Request

​Response

​Error Responses

​Example

​GET /api/documents/<filename>/

​Example

Build docs developers (and LLMs) love

POST /api/chat/

Request

Response

Error Responses

Example

GET /api/documents/<filename>/

Example