SDK y ejemplos

Todo lo que necesitas para llamar a Shara desde tu código: autenticación por token Bearer, la tabla de endpoints principales y ejemplos listos para copiar en curl y JavaScript (fetch). La API es REST plana sobre HTTPS, con cuerpos y respuestas en JSON, así que cualquier cliente HTTP estándar sirve mientras llegan los SDK oficiales.

Todas las rutas cuelgan de https://api.sharasaas.com/v1. El transporte es HTTPS obligatorio (TLS 1.2+), el cuerpo de las peticiones y las respuestas son JSON (Content-Type: application/json) y el modo streaming devuelve Server-Sent Events (text/event-stream). Toda la infraestructura está alojada en la Unión Europea.

Las integraciones se autentican con una API key de Shara. La generas desde Ajustes → API Keys (requiere rol de administración y verificación en dos pasos) y la envías en cada petición con la cabecera estándar Authorization:

La API pública de agentes todavía no está abierta. Shara está en beta privada y los ejemplos de abajo describen la forma que tendrá, no un endpoint que puedas llamar hoy. Si lo pruebas ahora responde 404, y es lo esperado. Escribe a soporte@aiginer.com si quieres acceso anticipado.

Authorization: Bearer shara_sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

La clave tiene el prefijo fijo shara_sk_live_ seguido de una parte secreta. Se muestra completa una única vez, en el momento de crearla: guárdala en tu gestor de secretos. Después, el panel solo enseña el prefijo para que la identifiques. Cada clave lleva scopes (permisos mínimos) y caduca por defecto a los 365 días; rótala sin ventana de corte desde POST /v1/api-keys/{id}/rotate.

Trata la API key como una contraseña de servidor: nunca la incrustes en el navegador, en apps móviles ni en repositorios públicos. Vive en variables de entorno del backend. Si sospechas que se ha filtrado, revócala (DELETE /v1/api-keys/{id}) y emite una nueva.

Resumen de la superficie que necesitas para integrar. El orquestador del workspace es Amadeus: recibe tu petición, decide qué agente departamental la atiende y coordina el trabajo. Puedes dirigirte a Amadeus (y dejar que enrute) o a un agente concreto por su slug.

El campo slug de un agente identifica al miembro de tu equipo digital: amadeus (orquestador), carnegie (Ventas), kotler (Marketing), graham (Finanzas), holmes (Legal), maslow (RRHH), deming (Operaciones), rosling (Analítica), porter (Estrategia), turing (IT) y carlzon (Atención). Los agentes disponibles dependen de tu plan.

Una petición mínima envía un alias de modelo y la lista de messages. El alias es lo único que se acepta para seleccionar la potencia del modelo: Symphony (máxima capacidad), Sonata (equilibrio coste/calidad), Prelude (ágil y económico) o Concerto (modelos locales del Plan Local).

curl -sS https://api.sharasaas.com/v1/agents/amadeus/messages \
  -H "Authorization: Bearer shara_sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Sonata",
    "messages": [
      { "role": "user", "content": "Resume las novedades de soporte de esta semana." }
    ],
    "effort": "medium"
  }'

La respuesta síncrona (200) devuelve el alias usado, el content (ya redactado) y el desglose de usage en tokens, que Shara traduce a STU para tu facturación:

{
  "alias": "Sonata",
  "content": "Esta semana soporte cerró 34 tickets…",
  "usage": {
    "inputTokens": 184,
    "outputTokens": 412
  }
}

Equivalente en Node.js / TypeScript con fetch nativo. Ramifica siempre por el campo error (cadena estable en snake_case), nunca por el texto de message:

const BASE = 'https://api.sharasaas.com/v1';
const API_KEY = process.env.SHARA_API_KEY; // nunca en el cliente

const res = await fetch(`${BASE}/agents/amadeus/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    alias: 'Sonata',
    messages: [
      { role: 'user', content: 'Resume las novedades de soporte de esta semana.' },
    ],
    effort: 'medium',
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`Shara API ${res.status}: ${error}`);
}

const data = await res.json();
console.log(data.alias, data.content, data.usage);

Las respuestas nunca revelan el modelo real detrás de un alias. Un redactor procesa cada salida (contenido, mensajes de error y volcados de herramientas) antes de cruzar la red, de modo que solo verás Symphony · Sonata · Prelude · Concerto. No dependas de nombres de proveedor: no aparecerán.

El límite estándar es de 60 peticiones por minuto en ventana deslizante. Cada respuesta trae cabeceras para que tu cliente se autorregule; úsalas en vez de adivinar:

• X-RateLimit-Limit: tope de peticiones de la ventana actual.
• X-RateLimit-Remaining: peticiones que te quedan; frena antes de llegar a 0.
• X-RateLimit-Reset: epoch (segundos) en que se reinicia la ventana.
• Retry-After: solo en 429, segundos a esperar antes de reintentar.

Al superar el límite recibes 429 con { "error": "rate_limit_exceeded", "retryAfterSec": <n> }; respeta Retry-After con backoff exponencial. Ten en cuenta además dos cortes distintos del límite de peticiones: quota_exceeded cuando agotas tu cuota de STU del periodo, y kill_switch cuando salta un tope de gasto (5 € por run, 50 € por hora y 400 € por día, que a la tarifa de excedente son 1 M, 10 M y 80 M STU). Ambos también son 429, pero se resuelven esperando al reinicio de cuota o revisando el consumo, no reintentando en bucle.

Con la disponibilidad general (GA) publicaremos SDKs oficiales para Node.js / TypeScript y Python que envuelven autenticación, reintentos y streaming. Mientras tanto, los ejemplos de esta página cubren el 100 % de la API: es REST plana, con cabeceras estándar y JSON, y funciona con cualquier cliente HTTP.

¿Quieres acceso anticipado a la API o subir tu límite de peticiones por workspace? Escríbenos a api@aiginer.com indicando tu caso de uso, o a soporte@aiginer.com para cualquier duda de integración.