Referencia de la API
Bienvenido a la documentación de la API de AgentsGT. Esta API te permite interactuar programáticamente con tus agentes de IA, recuperar el historial de chat y acceder a métricas de uso.
URL Base
Todas las solicitudes a la API deben realizarse a:
https://agentsgt.com/api/v1
Autenticación
AgentsGT usa API keys para la autenticación. Puedes crear y administrar API keys desde la página de configuración de tu organización.
Formato de la API Key
Las API keys constan de dos partes:
- Public Key: Comienza con
pk_(se puede almacenar de forma segura en código del lado del cliente) - Secret Key: Comienza con
sk_(debe mantenerse segura y nunca exponerse)
Usando Tu API Key
Incluye tu API key en el encabezado Authorization de cada solicitud:
Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}
Ejemplo:
Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890
Límite de Solicitudes
Las API keys pueden tener límites de solicitudes configurados por organización. Si excedes tu límite de solicitudes, recibirás una respuesta 429 Too Many Requests.
Formato de Respuesta
Todas las respuestas de la API se devuelven en formato JSON con la siguiente estructura:
Respuesta Exitosa:
{
"success": true,
"data": { ... }
}
Respuesta de Error:
{
"success": false,
"error": "Error message"
}
Códigos de Estado HTTP Comunes
| Código de Estado | Descripción |
|---|---|
200 | Éxito - La solicitud se completó exitosamente |
400 | Solicitud Incorrecta - Parámetros de solicitud inválidos |
401 | No Autorizado - API key inválida o faltante |
403 | Prohibido - La API key no tiene permiso |
404 | No Encontrado - El recurso no existe |
429 | Demasiadas Solicitudes - Se excedió el límite de solicitudes |
500 | Error Interno del Servidor - Algo salió mal de nuestro lado |
Endpoints Disponibles
Agentes
- Obtener Todos los Agentes - Recupera todos los agentes de tu organización
Historial de Chat
- Obtener Historial de Chat por Agente - Recupera el historial de conversaciones de un agente específico
- Obtener Historial de Chat por Identificador - Recupera el historial de conversaciones de un usuario/sesión específico
Métricas
- Obtener Métricas por Organización - Recupera métricas de consumo y uso de toda la organización
- Obtener Métricas por Agente - Obtiene métricas detalladas de un agente específico
- Obtener Métricas por Identificador - Rastrea el consumo de un usuario/sesión específico
Mejores Prácticas
- Protege Tus API Keys: Nunca subas las claves secretas al control de versiones ni las expongas en código del lado del cliente
- Usa Variables de Entorno: Almacena las API keys en variables de entorno, no en tu código
- Maneja los Errores Correctamente: Siempre verifica los códigos de estado de respuesta y maneja los errores de forma apropiada
- Monitorea el Uso: Mantén un seguimiento de tu uso de la API para evitar alcanzar los límites de solicitudes
- Actualización de Último Uso: Las API keys rastrean automáticamente cuándo fueron usadas por última vez con fines de seguridad