AIDARA API

Asistentes de IA con Streaming en Tiempo Real

Integra potentes asistentes en tu aplicación con respuestas en streaming y gestión completa de threads.

Versión: 3.0.0
Fecha: Junio 2025
Audiencia: Desarrolladores

🚀 Descripción General

AIDARA API es una plataforma avanzada para integrar asistentes en tus aplicaciones. Ofrece streaming de respuestas en tiempo real y gestión completa de threads para conversaciones persistentes.

✨ Características Principales

  • ⚡ Streaming en Tiempo Real: Respuestas progresivas tipo-ChatGPT
  • 🔐 Autenticación Robusta: Sistema de API Keys con rate limiting
  • 🧵 Gestión de Threads: Conversaciones persistentes y organizadas
  • 💚 Health Checks: Monitoreo del estado del servicio
  • 📋 API Simple: Endpoints intuitivos y fáciles de usar

🎯 Casos de Uso

  • 💬 Chatbots Inteligentes: Asistentes virtuales para atención al cliente
  • 📚 Asistentes Educativos: Tutores personalizados para e-learning
  • 🏢 Herramientas Empresariales: Automatización de tareas de oficina
  • 🔍 Análisis de Contenido: Procesamiento inteligente de documentos
  • 🛠️ Asistentes de Código: Ayuda para desarrolladores
  • 🎨 Creación de Contenido: Generación automática de textos

🔐 Autenticación

📋 Obtener API Key

Contacta con nuestro equipo para obtener tu API Key personalizada:

🛡️ Usar API Key

Incluye tu API Key en todas las peticiones mediante la cabecera X-API-Key:

X-API-Key: AIDARA_your-api-key-here
⚠️ Seguridad: Mantén tu API Key segura. Cada clave está vinculada a tu cuenta y asistente específico.

📡 Información Base

🌐 URL Base

https://api.wittymindsets.com/aidara

📄 Formato de Respuesta

JSON para endpoints estándar, Server-Sent Events (SSE) para streaming.

  • Estándar: application/json
  • Streaming: text/event-stream

⚡ Límites y Restricciones

  • Rate limiting: 60 req/min
  • Mensaje máximo: 4000 chars
  • Timeout: 120 segundos

📋 Endpoints Disponibles

Verifica el estado del servicio AIDARA y sus dependencias.

Verificación básica:

GET /health

Uso: Verificación rápida de que el servicio está en línea.

{
  "status": "ok",
  "timestamp": "2025-06-16T10:30:00.000Z",
  "service": "AIDARA API",
  "version": "3.0.0"
}

Verificación detallada:

GET /health/detailed

Uso: Verificación completa del estado de base de datos y servicio de IA.

{
  "status": "ok",
  "timestamp": "2025-06-16T10:30:00.000Z",
  "service": "AIDARA API",
  "version": "3.0.0",
  "checks": {
    "database": "ok",
    "openai": "ok"
  },
  "uptime": 123456,
  "memory": {
    "rss": 123456789,
    "heapTotal": 123456789,
    "heapUsed": 123456789
  }
}

Endpoint principal. Envía un mensaje al asistente y recibe la respuesta en streaming en tiempo real.

POST /chat/send

Cabeceras requeridas:

X-API-Key: tu-api-key
Content-Type: application/json

Parámetros del cuerpo:

Parámetro Tipo Requerido Descripción
message string ✅ Mensaje a enviar al asistente (máx 4000 chars)
thread_id string Opcional ID del thread existente (se crea uno nuevo si no se proporciona)

Respuesta (Streaming SSE):

La respuesta llega como Server-Sent Events con los siguientes tipos de eventos:

Tipo de Evento Descripción Datos
start Inicio del procesamiento Mensaje informativo
thread_id ID del thread (nuevo o existente) String con ID del thread
content Contenido progresivo de la respuesta Fragmentos de texto
complete Respuesta completa con estadísticas Mensaje completo y métricas
error Error durante el procesamiento Mensaje de error
end Fin del stream Sin datos

