Sentinel Public API v1

Base URL: https://app.sentinel.app · Spec OpenAPI: /v1/openapi.json

Autenticación

Generá una API key desde /[slug]/settings/api-keys. La key se ve UNA sola vez al crear — guardala segura. Todas las requests llevan:

Authorization: Bearer sk_live_<tu-key>

Las keys tienen scopes (ej: contacts:read, messages:write) y rate limit per minute configurable.

Rate limiting

Default: 60 req/min por API key (sliding window 60s). Cuando excedés recibís 429 con header Retry-After.

Endpoints

GET /v1/me

Devuelve workspace + scopes de la key. Útil para validar la key al iniciar.

GET /v1/contacts

Lista contactos (provenientes de Hivium, WhatsApp, etc.). Query: ?limit=50, ?cursor=<id>, ?q=busqueda.

curl -H "Authorization: Bearer sk_live_..." \
  "https://app.sentinel.app/v1/contacts?limit=25"

GET /v1/conversations

Lista canales activos/archivados. Query: ?status=active|archived.

POST /v1/messages/send

Encola un mensaje outbound. Body:

{
  "contact_phone": "+5491234567890",
  "text": "Hola desde la API",
  "metadata": { "campaign": "promo-mayo" }
}

Respuesta: 202 con { id, status: "queued", created_at }. Un worker async rutea al provider correspondiente.

Errores

Formato consistente:

{ "error": { "code": "invalid_api_key", "message": "..." } }

SDK TypeScript

Próximamente como paquete @sentinel/sdk. Por ahora viene incluido en src/lib/sdk/sentinel-client.ts dentro del repo.

import { SentinelClient } from '@sentinel/sdk'

const sentinel = new SentinelClient({ apiKey: process.env.SENTINEL_API_KEY! })
const { data } = await sentinel.contacts.list({ q: 'juan' })

Webhooks (próximamente)

Sentinel emitirá eventos hacia tu endpoint cuando: llegue mensaje inbound, suba un nuevo lead, se complete una sugerencia IA. Firmados con HMAC SHA256.