API de Chat IA

GET /api/chat/folders

Obtiene una lista de todas las carpetas de chat pertenecientes al actor autenticado.

Respuesta Exitosa (200 OK)

{
    "folders": [
        {
            "id": 1,
            "name": "Viajes Personales",
            "conversation_count": 5
        },
        {
            "id": 2,
            "name": "Consultas de Clientes",
            "conversation_count": 12
        }
    ]
}

POST /api/chat/folders

Crea una nueva carpeta de chat.

Cuerpo de la Petición

{
    "name": "Nuevos Proyectos"
}

Respuesta Exitosa (201 Created)

Devuelve el objeto de la carpeta recién creada.

{
    "folder": {
        "id": 3,
        "name": "Nuevos Proyectos",
        "conversation_count": 0
    }
}

PUT /api/chat/folders/<folder_id>

Renombra una carpeta existente.

Cuerpo de la Petición

{
    "new_name": "Proyectos Archivados"
}

Respuesta Exitosa (200 OK)

Devuelve el objeto de la carpeta actualizada.

DELETE /api/chat/folders/<folder_id>

Elimina una carpeta. Las conversaciones que contenía no se eliminan, simplemente quedan sin asignar a ninguna carpeta.

Respuesta Exitosa (200 OK)

{
    "message": "Carpeta ID 3 eliminada correctamente."
}

GET /api/chat/conversations/unfoldered

Obtiene una lista de las conversaciones que no están asignadas a ninguna carpeta.

Respuesta Exitosa (200 OK)

Devuelve un array de objetos de conversación.

GET /api/chat/folders/<folder_id>/conversations

Obtiene una lista de todas las conversaciones dentro de una carpeta específica.

Respuesta Exitosa (200 OK)

Devuelve un array de objetos de conversación.

PUT /api/chat/conversations/<conversation_id>/move

Mueve una conversación a una carpeta diferente. Para sacar una conversación de su carpeta, usa null como valor.

Cuerpo de la Petición

{
    "folder_id": 2
}

Respuesta Exitosa (200 OK)

Devuelve el objeto de la conversación actualizada.

POST /api/chat/conversations

Crea una nueva conversación. Opcionalmente, se puede asignar a una carpeta y/o a un GPT personalizado desde su creación. Si indicas chat_gpt_id, el ID debe corresponder a un GPT accesible y activo para el actor autenticado.

Cuerpo de la Petición

{
    "title": "Planificación de viaje a Japón",
    "folder_id": 1,
    "chat_gpt_id": 7
}

Respuesta Exitosa (201 Created)

Devuelve el objeto de la conversación recién creada.

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

Recupera el historial completo de mensajes de una conversación.

Respuesta Exitosa (200 OK)

{
    "messages": [
        {
            "role": "user",
            "content": "¿Cuáles son los mejores meses para visitar Kioto?",
            "timestamp": "..."
        },
        {
            "role": "assistant",
            "content": "Los mejores meses para visitar Kioto son...",
            "timestamp": "..."
        }
    ]
}

POST /api/chat/conversations/<conversation_id>/messages

Envía un mensaje a una conversación existente y obtiene una respuesta del asistente de IA. Esta acción consume tokens.

Cuerpo de la Petición

{
    "message": "¿Cuáles son los mejores meses para visitar Kioto?"
}

Respuesta Exitosa (200 OK)

{
    "reply": "Los mejores meses para visitar Kioto son la primavera (marzo-mayo) por los cerezos en flor, y el otoño (octubre-noviembre) por los colores vibrantes...",
    "tokens_remaining": 98
}

POST /api/chat/conversations/<conversation_id>/upload

Sube un documento (.pdf, .txt, .md) a una conversación para que su contenido sea utilizado como contexto en los siguientes mensajes.

Cuerpo de la Petición

La petición debe ser de tipo multipart/form-data. El archivo debe enviarse bajo la clave document.

curl -X POST "https://capdata.es/api/chat/conversations/42/upload" \
     -H "X-CapData-Token: tu_api_key_o_token" \
     -F "document=@/ruta/a/tu/reserva_hotel.pdf"

Respuesta Exitosa (200 OK)

{
    "success": true,
    "message": "Archivo 'reserva_hotel.pdf' analizado y añadido al contexto de esta conversación. Ya puedes hacer preguntas sobre él."
}

GET /api/chat/gpts

Obtiene una lista de todos los GPTs accesibles para el actor (incluye los importados de los globales). La respuesta incluye metadatos como knowledge_file_count, is_global_origin y display_type.

Respuesta Exitosa (200 OK)

{
  "gpts": [
    {
      "id": 7,
      "name": "Asistente de Viajes",
      "description": "Especializado en rutas y aerolíneas",
      "is_active": true,
      "knowledge_file_count": 3,
      "is_global_origin": false,
      "display_type": "Cliente"
    }
  ]
}

GET /api/chat/gpts/available-global

Lista los GPTs globales disponibles para ser importados por el cliente.

Respuesta Exitosa (200 OK)

{
  "available_global_gpts": [
    {
      "id": 3,
      "name": "Plantilla Hotelera",
      "description": "Base para atención hotelera",
      "is_global": true,
      "can_import": true,
      "knowledge_file_count": 5
    }
  ]
}

POST /api/chat/gpts/import/<global_gpt_id>

Importa un GPT global para el cliente autenticado.

Respuesta Exitosa (201 Created)

{
  "message": "GPT 'Plantilla Hotelera' importado exitosamente.",
  "imported_gpt": {
    "id": 12,
    "name": "Plantilla Hotelera",
    "is_active": true
  }
}

POST /api/chat/gpts

Crea un nuevo GPT personalizado con sus archivos de conocimiento.

Cuerpo de la Petición

La petición debe ser multipart/form-data con campos:

• name (string, requerido)
• system_prompt (string, requerido)
• description (string, opcional)
• is_active (boolean, opcional; por defecto true)
• knowledge_files[] (uno o varios archivos .pdf/.txt/.md)

curl -X POST "https://capdata.es/api/chat/gpts" \
  -H "X-CapData-Token: tu_api_key_o_token" \
  -F "name=Asistente Comercial" \
  -F "system_prompt=Responde como un asesor comercial experto" \
  -F "description=Entrenado con PDFs de producto" \
  -F "is_active=true" \
  -F "knowledge_files=@/ruta/catálogo.pdf" \
  -F "knowledge_files=@/ruta/procedimientos.txt"

Respuesta Exitosa (201 Created)

{
  "gpt": {
    "id": 21,
    "name": "Asistente Comercial",
    "description": "Entrenado con PDFs de producto",
    "is_active": true,
    "knowledge_file_count": 2
  }
}