API REST

Lea y escriba sus monitores, lea y actualice incidentes, y suba source maps. Todo esto usa las mismas comprobaciones de permisos y el mismo filtro de aislamiento entre clientes que el panel — no hay una implementación aparte para la API que pueda desviarse de él.

Incluida en todos los planes, también en el gratuito. No hay complemento que comprar ni nivel que la desbloquee.

URL base

https://vitrinaengine.com/api/v1

Autenticación

Cree una clave en Configuración → Claves de API y envíela como token bearer. La clave se muestra una sola vez, al crearla, y se guarda solo como hash — si la pierde, cree otra.

curl https://vitrinaengine.com/api/v1/summary \
  -H "Authorization: Bearer vte_su_clave_aqui"

Una clave nunca otorga más de lo que tenía quien la creó. Está ligada a su membresía, así que lleva su rol: una clave creada por alguien con un rol de solo lectura no puede escribir, envíe lo que envíe. Una clave también puede confinarse a un solo espacio de trabajo, y en ese caso cada respuesta se filtra a ese espacio y lo que quede fuera no existe para esa clave.

Quitar a alguien de su organización revoca las claves que creó, en la misma operación. Revocar el acceso tiene que llevarse las credenciales con él, o la persona conserva una que funciona.

Convenciones

Toda respuesta correcta es un objeto JSON con una propiedad data. Todo fallo es un objeto JSON con una propiedad error que contiene una frase pensada para una persona.

{ "data": { "id": "8f14e45f-…", "name": "Sitio de marketing" } }

{ "error": "This key cannot create monitors." }

Las respuestas se envían con Cache-Control: private, no-store. Son datos propios de una clave sobre un origen compartido y no deben quedar guardados en ningún proxy.

Los mensajes de error se devuelven en inglés. Los genera la API, no esta página, y son cadenas estables sobre las que se puede registrar o comparar.

Códigos de estado

Límites de peticiones

Por organización, no por clave — crear otra clave no los sube.

Pasarse responde 429 con una cabecera Retry-After que indica los segundos enteros que faltan para que la ventana se reinicie. Respétela en lugar de reintentar de inmediato.

Están puestos donde una integración normal nunca llega: un panel de pared que consulta cada diez segundos gasta seis de las 120 lecturas. Son iguales en todos los planes, porque los endpoints de colección devuelven todo en una sola respuesta — una cuenta con quinientos monitores no necesita más peticiones que una con veinte. Los source maps tienen una ventana por hora porque llegan en bloque al desplegar, donde un front end puede tener cien chunks.

404 en lugar de 403, a propósito

Un id que pertenece a otro cliente responde «Not found.», no «Forbidden.». Un 403 confirmaría que el registro existe, lo que convertiría al endpoint en una forma de averiguar si un id es real. No lea un 404 como prueba de que algo no existe en ninguna parte — solo de que no existe nada que esta clave pueda ver.

Endpoints

GET /summary

Conteos, para un panel de pared o un resumen diario. Requiere monitor:read.

{
  "data": {
    "total": 42, "up": 39, "degraded": 1, "down": 1,
    "paused": 1, "pending": 0,
    "openIncidents": 2, "suppressedIncidents": 1
  }
}

suppressedIncidents cuenta los incidentes retenidos por ser el alcance de otro. Son reales, y no son caídas separadas.

GET /monitors

Todos los monitores que la clave puede ver. Requiere monitor:read. Cada uno lleva id, name, kind, status, statusSince, enabled, intervalSeconds, tags, workspace, lastCheckedAt, lastResponseTimeMs, lastMessage, uptime24h, uptime30d y openIncidentId.

config nunca se devuelve. En algunos tipos contiene cabeceras de solicitud y credenciales, y una clave de solo lectura no debería ser una forma de recuperar los secretos que alguien escribió en un formulario.

POST /monitors

Requiere monitor:create. Necesita name, kind, workspaceId y config. Opcionales: intervalSeconds (por defecto 300), confirmations, dependsOn.

curl -X POST https://vitrinaengine.com/api/v1/monitors \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sitio de marketing",
    "kind": "http",
    "workspaceId": "…",
    "intervalSeconds": 60,
    "config": {
      "url": "https://example.com",
      "assertions": [{ "type": "status_code", "operator": "lt", "value": "400" }]
    }
  }'

