centinela / risk-api / v1
All systems operational Get API Key →
Centinela Risk API v1

Security intelligence
for LATAM operations

Integrate real-time security conditions, incident data, and risk scoring for Venezuela directly into your logistics, fleet management, or enterprise systems.

REST API JSON responses HTTPS only Datos verificados en vivo 24 Venezuelan states Real-time + historical
01 Overview

The Centinela Risk API provides programmatic access to security conditions data for Venezuela. Built for companies operating in the region — logistics firms, food delivery platforms, insurers, mining companies — that need to integrate risk intelligence into their own systems.

BASE URL https://riskscore-f6mmcvp3ia-uc.a.run.app
Beta notice

The API is currently in beta. Endpoints and response schemas may change. We will notify API key holders before any breaking changes.

02 Authentication

All API requests require authentication via an API key passed in the x-api-key request header. Keys are prefixed with cnt_live_ for production.

🔑

Get your API key

Send an email to api@appcentinela.com with your company name and intended use case. Keys are provisioned within 24 hours.

# Pass your API key in every request header
curl https://riskscore-f6mmcvp3ia-uc.a.run.app/v1/risk?state=miranda \
  -H "x-api-key: cnt_live_YOUR_KEY_HERE"
const response = await fetch('https://riskscore-f6mmcvp3ia-uc.a.run.app/v1/risk?state=miranda', {
  headers: {
    'x-api-key': 'cnt_live_YOUR_KEY_HERE'
  }
});
const data = await response.json();
import requests

headers = {"x-api-key": "cnt_live_YOUR_KEY_HERE"}
response = requests.get(
    "https://riskscore-f6mmcvp3ia-uc.a.run.app/v1/risk",
    params={"state": "miranda"},
    headers=headers
)
03 Plans & Rate Limits

Rate limits are applied per API key on a rolling 30-day window. Exceeding your limit returns a 429 response.

Basic
$99/mo
1,000 req / month
  • Risk Score
  • Incidents
  • Score History
  • Email support
Pro
$499/mo
10,000 req / month
  • All Basic features
  • Layers
  • Webhooks
  • Priority support
  • SLA 99.5%
  • Custom alerts
Enterprise
Custom
Unlimited
  • All Pro features
  • Dedicated support
  • Custom SLA
  • Colombia + Ecuador
Rate limit headers

Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers so you can track usage programmatically.

04 Endpoints
GET /v1/risk Current risk score for a Venezuelan state Basic+

Returns the current security conditions index (0–100) for a given state, along with trend, active incident count, and a brief AI-generated summary.

Query Parameters
ParameterTypeRequiredDescription
state string required Venezuelan state name in lowercase (e.g. miranda, monagas). See full reference below.
200 OK Response 
{
  "state": "miranda",
  "risk_index": 62,
  "level": "elevated",
  "trend": "stable",
  "active_incidents": 7,
  "last_updated": "2026-06-04T03:00:00Z",
  "summary": "Miranda presents elevated security conditions concentrated in Guarenas-Guatire corridor. No significant changes in the last 48 hours.",
  "source": "Centinela"
}
GET /v1/incidents Recent security incidents with geo coordinates Basic+

Returns a paginated list of recent security incidents. Each incident includes coordinates, severity classification, and source metadata.

Query Parameters
ParameterTypeRequiredDescription
state string optional Filter by state. Omit to return incidents across all states.
limit integer optional Number of results (default: 20, max: 100).
days integer optional Lookback window in days (default: 7, max: 30).
200 OK Response 
{
  "incidents": [
    {
      "id": "inc_a8f21b",
      "type": "road_block",
      "severity": "medium",
      "state": "miranda",
      "municipality": "Guaicaipuro",
      "coordinates": { "lat": 10.3467, "lng": -67.0356 },
      "timestamp": "2026-06-03T14:32:00Z",
      "verified": true,
      "source": "Centinela"
    }
  ],
  "total": 42,
  "page": 1
}
GET /v1/layers GeoJSON layers for map rendering Basic+

Returns GeoJSON feature collections for map rendering. Useful for building custom maps with security overlays in Mapbox, Leaflet, or Google Maps.

Query Parameters
ParameterTypeRequiredDescription
type string optional Layer type: risk_zones, incidents, corridors. Default: all.
state string optional Filter by state.
200 OK GeoJSON Response 
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[-66.9, 10.5], [-66.7, 10.5], /* ... */]]
      },
      "properties": {
        "state": "miranda",
        "risk_index": 62,
        "level": "elevated"
      }
    }
  ]
}
GET /v1/score/history Historical risk score time series Basic+

Returns a time series of daily risk scores for trend analysis and reporting. Useful for board-level security reports and contract risk assessments.

Query Parameters
ParameterTypeRequiredDescription
state string required Venezuelan state name in lowercase.
days integer optional Number of historical days (default: 30, max: 90).
200 OK Response 
{
  "state": "miranda",
  "history": [
    { "date": "2026-05-05", "risk_index": 58, "incidents": 5 },
    { "date": "2026-05-06", "risk_index": 61, "incidents": 7 },
    { "date": "2026-05-07", "risk_index": 59, "incidents": 6 }
  ]
}
POST /v1/webhooks Register a webhook for real-time alerts Basic+

Register a URL to receive POST notifications when the risk index changes significantly or a critical incident is detected in your monitored states.

Request Body — application/json
FieldTypeRequiredDescription
url string required HTTPS URL to receive webhook POST requests.
states string[] required Array of state names to monitor (e.g. ["miranda", "monagas"]).
threshold integer optional Minimum risk index change to trigger notification (default: 10). 
curl -X POST https://registerwebhook-f6mmcvp3ia-uc.a.run.app/v1/webhooks \
  -H "x-api-key: cnt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/centinela-webhook",
    "states": ["miranda", "monagas", "anzóategui"],
    "threshold": 15
  }'
