API pública

Polaris expone una API pública mínima para integraciones confiables desde servidor. La primera versión se enfoca en lecturas seguras por workspace y en un endpoint de chat sin streaming, usando API keys, scopes y auditoría de requests.

Autenticación

Crea una API key desde Workspace Settings y envíala como Bearer token.

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/me

Polaris solo muestra la llave completa una vez. Guárdala en un entorno seguro de servidor y revócala cuando deje de ser necesaria.

Formato de respuesta

Las respuestas exitosas incluyen data, request_id y metadata de la API.

{
  "data": [],
  "request_id": "req_123",
  "meta": {
    "workspace_id": "workspace_id",
    "api_version": "v1"
  }
}

Los errores usan un formato consistente y nunca exponen stack traces.

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Missing required scope: chatbots:read",
    "request_id": "req_123"
  }
}

Scopes

Asigna solo los scopes que necesita cada integración.

El primer endpoint de escritura está limitado a mensajes de chatbot. Otros scopes de escritura quedan reservados para futuras superficies de API.

Endpoints

Paginación y filtros

Los endpoints de lista soportan limit y page.

curl -H "Authorization: Bearer plr_live_..." \
  "https://api.polarisai.mx/api/public/v1/conversations?limit=20&page=1"

Filtros disponibles:

Ejemplos

Listar chatbots:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/chatbots

Consultar uso y límites:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/usage

Listar mensajes de una conversación:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/conversations/{conversation_id}/messages

Enviar un mensaje a un chatbot:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"¿Cómo creo un chatbot?"}'

Usa Idempotency-Key cuando reintentes requests de escritura después de un timeout o fallo de red:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-123" \
  -d '{"message":"¿Cómo creo un chatbot?"}'

Si envías la misma key con el mismo body, Polaris devuelve la respuesta original sin duplicar mensajes ni consumo. Si reutilizas la misma key con otro body, Polaris devuelve IDEMPOTENCY_KEY_CONFLICT.

Continuar una conversación existente:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id":"conversation_id",
    "message":"¿Qué debo probar antes de publicarlo?",
    "external_user_id":"cliente_123",
    "metadata":{"source":"partner_app"}
  }'

Polaris siempre registra las conversaciones creadas por API como source: public_api. Si envías metadata.source, trátalo como contexto de tu integración, por ejemplo partner_app o crm_sync. Polaris conserva source=public_api como attribution canónica para auditoría, filtros y soporte.

Atribución de conversaciones

Las conversaciones creadas con POST /api/public/v1/chatbots/{chatbot_id}/messages se marcan como public_api.

Polaris guarda el prefijo de la API key y el external_user_id opcional para auditoría y soporte. La API key completa nunca se guarda.

Al listar conversaciones, el campo source ayuda a distinguir tráfico de API, widget, soporte, WhatsApp y dashboard.

Las respuestas de chat incluyen la respuesta del asistente, citas seguras y metadata de uso.

{
  "data": {
    "conversation_id": "conversation_id",
    "message_id": "message_id",
    "answer": "Empieza creando el chatbot en el workspace correcto...",
    "citations": [
      {
        "document_id": "document_id",
        "title": "Crear un chatbot",
        "datasource_name": "Polaris Docs",
        "excerpt": "Crea el chatbot dentro del workspace correcto...",
        "score": 0.82,
        "rank": 1
      }
    ],
    "usage": {
      "ai_messages_incremented": true
    }
  },
  "request_id": "req_123",
  "meta": {
    "workspace_id": "workspace_id",
    "api_version": "v1"
  }
}

El endpoint de chat todavía no soporta streaming. No expone prompts internos, tools, embeddings ni chunks completos de documentos.

Seguridad

• Las API keys están limitadas a un workspace.
• Las llaves revocadas o expiradas dejan de autenticar inmediatamente.
• Polaris no expone prompts internos, tools, chunks de documentos ni logs del sistema.
• Los mensajes por API respetan los límites de AI messages y las políticas de grace/blocked del workspace.
• Los writes públicos soportan Idempotency-Key para que los retries del cliente sean seguros.
• Los rate limits protegen la API contra ráfagas y abuso. Los límites del plan siguen controlando el consumo comercial.
• Las respuestas limitadas por rate limit devuelven RATE_LIMIT_EXCEEDED con Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
• Usa API keys solo desde entornos de servidor confiables, no desde código público del navegador.
• Cada request autenticado se audita con request ID, prefijo de la llave, scope, endpoint y status code.