Responde 201 con el id nuevo. El intervalo se ajusta al mínimo de su plan en lugar de rechazarse, así que pedir 10 segundos en un plan cuyo mínimo es 60 le da 60 — si le importa, vuelva a leerlo.

GET /monitors/{id}

Un monitor, con todo lo que da la lista más paused. Requiere monitor:read.

PATCH /monitors/{id}

Envíe solo lo que quiera cambiar: name, intervalSeconds, confirmations, enabled, config o paused.

paused se comprueba contra monitor:pause y todo lo demás contra monitor:update, por separado — una clave que puede pausar pero no editar todavía puede pausar. Enviar un cambio vacío es un 400.

El monitor se vuelve a leer y se devuelve, en lugar de repetirle lo que envió, así que lo que ve es lo que quedó guardado.

# Silenciar un monitor mientras dura un despliegue.
curl -X PATCH https://vitrinaengine.com/api/v1/monitors/$ID \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{"paused": true}'

DELETE /monitors/{id}

Requiere monitor:delete. Responde { "data": { "id": "…", "deleted": true } }.

GET /incidents

Requiere incident:read. Acepta ?open=true para los que están abiertos, y ?limit= (por defecto 50, tope 200 — pedir más se responde con 200 en lugar de rechazarse).

Cada uno lleva id, monitorId, monitorName, title, cause, status, severity, startedAt, resolvedAt, durationSeconds, acknowledgedAt y rootIncidentId.

rootIncidentId es el campo que mirar si arma un feed de alertas. Cuando está presente, este incidente es el alcance de otro — se cayó el servidor de base de datos y este es uno de los doce servicios que están detrás. Sáltelos y recibe una alerta en lugar de trece.

GET /incidents/{id}

Un incidente. Requiere incident:read. Los mismos campos que la lista, más workspaceId.

No devuelve la cronología del incidente — los comentarios y los cambios de estado que se ven en el panel no están en este endpoint. Si los necesita, dígalo y se pueden agregar; documentarlos aquí sin que existan sería peor que la ausencia.

PATCH /incidents/{id}

Envíe status con valor "acknowledged" o "resolved", o un comment, o ambos. Cada uno se comprueba contra su propio permiso: incident:acknowledge, incident:resolve, incident:comment. Agregar "publish": true a un comentario lo publica en la página de estado y requiere además status_page:manage.

# Un runbook que arregló la causa puede cerrar su propio incidente.
curl -X PATCH https://vitrinaengine.com/api/v1/incidents/$ID \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "comment": "Reiniciado por el runbook.", "publish": true}'

POST /sourcemaps

Suba un source map para que las trazas minificadas se resuelvan. Requiere monitor:create. Necesita projectRef (un número) y filename, más el mapa en sí como map (JSON) o mapGzipBase64. Opcionales: debugId y release.

Envíe un debug id o un release. Un mapa sin ninguno de los dos no se puede asociar a una traza y quedará ahí sin hacer nada. La correspondencia se busca primero por debugId y después por release más nombre de archivo.

Los mapas se resuelven cuando se lee una incidencia, no al subirlos, así que uno subido después de que llegaran los errores igual sirve — que es el orden habitual.

Lo que esta API deliberadamente no devuelve

• El config de un monitor. Puede contener credenciales.
• Desde qué región se ejecutó una verificación. Dónde verificamos es decisión nuestra y podemos cambiarlo a medida que colocamos y movemos sondas. Sería una promesa sobre nuestra infraestructura sobre la que usted no podría actuar, y tampoco se muestra en ninguna otra parte del producto.

Versionado

La versión va en la ruta. Se agregarán campos a las respuestas — trate los desconocidos como algo a ignorar y no como un error — pero nada se quitará de v1 ni cambiará de significado dentro de ella.

¿Falta algo?

La superficie es deliberadamente pequeña: cubre un panel de pared, un resumen en un chat y un script de despliegue que silencia un monitor mientras dura una publicación. Si está construyendo algo que no alcanza, escriba a support@vitrinaengine.com — saber qué quiere la gente de verdad es como se elige el siguiente endpoint.

Precios · Términos