Ejemplo de flujo de eventos:

// Primer evento: Inicio
data: {"type": "start", "timestamp": "2025-06-16T10:30:00.000Z", "data": "Iniciando procesamiento..."}

// ID del thread
data: {"type": "thread_id", "timestamp": "2025-06-16T10:30:01.000Z", "data": "thread_abc123"}

// Eventos de contenido progresivo
data: {"type": "content", "timestamp": "2025-06-16T10:30:02.000Z", "data": "Hola, "}
data: {"type": "content", "timestamp": "2025-06-16T10:30:02.100Z", "data": "¿en qué puedo "}
data: {"type": "content", "timestamp": "2025-06-16T10:30:02.200Z", "data": "ayudarte?"}

// Evento de finalización
data: {"type": "complete", "timestamp": "2025-06-16T10:30:03.000Z", "data": {
  "message": "Hola, ¿en qué puedo ayudarte?",
  "tokens": {
    "input": 15,
    "output": 8,
    "total": 23
  }
}}

// Fin del stream
data: {"type": "end", "timestamp": "2025-06-16T10:30:03.100Z"}

💻 Ejemplos de Código

Ejemplos con cURL

# Verificar estado de la API
curl -X GET https://api.wittymindsets.com/aidara/health

# Verificar estado detallado
curl -X GET https://api.wittymindsets.com/aidara/health/detailed

# Enviar mensaje con streaming
curl -X POST \
  https://api.wittymindsets.com/aidara/chat/send \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explícame qué es la IA",
    "thread_id": "thread_abc123"
  }' \
  --no-buffer

Ejemplo con JavaScript (Browser)

class AidaraAPI {
  constructor(apiKey, baseUrl = 'https://api.wittymindsets.com/aidara') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async checkHealth() {
    const response = await fetch(`${this.baseUrl}/health`);
    return response.json();
  }

  async checkDetailedHealth() {
    const response = await fetch(`${this.baseUrl}/health/detailed`);
    return response.json();
  }

  async sendMessageStreaming(message, threadId = null, onContent, onComplete) {
    const response = await fetch(`${this.baseUrl}/chat/send`, {
      method: 'POST',
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        message,
        thread_id: threadId
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        buffer += decoder.decode(value, { stream: true });
        const lines = buffer.split('\n');
        buffer = lines.pop(); // Guardar línea incompleta

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            try {
              const data = JSON.parse(line.slice(6));
              
              switch (data.type) {
                case 'thread_id':
                  console.log('Thread ID:', data.data);
                  break;
                case 'content':
                  onContent(data.data);
                  break;
                case 'complete':
                  onComplete(data.data);
                  break;
                case 'error':
                  throw new Error(data.data);
                case 'end':
                  return;
              }
            } catch (e) {
              console.warn('Error parsing SSE data:', e);
            }
          }
        }
      }
    } finally {
      reader.releaseLock();
    }
  }
}

// Uso del cliente
const aidara = new AidaraAPI('tu-api-key');

// Verificar estado
aidara.checkHealth().then(console.log);

// Enviar mensaje con streaming
aidara.sendMessageStreaming(
  '¿Puedes explicarme qué es machine learning?',
  null,
  (content) => {
    // Mostrar contenido progresivamente
    document.getElementById('chat').innerHTML += content;
  },
  (data) => {
    console.log('Respuesta completa:', data.message);
    console.log('Tokens usados:', data.tokens);
  }
).catch(console.error);

Ejemplo con Python

import requests
import json