await fetch('https://registerwebhook-f6mmcvp3ia-uc.a.run.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'x-api-key': 'cnt_live_YOUR_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://yourapp.com/centinela-webhook',
    states: ['miranda', 'monagas'],
    threshold: 15
  })
});
200 OK Response 
{
  "webhook_id": "wh_9f3a12bc",
  "url": "https://yourapp.com/centinela-webhook",
  "states": ["miranda", "monagas"],
  "threshold": 15,
  "created_at": "2026-06-04T12:00:00Z",
  "status": "active"
}
05 Errors

The API uses standard HTTP status codes. Error responses include a machine-readable code and a human-readable message.

StatusCodeDescription
400 invalid_params Missing or malformed query parameters.
401 invalid_api_key API key is missing, invalid, or revoked.
403 plan_required Your current plan does not include access to this endpoint.
404 state_not_found The specified state does not exist in our database.
429 rate_limit_exceeded You have exceeded your plan's monthly request limit.
500 internal_error Unexpected server error. These are logged and addressed automatically. 
// Example error response (401)
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}
06 Venezuelan States Reference

Use these exact lowercase slugs in the state parameter.

07 Climate Risk API

Riesgo climático por estado o coordenada — inundación, incendio forestal, calor extremo, deslizamiento y sequía. Datos verificados de múltiples fuentes independientes. Proyecciones a 30 años.

Widget embebible

Además del API, Centinela provee un widget drop-in listo para integrar en cualquier app inmobiliaria, bancaria o de seguros. Funciona como el climate risk de Redfin — mapa con overlay + sheet de detalle por categoría. provided_by: "Centinela" aparece en cada widget.

GET /v1/climate Climate risk score por estado o coordenada Basic+

Devuelve el score de riesgo climático agregado y por categoría (flood, fire, heat, landslide, drought) para una ubicación en Venezuela. Acepta nombre de estado o coordenadas lat/lng.

Query Parameters
ParameterTypeRequiredDescription
state string optional* Nombre del estado en minúsculas (e.g. miranda). Requerido si no se usa lat/lng.
lat float optional* Latitud decimal. Usar junto con lng.
lng float optional* Longitud decimal. Usar junto con lat.
200 OK Response 
{
  "state": "miranda",
  "location": "Miranda, Venezuela",
  "overall_score": 7,
  "overall_level": "severe",
  "risks": {
    "flood":     { "score": 8, "level": "severe",   "trend": "rising",  "label": "Inundación" },
    "fire":      { "score": 2, "level": "low",      "trend": "stable",  "label": "Incendio forestal" },
    "heat":      { "score": 7, "level": "severe",   "trend": "rising",  "label": "Calor extremo" },
    "landslide": { "score": 6, "level": "moderate", "trend": "stable",  "label": "Deslizamiento" },
    "drought":   { "score": 4, "level": "moderate", "trend": "falling", "label": "Sequía" }
  },
  "horizon_years": 30,
  "last_updated": "2026-06-08T00:00:00Z",
  "source": "Centinela",
  "provided_by": "Centinela Climate Risk API",
  "widget_url": "https://cdn.appcentinela.com/climate-widget.js"
}
# Por estado
curl "https://climate-f6mmcvp3ia-uc.a.run.app/v1/climate?state=miranda" \
  -H "x-api-key: cnt_live_YOUR_KEY"

# Por coordenadas
curl "https://climate-f6mmcvp3ia-uc.a.run.app/v1/climate?lat=10.48&lng=-66.87" \
  -H "x-api-key: cnt_live_YOUR_KEY"
GET /v1/climate/history Histórico de riesgo climático — serie de tiempo anual Pro+

Devuelve la serie histórica de scores de riesgo climático año por año. Útil para análisis de tendencias, reportes de seguros, y modelos de riesgo hipotecario.

Query Parameters
ParameterTypeRequiredDescription
state string required Nombre del estado en minúsculas.
years integer optional Años de historial (default: 10, max: 30).
200 OK Response 
{
  "state": "miranda",
  "years": 10,
  "history": [
    {
      "year": 2016,
      "overall_score": 5,
      "risks": {
        "flood":     { "score": 6, "label": "Inundación" },
        "heat":      { "score": 5, "label": "Calor extremo" },
        "landslide": { "score": 5, "label": "Deslizamiento" }
      }
    },
    { "year": 2026, "overall_score": 7, "risks": { /* ... */ } }
  ],
  "source": "Centinela"
}
Widget embed — integración en 3 líneas

El widget de Climate Risk se integra con <script src="https://cdn.appcentinela.com/climate-widget.js"> y un <div> con tu API key y estado. El componente renderiza el mapa con overlay y el sheet de detalle por categoría — igual al screenshot de Apple Maps.

08 Changelog
v1.1.0 2026-06-08 current
  • Climate Risk API — GET /v1/climate por estado o lat/lng
  • Climate History — GET /v1/climate/history — serie anual hasta 30 años
  • 5 categorías: flood, fire, heat, landslide, drought con trend a 30 años
  • Widget drop-in embebible — integración en 3 líneas
  • Múltiples fuentes verificadas independientes
v1.0.0 2026-06-04
  • Initial public release
  • 6 endpoints live: risk, incidents, layers, scoreHistory, webhooks, generateApiKey
  • Real-time verified data for all 24 Venezuelan states
  • Plan-based rate limiting: Basic / Pro / Enterprise
Built by Centinela · Venezuela & LATAM risk intelligence
appcentinela.com