NISIRA Conversations API: Manage Chat Thread History

Conversations are the persistent thread containers for all user–assistant exchanges in NISIRA Assistant. Each conversation is identified by a randomly generated 11-character URL-safe slug that hides the internal numeric primary key. All four endpoints require a valid JWT Bearer token and scope every operation to the authenticated user — users cannot access or modify conversations that belong to other accounts.

GET /api/conversations/

Returns a paginated list of conversations belonging to the authenticated user, ordered by most-recently-updated first.

Query Parameters

page

integer

default:"1"

Page number, 1-indexed.

size

integer

default:"15"

Number of conversations per page. Clamped to the range [1, 100].

Response

conversations

array

Array of conversation summary objects.

Show Conversation object fields

string

The conversation slug (same as slug). Use this as conversation_id in all other endpoints.

numeric_id

integer

Legacy numeric primary key. Prefer id (slug) for new integrations.

slug

string

URL-safe 11-character random slug.

title

string

Conversation title, typically the first user message (up to 50 characters).

created_at

string

ISO 8601 timestamp of when the conversation was created.

updated_at

string

ISO 8601 timestamp of the last message or update.

page

integer

Current page number.

size

integer

Page size used for this response.

total

integer

Total number of conversations owned by the user.

has_more

boolean

true if there are additional pages beyond the current one.

Example

curl -X GET "https://your-domain.com/api/conversations/?page=1&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "conversations": [
    {
      "id": "aB3dEfGhIjK",
      "numeric_id": 47,
      "slug": "aB3dEfGhIjK",
      "title": "¿Cuáles son los requisitos para solicitar una licencia?",
      "created_at": "2024-11-10T14:22:01.483Z",
      "updated_at": "2024-11-10T14:25:37.901Z"
    }
  ],
  "page": 1,
  "size": 10,
  "total": 1,
  "has_more": false
}

POST /api/conversations/create/

Creates a new, empty conversation for the authenticated user.

Request Body

title

string

Optional display title for the conversation. If omitted, the backend generates a default title based on the current date and time (e.g., "Conversación 10/11/2024 14:22").

Response

string

The new conversation’s slug. Use this as conversation_id when sending the first message.

numeric_id

integer

Legacy numeric primary key.

slug

string

URL-safe 11-character random slug (same as id).

title

string

The conversation title that was saved.

created_at

string

ISO 8601 creation timestamp.

message

string

Confirmation message: "Conversación creada exitosamente".

Example

curl -X POST https://your-domain.com/api/conversations/create/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Consulta sobre normativas urbanas"}'

{
  "id": "mN7pQrStUvW",
  "numeric_id": 48,
  "slug": "mN7pQrStUvW",
  "title": "Consulta sobre normativas urbanas",
  "created_at": "2024-11-10T15:00:00.000Z",
  "message": "Conversación creada exitosamente"
}

GET /api/conversations/<conversation_id>/messages/

Returns paginated messages for a specific conversation. Page 1 returns the 15 most recent messages in ascending chronological order (oldest first within the page). Page 2 returns the 15 messages before those, also in ascending order — this design supports infinite-scroll history loading from the bottom of the chat window.

The conversation_id path parameter accepts either the slug (preferred, e.g., aB3dEfGhIjK) or the legacy numeric ID (e.g., 47). The backend detects which format is being used automatically.

Query Parameters

page

integer

default:"1"

Page number. Page 1 is the most recent batch of messages.

size

integer

default:"15"

Number of messages per page. Clamped to the range [1, 100].

Response

conversation_id

string

The conversation slug.

conversation_title

string

The conversation’s display title.

messages

array

Ordered array of message objects (ascending by creation time within the page).

Show Message object fields

integer

The message’s database ID. Use this with POST /api/ratings/ to submit feedback.

content

string

The message text. Bot messages are markdown-formatted.

is_user

boolean

true for user messages, false for bot responses.

timestamp

string

ISO 8601 creation timestamp.

sources

array

For bot messages: parsed array of source citation objects (same structure as POST /api/chat/ sources). Empty array for user messages and bot messages with no citations.

rating

string | null

The current user’s rating for this message: "like", "dislike", or null if unrated.

rating_issue_tag

string | null

The issue tag associated with the current user’s rating, or null.

total

integer

Total number of messages in the conversation.

has_more

boolean

true if older pages of messages exist beyond the current page.

Example

curl -X GET \
  "https://your-domain.com/api/conversations/aB3dEfGhIjK/messages/?page=1&size=15" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "conversation_id": "aB3dEfGhIjK",
  "numeric_id": 47,
  "slug": "aB3dEfGhIjK",
  "conversation_title": "¿Cuáles son los requisitos para solicitar una licencia?",
  "messages": [
    {
      "id": 481,
      "content": "¿Cuáles son los requisitos para solicitar una licencia de construcción?",
      "is_user": true,
      "timestamp": "2024-11-10T14:22:05.123Z",
      "sources": [],
      "rating": null,
      "rating_issue_tag": null
    },
    {
      "id": 482,
      "content": "Para solicitar una licencia de construcción debe presentar...",
      "is_user": false,
      "timestamp": "2024-11-10T14:22:07.451Z",
      "sources": [
        {
          "title": "Reglamento de Construcciones Municipales",
          "filename": "reglamento_construccion_2024.pdf",
          "page_number": 14,
          "score": 0.91,
          "document_id": "doc_8f2a1b"
        }
      ],
      "rating": "like",
      "rating_issue_tag": "none"
    }
  ],
  "page": 1,
  "size": 15,
  "total": 2,
  "has_more": false
}

DELETE /api/conversations/<conversation_id>/delete/

Permanently deletes a conversation and all of its messages. This operation is irreversible — all Message records are deleted via CASCADE, and any associated Rating records are also removed.

Deletion is permanent. All messages and ratings associated with this conversation will be lost. There is no soft-delete or trash mechanism.

Response

message

string

Confirmation string: "Conversación eliminada exitosamente".

Example

curl -X DELETE \
  "https://your-domain.com/api/conversations/aB3dEfGhIjK/delete/" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "message": "Conversación eliminada exitosamente"
}

Overview

Endpoints

NISIRA Conversations API: Manage Chat Thread History

GET /api/conversations/

Query Parameters

Response

Example

POST /api/conversations/create/

Request Body

Response

Example

GET /api/conversations/<conversation_id>/messages/

Query Parameters

Response

Example

DELETE /api/conversations/<conversation_id>/delete/

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/conversations/

​Query Parameters

​Response

​Example

​POST /api/conversations/create/

​Request Body

​Response

​Example

​GET /api/conversations/<conversation_id>/messages/

​Query Parameters

​Response

​Example

​DELETE /api/conversations/<conversation_id>/delete/

​Response

​Example

Build docs developers (and LLMs) love

GET /api/conversations/

Query Parameters

Response

Example

POST /api/conversations/create/

Request Body

Response

Example

GET /api/conversations/<conversation_id>/messages/

Query Parameters

Response

Example

DELETE /api/conversations/<conversation_id>/delete/

Response

Example