class AidaraAPI:
    def __init__(self, api_key, base_url='https://api.wittymindsets.com/aidara'):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            'X-API-Key': api_key,
            'Content-Type': 'application/json'
        }

    def check_health(self):
        """Verificar estado básico del servicio"""
        response = requests.get(f'{self.base_url}/health')
        response.raise_for_status()
        return response.json()

    def check_detailed_health(self):
        """Verificar estado detallado del servicio"""
        response = requests.get(f'{self.base_url}/health/detailed')
        response.raise_for_status()
        return response.json()

    def send_message_streaming(self, message, thread_id=None, on_content=None, on_complete=None):
        """Envía mensaje con streaming"""
        url = f'{self.base_url}/chat/send'
        data = {'message': message}
        if thread_id:
            data['thread_id'] = thread_id

        response = requests.post(
            url,
            headers=self.headers,
            json=data,
            stream=True
        )
        response.raise_for_status()

        for line in response.iter_lines():
            if line:
                line = line.decode('utf-8')
                if line.startswith('data: '):
                    try:
                        data = json.loads(line[6:])
                        event_type = data.get('type')
                        
                        if event_type == 'thread_id':
                            print(f"Thread ID: {data['data']}")
                        elif event_type == 'content':
                            if on_content:
                                on_content(data['data'])
                            else:
                                print(data['data'], end='', flush=True)
                        elif event_type == 'complete':
                            if on_complete:
                                on_complete(data['data'])
                            print(f"\nTokens: {data['data'].get('tokens', {})}")
                        elif event_type == 'error':
                            raise Exception(f"Error: {data['data']}")
                        elif event_type == 'end':
                            break
                            
                    except json.JSONDecodeError:
                        continue

# Ejemplo de uso
if __name__ == "__main__":
    aidara = AidaraAPI('tu-api-key')
    
    # Verificar estado
    print("Estado del servicio:")
    print(json.dumps(aidara.check_health(), indent=2))
    
    # Enviar mensaje con streaming
    print("\nEnviando mensaje...")
    aidara.send_message_streaming(
        "Explícame qué es la inteligencia artificial en términos simples"
    )

Ejemplo con Node.js

const fetch = require('node-fetch');

class AidaraAPI {
  constructor(apiKey, baseUrl = 'https://api.wittymindsets.com/aidara') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async checkHealth() {
    const response = await fetch(`${this.baseUrl}/health`);
    return response.json();
  }

  async checkDetailedHealth() {
    const response = await fetch(`${this.baseUrl}/health/detailed`);
    return response.json();
  }

  async sendMessageStreaming(message, threadId = null) {
    return new Promise((resolve, reject) => {
      const url = `${this.baseUrl}/chat/send`;
      const headers = {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json'
      };

      fetch(url, {
        method: 'POST',
        headers,
        body: JSON.stringify({
          message,
          thread_id: threadId
        })
      })
      .then(response => {
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }

        let fullResponse = '';
        let currentThreadId = null;

        response.body.on('data', (chunk) => {
          const lines = chunk.toString().split('\n');
          
          lines.forEach(line => {
            if (line.startsWith('data: ')) {
              try {
                const data = JSON.parse(line.slice(6));
                
                switch (data.type) {
                  case 'thread_id':
                    currentThreadId = data.data;
                    console.log(`Thread ID: ${currentThreadId}`);
                    break;
                  case 'content':
                    process.stdout.write(data.data);
                    fullResponse += data.data;
                    break;
                  case 'complete':
                    console.log(`\n✓ Completado`);
                    console.log(`Tokens: ${JSON.stringify(data.data.tokens)}`);
                    resolve({
                      threadId: currentThreadId,
                      message: fullResponse,
                      tokens: data.data.tokens
                    });
                    break;
                  case 'error':
                    reject(new Error(data.data));
                    break;
                  case 'end':
                    // Stream terminado
                    break;
                }
              } catch (e) {
                console.warn('Error parsing SSE:', e);
              }
            }
          });
        });

        response.body.on('error', reject);
      })
      .catch(reject);
    });
  }
}

