Referencia

Pingway Hub API

API REST del Hub de Pingway. Una app de terceros envía una notificación a un device pareado; el device la recibe por WebSocket (Android) o push APNs (iOS), la muestra, y devuelve `delivered` y `ack`. A diferencia de un push masivo, el envío con `requireAck: true` no se considera completado hasta que llega el ACK del receptor, y el Hub reintenta hasta lograrlo. Esta especificación cubre la API que usa un integrador. Los endpoints de pareo (`/api/pairing`, `/api/installations`) y los del cliente receptor (`/api/device`) son parte del flujo interno de las apps Android/iOS y no se documentan acá.

openapi.json ↓Base: https://hub.pingway.io

Autenticación

API key del tenant, con formato `pw_<tenant_slug>_<32_chars>`. Se genera en el Console (console.pingway.io) y se muestra una sola vez. Va como `Authorization: Bearer pw_...`; nunca en la querystring.

curl -X POST https://hub.pingway.io/api/notifications \
  -H "Authorization: Bearer pw_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"toDeviceId":"kitchen-01","title":"Nuevo pedido","requireAck":true}'

Servidor MCP

para agentes

Además de la API REST, Pingway expone un servidor MCP (Model Context Protocol) en https://hub.pingway.io/mcp. Sirve para que un agente mande alertas y sepa si una persona las atendió — incluido el caso de un agente autónomo que necesita confirmación humana antes de continuar.

Transporte Streamable HTTP, sin sesión, autenticado con la misma API key. Para conectarlo desde Claude Code:

claude mcp add --transport http pingway https://hub.pingway.io/mcp \
  --header "Authorization: Bearer pw_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Herramientas disponibles:

send_notification— envía una alerta a un dispositivo
broadcast_notification— envía a todos los dispositivos de uno o más grupos
get_notification_status— consulta si ya la confirmaron
list_devices— lista los dispositivos y su estado
list_tags— lista los grupos disponibles

La server card está publicada en /.well-known/mcp/server-card.json.

Notifications

Envío y consulta de notificaciones

post/api/notifications

Enviar una notificación a un device

Crea la notificación y responde `201` de inmediato con estado `queued`; la entrega ocurre en background. El progreso real (`sent` → `delivered` → `ack`) se sigue por `GET /api/notifications/{id}` o por webhook. Si el device está pausado por su usuario, la notificación se cancela en el momento (`status: canceled`) en vez de encolarse.

Idempotency-Key: header — Clave opcional para reintentos seguros. Un segundo POST con la misma clave devuelve la notificación original con `idempotent: true` y no consume cuota.

{
  "toDeviceId": "kitchen-01",
  "title": "Nuevo pedido",
  "body": "Mesa 4 — 2 platos",
  "requireAck": true
}

get/api/notifications

Listar notificaciones de un device

toDeviceId: query · requerido — `deviceId` público del pareo, o el UUID interno.
status: query
limit: query

post/api/notifications/broadcast

Enviar a todos los devices con uno o más tags

Resuelve los devices del tenant que tienen al menos uno de los tags y crea una notificación independiente por cada uno (status y ACK propios), agrupadas por `broadcastId`. Consume tantos créditos de plan como devices matcheados: si la cuota no alcanza para todos, se rechaza el broadcast entero en vez de entregarlo a medias.

{
  "tags": [
    "cocina",
    "barra"
  ],
  "title": "Cierre en 10 min",
  "requireAck": false
}

get/api/notifications/{id}

Estado de una notificación

id: path · requerido

Devices

Devices pareados del tenant

get/api/devices

Listar devices del tenant

limit: query
tag: query — Filtra por tag exacto (case-insensitive).
onlineOnly: query — Devuelve solo los devices con WebSocket abierto.

get/api/devices/{deviceId}

Detalle de un device

Acepta el `deviceId` público del pareo o el UUID interno.

deviceId: path · requerido

Webhooks

Eventos salientes de entrega y ACK

post/api/webhooks

Registrar un webhook

El `secret` se devuelve **una sola vez**, en esta respuesta. Se usa para firmar el payload de cada entrega; el listado nunca lo incluye. Feature de plan Pro en adelante.

{
  "url": "https://example.com/hooks/pingway",
  "events": [
    "notification.ack"
  ]
}

get/api/webhooks

Listar webhooks del tenant

delete/api/webhooks/{id}

Borrar un webhook

id: path · requerido

post/api/webhooks/{id}/test

Disparar una entrega de prueba

id: path · requerido

get/api/webhooks/_events

Eventos disponibles para suscribirse

Health

Estado del servicio

get/health