// Uso
async function main() {
  const aidara = new AidaraAPI('tu-api-key');
  
  try {
    // Verificar estado
    console.log('Estado del servicio:');
    console.log(JSON.stringify(await aidara.checkHealth(), null, 2));
    
    console.log('\nEnviando mensaje...\n');
    
    const result = await aidara.sendMessageStreaming(
      '¿Puedes explicarme las ventajas del streaming en APIs?'
    );
    
    console.log(`\nRespuesta guardada en thread: ${result.threadId}`);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

⚠️ Códigos de Error

Código HTTP Descripción Solución
401 API Key requerida Incluye el header X-API-Key con tu clave válida
401 API Key inválida Verifica que la clave API sea correcta y esté activa
403 Límite mensual de tokens excedido Contacta para ampliar tu límite o espera al siguiente mes

Código HTTP Descripción Solución
400 Mensaje requerido Incluye el campo message en el cuerpo de la petición
400 Mensaje demasiado largo El mensaje debe tener máximo 4000 caracteres
400 Assistant ID no configurado Contacta soporte - problema de configuración de cuenta

Código HTTP Descripción Solución
429 Rate limit excedido Espera 1 minuto antes de realizar otra petición
429 Demasiadas peticiones Reduce la frecuencia de peticiones (máx 60/min)
429 Límite de rate de OpenAI excedido Intenta de nuevo en unos momentos - límite del proveedor de IA

Código HTTP Descripción Solución
500 Error interno del servidor Contacta con soporte técnico
500 Error al crear thread Reintenta la operación o contacta soporte
500 Error al enviar mensaje Verifica el formato del mensaje y reintenta
500 Error al ejecutar asistente Problema con el servicio de IA, contacta soporte
503 Error al conectar con OpenAI Servicio temporalmente no disponible, reintenta en unos minutos
503 Health check fallido Servicio degradado - algunos componentes no están disponibles

📋 Estructura de Respuesta de Error

{
  "success": false,
  "error": "Descripción del error",
  "code": "CODIGO_ESPECIFICO",
  "details": {
    // Información adicional del error (opcional)
  }
}

🌊 Errores Durante el Streaming

Durante el streaming, los errores se envían como eventos SSE del tipo error:

data: {
  "type": "error", 
  "timestamp": "2025-06-16T10:30:00.000Z",
  "data": "Descripción del error"
}
Error Descripción Acción
El asistente falló Error en la ejecución del asistente de IA Reintenta o contacta soporte
El procesamiento fue cancelado El run fue cancelado por el sistema Reintenta la petición
El procesamiento expiró Timeout en la respuesta del asistente Reintenta con un mensaje más simple
El asistente no generó respuesta Problema de configuración del asistente Contacta soporte técnico

💡 Manejo de Errores en Cliente

Implementa siempre manejo de errores robusto: captura errores HTTP, eventos SSE de error, timeouts de conexión y desconexiones inesperadas. Para errores 429 (rate limiting), implementa backoff exponencial.

📞 Soporte y Contacto

🛠️ Soporte Técnico

  • Email: support@wittymindsets.com
  • Horario: Lunes a Viernes, 9:00 - 18:00 (CET)
  • Tiempo de respuesta: < 8 horas laborales

🔧 Información para Soporte

Cuando contactes con soporte, incluye:

  • • Código de error HTTP
  • • Mensaje de error completo
  • • Timestamp de la petición
  • • Tu API Key (solo los primeros 8 caracteres)
  • • Código de ejemplo que falla

💼 Soporte Comercial

  • Email: comercial@wittymindsets.com
  • Horario: Lunes a Viernes, 9:00 - 18:00 (CET)
  • Consultas: Precios, límites, upgrades

🌐 Enlaces Útiles

🚀 ¿Listo para empezar?

Solicita tu API Key personalizada y comienza a integrar asistentes de IA en minutos:

  1. Contacta comercial@wittymindsets.com
  2. Recibe tu API Key y configuración de asistente
  3. Prueba el endpoint de health: GET /health
  4. Prueba los ejemplos de código con POST /chat/send
  5. Integra en tu aplicación
  6. ¡Disfruta del streaming en tiempo real!