UrbeIA API Documentation

1. Get an API key

Register in /portal/api-keys. Keys are associated to dev tier and contracted packages.

2. First call

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.urbeia.com/dev/packages/global-metrics/health-score?city_code=VLC

# Docs prefix equivalent:
# dev/packages/global-metrics/health-score

2.b Prefixes in this documentation

This page documents contracts exposed outward by Bu surfaces. In some cases Bu publishes a direct HTTP route; in others, Bu consumes a kernel contract from product or portal and certifies that shape as an external surface. Bk is never a developer-facing surface. Internal operating lanes without an external contract remain outside this page. Legacy compatibility remains active for /api/v1/public/*, /api/v2/packages/*, /api/v1/dev/spatial/interventions/* and /api/v1/integration/uil/*.

3. Response shape

{
  "meta": {
    "city_code": "VLC",
    "resolved_at": "2026-03-10T10:00:00+01:00",
    "api_version": "v1",
    "fallback_mode": false
  },
  "data": { ... }
}

fallback_mode: true means temporary cached snapshot mode.

GET /api/v1/dev/system-state

Parameters:

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/system-state?city_code=VLC"

Response

{
  "meta": {
    "city_code": "VLC",
    "resolved_at": "2026-03-10T10:00:00+01:00",
    "timezone": "Europe/Madrid",
    "fallback_mode": false
  },
  "data": {
    "system": {
      "integration": 0.62,
      "status": "OK",
      "memory": 0.15,
      "stability_over_time": 0.35,
      "stress": 0.58,
      "variability": 0.49,
      "coherence": 0.62,
      "drift": 0.51
    },
    "behaviour": {
      "irritability": 0.27,
      "reactivity": 0.27,
      "anxiety": 0.41,
      "spatial_mode": "ACTIVE"
    },
    "resolved_at": "2026-03-10T10:00:00+01:00",
    "timezone": "Europe/Madrid"
  }
}

Fields

Typical use cases: sticky dashboard header, live pulse widget, system-health indicator in internal apps. For details (hypotheses, causality, narrative, hotspots) use the specific package endpoints.

GET /api/v1/dev/hypotheses/top

Top hypotheses detected by the cognitive kernel, ranked by confidence, one per sensory domain.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/hypotheses/top?city_code=VLC&limit=5"

{
  "meta": { "city_code": "VLC", "resolved_at": "2026-03-10T10:00:00+01:00" },
  "data": {
    "hypotheses": [
      { "domain": "mobility", "insight": "Recurrent evening saturation pattern on S3-S5 axes.", "confidence": 0.78 }
    ]
  }
}

GET /api/v1/dev/causality/top

Strongest causal relations detected between urban variables (domains and sensors), ranked by |rho|.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/causality/top?city_code=VLC&limit=10"

{
  "data": {
    "edges": [
      {
        "from": "D:noise", "to": "D:mobility",
        "from_label": "Noise", "to_label": "Mobility",
        "rho": 0.265, "confidence": 0.265, "support": 56144
      }
    ]
  }
}

rho ∈ [-1, 1]: sign and magnitude of the directed correlation. support: samples backing the relation.

GET /api/v1/dev/narrative/current

Current urban narrative: transitions, recurrent motifs and metadata on the selected source (richness-prioritised).

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/narrative/current?city_code=VLC"

{
  "data": {
    "narrative": {
      "transitions": [ { "from": 5, "to": 5, "count": 238 } ],
      "motifs": [ { "ngram": [6,6,6], "count": 273 } ],
      "meta": { "richness_score": 680, "source": "urban_narratives_history_rich" }
    }
  }
}

Per-endpoint examples

GET /health-score

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/health-score?city_code=VLC&at=2026-03-10T09:00:00Z"

{
  "meta": {"city_code": "VLC", "resolved_at": "2026-03-10T10:00:00+01:00", "timezone": "Europe/Madrid"},
  "data": {"score": 74.6, "stress": 0.31, "coherence": 0.72, "stability": 0.69, "drift": 0.18}
}

GET /domain-scores

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/domain-scores?city_code=VLC&at=2026-03-10T09:00:00Z"

{
  "data": {"domains": [{"domain_code": "mobility", "score": 0.71, "trend": "up"}]}
}

GET /city-profile

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/city-profile?city_code=VLC"

{
  "data": {
    "city_code": "VLC",
    "display_name": "Valencia",
    "timezone": "Europe/Madrid",
    "centroid": {"lat": 39.4699, "lon": -0.3763}
  }
}

GET /evolution

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/evolution?city_code=VLC&start_date=2026-03-09T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{
  "data": {"series": [{"resolved_at": "2026-03-09T12:00:00+01:00", "health_score": 71.1}]}
}

GET /benchmark

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/benchmark?city_code=VLC"

{
  "data": {"cities": [{"city_code": "VLC", "score": 74.6, "rank": 1}], "count": 1}
}

GET /data-quality

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/global-metrics/data-quality?city_code=VLC&at=2026-03-10T09:00:00Z"

{
  "data": {"coverage": 0.91, "freshness": 0.88, "noise": 0.14, "confidence": 0.86}
}

Per-endpoint examples

GET /active

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/active?city_code=VLC&at=2026-03-10T09:00:00Z"

{
  "data": {"alerts": [{"alert_id": "al_102", "theme": "mobility", "severity": "high", "zone_id": "z_centro"}]}
}

GET /history

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/history?city_code=VLC&start_date=2026-03-03T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{
  "data": {"items": [{"alert_id": "al_081", "status": "resolved"}], "count": 1}
}

GET /by-zone/{zone_id}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/by-zone/z_centro?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"zone_id": "z_centro", "alerts": [{"theme": "noise", "severity": "medium"}]}}

GET /by-theme/{theme}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/by-theme/mobility?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"theme": "mobility", "alerts": [{"zone_id": "z_centro", "severity": "high"}]}}

GET /summary

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/summary?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"severity_counts": {"high": 1}, "top_theme": "mobility", "hottest_zone": "z_centro"}}

GET /trends

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/alerts/trends?city_code=VLC&start_date=2026-03-09T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data": {"trend": "up", "delta_24h": 0.18, "dominant_theme": "mobility"}}

Per-endpoint examples

GET /short-term

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/short-term?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"health_future": 0.74, "stress_future": 0.33, "confidence": 0.81}}

GET /domain-outlook

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/domain-outlook?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"domains": [{"domain_code": "mobility", "direction": "up", "confidence": 0.78}]}}

GET /risk-factors

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/risk-factors?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"factors": [{"factor": "mobility_pressure", "probability": 0.67}]}}

GET /scenarios

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/scenarios?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data": {"scenarios": [{"label": "base", "probability": 0.56}]}}

GET /accuracy

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/accuracy?city_code=VLC&start_date=2026-02-01T00:00:00Z&end_date=2026-03-01T00:00:00Z"

{"data": {"mae": 0.083, "hit_rate": 0.79, "window_days": 28}}

GET /what-if/{domain}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/predictions/what-if/mobility?city_code=VLC&at=2026-03-10T09:00:00Z&magnitude=0.10"

{"data": {"domain": "mobility", "delta_score": 0.06, "secondary_effects": [{"domain_code": "noise", "delta": 0.03}]}}

This block exposes product-prepared counterfactual simulation. It accepts tactical spatial interventions and also direct interventions with a percentage impact on an urban domain,

Docs prefix: dev/spatial/interventions/* · Canonical route: /dev/spatial/interventions/* · Legacy compatibility: /api/v1/dev/spatial/interventions/*

The canonical OpenAPI contract is published under /api/v1/dev/spatial/interventions/*. The /dev/* aliases remain active, but are excluded from the main schema.

Per-endpoint examples

GET /mood

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/mood?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"stress":0.42,"calm":0.38,"anxiety":0.29,"irritability":0.21}}

GET /mood/timeline

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/mood/timeline?city_code=VLC&start_date=2026-03-09T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"series":[{"resolved_at":"2026-03-09T12:00:00+01:00","stress":0.39}]}}

GET /wellbeing-index

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/wellbeing-index?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"wellbeing_index":68.4,"confidence":0.8}}

GET /stress-map

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/stress-map?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","stress":0.61,"intensity":"high"}]}}

GET /cognitive-patterns

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/cognitive-patterns?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"patterns":[{"pattern":"crowded_reactivity","weight":0.57}]}}

GET /resilience

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/resilience?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"resilience_score":0.66,"direction":"stable"}}

GET /narratives

curl -H "Authorization: Bearer $TOKEN"   "https://api.urbeia.com/dev/packages/psycho-urban/narratives?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"headline":"The city operates with moderate stress and stable recovery."}}

Per-endpoint examples

GET /hotspots

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/hotspots?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"hotspots":[{"zone_id":"z_centro","intensity":0.73,"theme":"mobility"}]}}

GET /zone/{zone_id}/profile

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/zone/z_centro/profile?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zone_id":"z_centro","domains":{"mobility":0.71},"top_alert":"noise"}}

GET /layers/{theme}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/layers/mobility?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"theme":"mobility","cells":[{"lat":39.47,"lon":-0.376,"value":0.64}]}}

GET /corridors

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/corridors?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"corridors":[{"corridor_id":"cor_1","pressure":0.69}]}}

GET /compare-zones

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/compare-zones?city_code=VLC&zone_id=z_centro&zone_id=z_rivera&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","score":0.72},{"zone_id":"z_rivera","score":0.58}]}}

GET /events-feed

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/events-feed?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"events":[{"event_id":"evt_12","kind":"pressure_spike","zone_id":"z_centro"}]}}

GET /temporal-map

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/temporal-map?city_code=VLC&at=2026-03-09T20:00:00Z"

{"data":{"resolved_at":"2026-03-09T21:00:00+01:00","hotspots":[{"zone_id":"z_centro","intensity":0.61}]}}

GET /correlations

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/correlations?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"pairs":[{"zone_a":"z_centro","zone_b":"z_rivera","correlation":0.48}]}}

GET /anomaly-zones

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/spatial-crossover/anomaly-zones?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","anomaly_score":0.67}]}}

Per-endpoint examples

GET /mobility/pressure

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/mobility/pressure?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","pressure":0.74}]}}

GET /mobility/corridors

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/mobility/corridors?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"corridors":[{"corridor_id":"cor_1","load":0.71,"speed":0.46}]}}

GET /mobility/forecast

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/mobility/forecast?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"corridors":[{"corridor_id":"cor_1","pressure_future":0.78}]}}

GET /density/current

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/density/current?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","density":0.69}]}}

GET /density/patterns

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/density/patterns?city_code=VLC&start_date=2026-03-09T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"patterns":[{"hour":9,"density":0.63}]}}

GET /bottlenecks

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/bottlenecks?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"bottlenecks":[{"zone_id":"z_centro","severity":"high"}]}}

GET /efficiency-score

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/logistics/efficiency-score?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"efficiency_score":64.2,"trend":"down"}}

Per-endpoint examples

GET /impact-matrix

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/impact-matrix?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"matrix":[{"src":"mobility","dst":"noise","weight":0.42}]}}

GET /leverage-points

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/leverage-points?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"points":[{"domain":"mobility","leverage":0.71}]}}

GET /resource-allocation

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/resource-allocation?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"allocations":[{"domain":"mobility","priority":1}]}}

GET /synergies

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/synergies?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"synergies":[{"a":"mobility","b":"safety","score":0.36}]}}

GET /inefficiencies

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/inefficiencies?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"inefficiencies":[{"domain":"noise","loss":0.29}]}}

GET /intervention-simulator

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/optimization/intervention-simulator?city_code=VLC&at=2026-03-10T09:00:00Z&domain=mobility&magnitude=0.10"

{"data":{"delta_score":0.05,"top_secondary":"noise"}}

Per-endpoint examples

GET /energy/state

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/energy/state?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"demand":0.58,"efficiency":0.67,"peak":false}}

GET /climate/indicators

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/climate/indicators?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"heat_stress":0.34,"air_quality":0.72}}

GET /emissions/proxy

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/emissions/proxy?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"emissions_proxy":0.41,"trend":"down"}}

GET /green-score

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/green-score?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"green_score":63.5}}

GET /waste/efficiency

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/waste/efficiency?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"efficiency":0.69,"collection_quality":0.74}}

GET /water/flow

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/water/flow?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"flow_state":"stable","anomalies":0}}

GET /sustainability/trends

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/sustainability/sustainability/trends?city_code=VLC&start_date=2026-03-01T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"trend":"up","delta":0.07}}

Per-endpoint examples

GET /pressure

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/pressure?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"pressure":0.52,"top_zone":"z_oldtown"}}

GET /hotspots

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/hotspots?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"hotspots":[{"zone_id":"z_oldtown","intensity":0.77}]}}

GET /impact-on-city

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/impact-on-city?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"domains":[{"domain_code":"noise","impact":0.34}]}}

GET /seasonal-pattern

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/seasonal-pattern?city_code=VLC&start_date=2026-03-01T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"seasonal_pattern":"shoulder","deviation":0.08}}

GET /overtourism-risk

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/overtourism-risk?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"risk":0.43,"zone_id":"z_oldtown"}}

GET /recommendations

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/tourism/recommendations?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_rivera","relief_potential":0.58}]}}

Per-endpoint examples

GET /risk-zones

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/risk-zones?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","severity":"high"}]}}

GET /incidents/recent

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/incidents/recent?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"incidents":[{"incident_id":"inc_22","zone_id":"z_centro","severity":"medium"}]}}

GET /night-safety-index

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/night-safety-index?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","score":0.62}]}}

GET /infrastructure/stress

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/infrastructure/stress?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"points":[{"asset":"bridge_1","stress":0.57}]}}

GET /emergency/readiness

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/emergency/readiness?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"zones":[{"zone_id":"z_centro","readiness":0.7}]}}

GET /vulnerability-map

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/safety/vulnerability-map?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"cells":[{"lat":39.47,"lon":-0.376,"vulnerability":0.49}]}}

Per-endpoint examples

GET /pulse

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/real-time/pulse?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"headline":"Mobility is tense in the center","health_score":74.6}}

GET /feed

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/real-time/feed?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"items":[{"kind":"alert","resolved_at":"2026-03-10T09:55:00+01:00"}]}}

GET /changes

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/real-time/changes?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"deltas":[{"domain":"mobility","delta":0.04}]}}

GET /trending

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/real-time/trending?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"themes":[{"theme":"mobility","weight":0.61}]}}

GET /anomalies

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/real-time/anomalies?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"anomalies":[{"kind":"pressure_spike","zone_id":"z_centro"}]}}

SSE /stream

curl -N "https://api.urbeia.com/dev/packages/real-time/stream?city_code=VLC"

event: pulse
data: {"headline":"Mobility is tense in the center"}

Per-endpoint examples

GET /now

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/now?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"headline":"Valencia runs with moderate mobility pressure."}}

GET /today

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/today?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"summary":"The day consolidates moderate stress and better energy performance."}}

GET /why/{indicator}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/why/health-score?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"indicator":"health-score","why":"Improvement comes from higher coherence and lower noise."}}

GET /compare/yesterday

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/compare/yesterday?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"comparison":"Today improves versus yesterday in health and noise."}}

GET /insights

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/insights?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"insights":["Pressure concentrates in center and riverfront."]}}

GET /report/weekly

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/narrative/report/weekly?city_code=VLC&end_date=2026-03-10T00:00:00Z"

{"data":{"title":"Weekly summary","highlights":["Noise down","Resilience up"]}}

Per-endpoint examples

GET /overview

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/overview?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"global_state":"stable","score":0.78,"risk_preventive":0.21}}

GET /history

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/history?city_code=VLC&start_date=2026-03-01T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"series":[{"resolved_at":"2026-03-09T12:00:00+01:00","score":0.76}]}}

GET /audit-trail

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/audit-trail?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"rules":[{"rule_id":"r_12","triggered":true}]}}

GET /export

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/export?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"overview":{},"history":{},"audit":{}}}

GET /cce/latest

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/cce/latest?city_code=VLC&at=2026-03-10T09:00:00Z"

{"data":{"global_inconsistency":0.18,"resolved_at":"2026-03-10T10:00:00+01:00"}}

GET /cce/history

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/cognition/metacognition/cce/history?city_code=VLC&start_date=2026-03-01T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data":{"series":[{"resolved_at":"2026-03-09T12:00:00+01:00","global_inconsistency":0.2}]}}

Endpoint examples

GET /state/overview

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/state/overview?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"status":"READY","overview":{"health_score":0.73,"pressure_index":0.41}}}

GET /spatial/hotspots

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/spatial/hotspots?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"hotspots":[{"track_id":"trk_31a92","centroid":{"lat":39.4702,"lon":-0.3768},"radius_m":180.0,"intensity":0.78}],"count":1}}

GET /spatial/hotspots/day

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/spatial/hotspots/day?city_code=VLC&start_date=2026-03-10T00:00:00+01:00&end_date=2026-03-10T23:59:59+01:00"

{"data":{"daily_hotspots":[{"track_id":"trk_31a92","appearances":14,"mean_intensity":0.74}]}}

GET /forecast/short-term

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/forecast/short-term?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"domains":{"mobility":{"delta":-0.08,"confidence":0.72}},"hotspots":[{"track_id":"trk_31a92","survival_prob":0.81}]}}

GET /forecast/detail

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/forecast/detail?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"confidence":0.71,"expected_hotspots_v1":{"status":"ok","hotspots":[{"track_id":"trk_31a92","survival_prob":0.81}]}}}

GET /state/timeline

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/state/timeline?city_code=VLC"

{"data":{"timeline":[{"resolved_at":"2026-03-10T08:00:00+01:00","health_score":0.69}]}}

GET /alerts/current

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/alerts/current?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"alerts":[{"alert_id":"alt_2041","theme":"mobility","severity":"medium"}],"count":1}}

GET /psycho/context

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/psycho/context?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"stress_index":0.44,"calm_index":0.36,"drivers":["crowding","noise","thermal_discomfort"]}}

POST /events/audit

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"city_code":"VLC","fingerprints":["evt:fallas:mascleta"]}' \
  "https://api.urbeia.com/api/v1/dev/events/audit"

{"data":{"events":[{"fingerprint":"evt:fallas:mascleta","status":"known","domain_impact":["activity","mobility","noise"]}]}}

POST /events/window-snapshot

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"city_code":"VLC","start_date":"2026-03-10T08:00:00+01:00","end_date":"2026-03-10T12:00:00+01:00"}' \
  "https://api.urbeia.com/api/v1/dev/events/window-snapshot"

{"data":{"events":[{"fingerprint":"evt:fallas:mascleta","severity":"high"}]}}

GET /cognition/sensory-legend

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/sensory-legend?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"legend":[{"code":"high_pressure","label":"High pressure"},{"code":"relief_zone","label":"Relief zone"}]}}

GET /cognition/metacognition/*

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/metacognition/overview?city_code=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"coherence_score":0.73,"uncertainty_index":0.28,"active_watchers":["forecast","dsi","uoe"]}}

Endpoint examples

GET /domain-canonical

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/domain-canonical?city_code=VLC&domain=mobility&at=2026-03-10T10:00:00+01:00&limit=100"

{"data":{"domain":"mobility","status":"READY","variables":[{"var_key":"mobility.flow_ratio","category":"STRUCTURAL","ontology_score":0.71}],"count":1}}

GET /relations/latest

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/relations/latest?city_code=VLC&at=2026-03-10T10:00:00+01:00&min_confidence=0.6&limit=50"

{"data":{"relations":[{"relation_id":"mobility→noise:mobility.flow_ratio→noise.complaints","structural_confidence":0.77,"support_n":128}],"count":1}}

GET /relations/explain

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/relations/explain?city_code=VLC&relation_id=mobility%E2%86%92noise%3Amobility.flow_ratio%E2%86%92noise.complaints&at=2026-03-10T10:00:00+01:00"

{"data":{"metrics":{"rho_spearman":0.64},"alignment":{"forecast_alignment":0.58},"confidence_block":{"structural_confidence":0.77}}}

GET /variables/explain

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/variables/explain?city_code=VLC&domain=mobility&var_key=mobility.flow_ratio&at=2026-03-10T10:00:00+01:00"

{"data":{"var_key":"mobility.flow_ratio","category":"CORE","promotion_reason":"Stable support and high centrality."}}

GET /domain/schema

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/domain/schema?city_code=VLC&domain=mobility&at=2026-03-10T10:00:00+01:00&min_category=STRUCTURAL"

{"data":{"domain":"mobility","variables":[{"var_key":"mobility.flow_ratio","category":"CORE"}],"relations":[{"relation_id":"mobility→noise:mobility.flow_ratio→noise.complaints","structural_confidence":0.77}]}}

GET /domain/timeseries

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v1/dev/cognition/dsi/domain/timeseries?city_code=VLC&domain=mobility&start_date=2026-03-01T00:00:00+01:00&end_date=2026-03-10T23:59:59+01:00&var_key=mobility.flow_ratio"

{"data":{"series":[{"var_key":"mobility.flow_ratio","points":[{"resolved_at":"2026-03-01T00:00:00+01:00","value":0.58}]}]}}

Endpoint example

GET /domains/{domain_src}/cross/{domain_dst}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v2/domains/mobility/cross/noise?city=VLC&at=2026-03-10T10:00:00+01:00&min_confidence=0.6&polarity=ALL&top_k=20"

{"data":{"domain_src":"mobility","domain_dst":"noise","relations":[{"relation_id":"mobility→noise:mobility.flow_ratio→noise.complaints","direction":"POSITIVE","confidence":{"structural_confidence":0.77}}],"count":1}}

Endpoint examples

GET /domains/{domain}/ontology

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v2/domains/mobility/ontology?city=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"status":"READY","domain":"mobility","maturity_score":0.71,"variables":[{"var_key":"mobility.flow_ratio","ontology_score":0.79,"category":"CORE"}],"count":1}}

GET /meta-domains

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v2/meta-domains?city=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"status":"READY","meta_domains":[{"meta_name":"mobility_climate_stress","status":"STABLE","maturity_meta":0.58}],"count":1}}

GET /meta-domains/{meta_name}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v2/meta-domains/mobility_climate_stress?city=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"meta_name":"mobility_climate_stress","composition":[{"var_key":"mobility.flow_ratio","domain_origin":"mobility","weight_in_cluster":0.41}],"count":1}}

GET /forecast/explain

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/v2/forecast/explain?city=VLC&at=2026-03-10T10:00:00+01:00"

{"data":{"status":"READY","phi_guard":{"phi_state":"CONSOLIDATE","applied":true},"ontology_reweight":[{"domain":"mobility","multiplier":1.142}],"meta_reweight":[{"meta_name":"mobility_climate_stress","multiplier":1.087}]}}

Per-endpoint examples

GET /schema

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/domain-data/schema?city_code=VLC&domain=mobility"

{"data": {"domain": "mobility", "variables": [{"var_key": "mobility.flow_pressure", "category": "CORE"}]}}

GET /timeseries

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/domain-data/timeseries?city_code=VLC&domain=mobility&var_key=mobility.flow_pressure&start_date=2026-03-01T00:00:00Z&end_date=2026-03-10T00:00:00Z"

{"data": {"series": [{"resolved_at": "2026-03-09T12:00:00+01:00", "value": 0.63}]}}

GET /domains/catalog

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/domain-data/domains/catalog?city_code=VLC"

{"data": {"domains": [{"domain_code": "mobility", "display_name": "Mobility", "is_active": true}]}}

GET /magnetos/catalog

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/domain-data/magnetos/catalog?city_code=VLC&domain_code=mobility"

{"data": {"magnetos": [{"magneto_code": "mobility.flow_pressure", "kind": "state", "polarity": 1}]}}

GET /magnetos/relevance

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/dev/packages/domain-data/magnetos/relevance?city_code=VLC&at=2026-03-10T09:00:00Z&domain_code=mobility"

{"data": {"available_magnetos": [{"magneto_code": "mobility.flow_pressure"}], "recommended_magnetos": [{"magneto_code": "mobility.flow_pressure", "reason_code": "FORECAST_RELEVANT_NOW"}]}}

Per-endpoint examples

The COEL layer adds presentation and BI semantics over DSI: a technical key such as mobility.raw_pack_mncwtl_when__bus_boardings can be consumed as mobility.bus_boardings without losing traceability. Bu consumes the kernel contract from Bk and exposes this certified external shape.

GET /domains

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/core-struct/domains?city_code=SYNTH"

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.domains",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "filters": {"only_with_core": true}
  },
  "kernel_governance": {
    "candidate_policy": "CORE_STRUCTURAL_ONLY",
    "direct_actuation": "FORBIDDEN",
    "unit_policy": "EXTERNAL_DECLARATION_REQUIRED_FOR_PHYSICAL_VALUES",
    "audit_policy": "AUDIT_REF_REQUIRED",
    "non_weakening_required": true
  },
  "items": [
    {"domain": "mobility", "core_variables_n": 55, "peripheral_variables_n": 21}
  ],
  "pagination": {"limit": null, "next_cursor": null},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domains": [{"domain": "mobility", "core_variables_n": 55, "peripheral_variables_n": 21}]
  }
}

GET /domains/{domain}/variables

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/core-struct/domains/climate/variables?city_code=SYNTH&include_support=true"

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.domain_variables",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "domain": "climate",
    "filters": {"family": null, "include_peripheral": false, "include_support": true}
  },
  "items": [{
    "var_key": "climate.raw_lista_datos__tempact",
    "display_code": "climate.tempact",
    "display_label": "Tempact",
    "family": "climate",
    "magneto_code": "climate",
    "presentation_source": "coel_pair"
  }],
  "pagination": {"limit": 100, "next_cursor": null, "offset": 0},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "climate",
    "variables": {
      "core": [{
        "var_key": "climate.raw_lista_datos__tempact",
        "display_code": "climate.tempact",
        "display_label": "Tempact",
        "family": "climate",
        "magneto_code": "climate",
        "presentation_source": "coel_pair"
      }],
      "peripheral": [],
      "support": []
    },
    "paging": {"limit": 100, "offset": 0, "returned": 1}
  }
}

GET /variables/{var_key}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.urbeia.com/api/core-struct/variables/climate.raw_cuerpo_data__pm10?city_code=SYNTH"

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.variable",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {"city_code": "SYNTH", "var_key": "climate.raw_cuerpo_data__pm10"},
  "items": [{
    "var_key": "climate.raw_cuerpo_data__pm10",
    "canonical_role": "semantic_core",
    "magneto_code": "climate",
    "magneto_display_name": "Urban climate",
    "magnetic_family_code": "climate"
  }],
  "pagination": {"limit": 1, "next_cursor": null},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "variable": {
      "var_key": "climate.raw_cuerpo_data__pm10",
      "canonical_role": "semantic_core",
      "magneto_code": "climate",
      "magneto_display_name": "Urban climate",
      "magnetic_family_code": "climate"
    }
  }
}

POST /query/events

curl -X POST "https://api.urbeia.com/api/core-struct/query/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"SYNTH","domain":"climate","time":{"field":"ts_urb","from":"260","to":"280"},"filters":[{"var_key":"climate.raw_cuerpo_data__pm10","op":"gt","value":20}]}'

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.query.events",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "from_ts_urb": "260",
    "to_ts_urb": "280",
    "domain": "climate",
    "filters": [{"var_key": "climate.raw_cuerpo_data__pm10", "op": "gt", "value": 20}]
  },
  "items": [{
    "event_key": {"ts_urb": "270.209072007000"},
    "values": {"climate.raw_cuerpo_data__pm10": 23.4}
  }],
  "pagination": {"limit": 100, "next_cursor": null},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "climate",
    "count": 2,
    "matches": [{"event_key": {"ts_urb": "270.209072007000"}, "values": {"climate.raw_cuerpo_data__pm10": 23.4}}]
  }
}

POST /query/pairs

curl -X POST "https://api.urbeia.com/api/core-struct/query/pairs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"SYNTH","domain":"mobility","pair_var_codes":["mobility.bus_boardings"],"time":{"from":0,"to":500}}'

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.query.pairs",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "from_ts_urb": 0,
    "to_ts_urb": 500,
    "domain": "mobility",
    "filters": {"variables": ["mobility.bus_boardings"]}
  },
  "items": [{
    "event_key": {"ts_urb": "100.0", "event_fingerprint": "ffffffffffffffffffffffffffffffffffffffff"},
    "variable": {
      "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
      "display_code": "mobility.bus_boardings",
      "display_label": "Bus boardings",
      "canonical_observable_code": "mobility.bus_boardings",
      "domain": "mobility",
      "family": "mobility.public_transport",
      "magneto_code": "mobility.public_transport",
      "semantic_type": "intensity",
      "uoe_category": "STRUCTURAL"
    },
    "value": {"kind": "raw_numeric_declared", "numeric": 42.0, "text": null, "json": null, "unit": null},
    "operational_eligibility": "ELEVATABLE",
    "eligibility_reason": "gate_precheck_ok_family_contract",
    "trust_final": 0.9,
    "phi_mode": "OK"
  }],
  "pagination": {"limit": 100, "next_cursor": null, "offset": 0},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "mobility",
    "count": 1,
    "matches": [{
      "event_key": {"ts_urb": "100.0", "event_fingerprint": "ffffffffffffffffffffffffffffffffffffffff"},
      "variable": {
        "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
        "display_code": "mobility.bus_boardings",
        "display_label": "Bus boardings",
        "canonical_observable_code": "mobility.bus_boardings",
        "domain": "mobility",
        "family": "mobility.public_transport",
        "magneto_code": "mobility.public_transport",
        "semantic_type": "intensity",
        "uoe_category": "STRUCTURAL"
      },
      "value": {"kind": "raw_numeric_declared", "numeric": 42.0, "text": null, "json": null, "unit": null},
      "operational_eligibility": "ELEVATABLE",
      "eligibility_reason": "gate_precheck_ok_family_contract",
      "trust_final": 0.9,
      "phi_mode": "OK"
    }],
    "paging": {"limit": 100, "offset": 0, "returned": 1}
  }
}

POST /query/observables

curl -X POST "https://api.urbeia.com/api/core-struct/query/observables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"SYNTH","domain":"mobility","canonical_observable_codes":["mobility.bus_boardings"],"time":{"from":0,"to":500}}'

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.query.observables",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "from_ts_urb": 0,
    "to_ts_urb": 500,
    "domain": "mobility",
    "filters": {"variables": ["mobility.bus_boardings"]}
  },
  "items": [{
    "event_key": {"ts_urb": "100.0", "event_fingerprint": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"},
    "observable": {
      "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
      "display_code": "mobility.bus_boardings",
      "display_label": "Bus boardings",
      "domain": "mobility",
      "family": "mobility.public_transport",
      "magneto_code": "mobility.public_transport",
      "semantic_type": "intensity",
      "uoe_category": "STRUCTURAL",
      "operational_status": "OPERATIONAL"
    },
    "value": {"kind": "raw_numeric_declared", "numeric": 24.0, "text": null, "json": null, "unit": null},
    "trust_final": 0.92,
    "phi_mode": "OK"
  }],
  "pagination": {"limit": 100, "next_cursor": null, "offset": 0},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "mobility",
    "count": 1,
    "matches": [{
      "event_key": {"ts_urb": "100.0", "event_fingerprint": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"},
      "observable": {
        "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
        "display_code": "mobility.bus_boardings",
        "display_label": "Bus boardings",
        "domain": "mobility",
        "family": "mobility.public_transport",
        "magneto_code": "mobility.public_transport",
        "semantic_type": "intensity",
        "uoe_category": "STRUCTURAL",
        "operational_status": "OPERATIONAL"
      },
      "value": {"kind": "raw_numeric_declared", "numeric": 24.0, "text": null, "json": null, "unit": null},
      "trust_final": 0.92,
      "phi_mode": "OK"
    }],
    "paging": {"limit": 100, "offset": 0, "returned": 1}
  }
}

POST /query/pairs/series

curl -X POST "https://api.urbeia.com/api/core-struct/query/pairs/series" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"SYNTH","domain":"mobility","variables":["mobility.bus_boardings"],"time":{"field":"ts_physical","from":"2026-04-25T00:00:00Z","to":"2026-04-25T23:59:59Z"},"sampling":"raw"}'

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.query.pairs.series",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "from_ts_urb": "2026-04-25T00:00:00Z",
    "to_ts_urb": "2026-04-25T23:59:59Z",
    "domain": "mobility",
    "filters": {"variables": ["mobility.bus_boardings"], "sampling": "raw"}
  },
  "items": [{
    "display_code": "mobility.bus_boardings",
    "display_label": "Bus boardings",
    "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
    "canonical_observable_code": "mobility.bus_boardings",
    "domain": "mobility",
    "family": "mobility.public_transport",
    "magneto_code": "mobility.public_transport",
    "semantic_type": "intensity",
    "operational_eligibility": "ELEVATABLE",
    "uoe_category": "STRUCTURAL",
    "points": [{
      "ts_urb": "100.0",
      "ts_physical": "2026-04-25T10:00:00+00:00",
      "value": 42.0,
      "trust_final": 0.9,
      "phi_mode": "OK",
      "event_fingerprint": "ffffffffffffffffffffffffffffffffffffffff",
      "operational_eligibility": "ELEVATABLE"
    }]
  }],
  "pagination": {"limit": 1, "next_cursor": null},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "mobility",
    "series": [{
      "display_code": "mobility.bus_boardings",
      "display_label": "Bus boardings",
      "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
      "canonical_observable_code": "mobility.bus_boardings",
      "domain": "mobility",
      "family": "mobility.public_transport",
      "magneto_code": "mobility.public_transport",
      "semantic_type": "intensity",
      "operational_eligibility": "ELEVATABLE",
      "uoe_category": "STRUCTURAL",
      "points": [{
        "ts_urb": "100.0",
        "ts_physical": "2026-04-25T10:00:00+00:00",
        "value": 42.0,
        "trust_final": 0.9,
        "phi_mode": "OK",
        "event_fingerprint": "ffffffffffffffffffffffffffffffffffffffff",
        "operational_eligibility": "ELEVATABLE"
      }]
    }]
  }
}

POST /query/observables/aggregate

curl -X POST "https://api.urbeia.com/api/core-struct/query/observables/aggregate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"SYNTH","domain":"mobility","variables":["mobility.bus_boardings"],"time":{"from":0,"to":500},"aggregate":["count","avg","max"]}'

{
  "api_contract": {
    "name": "Bk.restapi_core_access.core_struct.query.observables.aggregate",
    "version": "v0.1",
    "stability": "draft",
    "owner_node": "Bk",
    "owner_entity": "Urbeika",
    "non_weakening_required": true
  },
  "request_context": {
    "city_code": "SYNTH",
    "from_ts_urb": 0,
    "to_ts_urb": 500,
    "domain": "mobility",
    "filters": {"variables": ["mobility.bus_boardings"], "aggregate": ["count", "avg", "max"]}
  },
  "items": [{
    "display_code": "mobility.bus_boardings",
    "display_label": "Bus boardings",
    "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
    "canonical_observable_code": "mobility.bus_boardings",
    "domain": "mobility",
    "family": "mobility.public_transport",
    "magneto_code": "mobility.public_transport",
    "semantic_type": "intensity",
    "uoe_category": "STRUCTURAL",
    "operational_status": "OPERATIONAL",
    "sample_size": 1,
    "aggregates": {"count": 1, "avg": 24.0, "max": 24.0}
  }],
  "pagination": {"limit": 1, "next_cursor": null},
  "audit": {"response_trace_id": null},
  "data": {
    "city_code": "SYNTH",
    "domain": "mobility",
    "aggregates": [{
      "display_code": "mobility.bus_boardings",
      "display_label": "Bus boardings",
      "var_key": "mobility.raw_pack_mncwtl_when__bus_boardings",
      "canonical_observable_code": "mobility.bus_boardings",
      "domain": "mobility",
      "family": "mobility.public_transport",
      "magneto_code": "mobility.public_transport",
      "semantic_type": "intensity",
      "uoe_category": "STRUCTURAL",
      "operational_status": "OPERATIONAL",
      "sample_size": 1,
      "aggregates": {"count": 1, "avg": 24.0, "max": 24.0}
    }]
  }
}

POST /query/pairs/top and POST /query/pairs/breakdown

top accepts metrics such as avg, max, p90 or volatility. breakdown groups by domain, family, magneto_code, semantic_type, uoe_category and operational_eligibility.

Per-endpoint examples

GET /cities

This endpoint returns only OFFICIAL cities and explicitly marks whether each one is certified, occupied, and selectable for a new UIL registration flow.

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/cities"

{
  "data": {
    "cities": [
      {
        "city_code": "VLC",
        "city_name": "Valencia",
        "city_type": "OFFICIAL",
        "status": "OCCUPIED",
        "is_certified": true,
        "is_available": false,
        "is_selectable_for_uil_registration": false,
        "certification": {
          "has_certified_lab": true,
          "certified_lab_city_code": "VLC_LAB_12345"
        },
        "availability": {
          "reason_code": "OFFICIAL_CITY_OCCUPIED"
        },
        "timezone": "Europe/Madrid",
        "packages": ["global-metrics", "alerts", "integration"]
      },
      {
        "city_code": "MAD",
        "city_name": "Madrid",
        "city_type": "OFFICIAL",
        "status": "AVAILABLE",
        "is_certified": false,
        "is_available": true,
        "is_selectable_for_uil_registration": true,
        "certification": {
          "has_certified_lab": false,
          "certified_lab_city_code": null
        },
        "availability": {
          "reason_code": null
        },
        "timezone": "Europe/Madrid",
        "packages": ["global-metrics", "alerts", "integration"]
      }
    ],
    "count": 2
  }
}

GET /packages

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/packages"

{"data": {"packages": [{"package": "global-metrics", "enabled": true}]}}

GET /schema/{package}

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/schema/global-metrics"

{"data": {"package": "global-metrics", "json_schema": {"type": "object"}}}

GET /status

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/status"

{"data": {"status": "ok", "packages": [{"package": "simulations", "latency_ms": 182}]}}

GET /usage

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/usage"

{"data": {"requests_today": 142, "daily_quota": 5000, "rate_per_minute": 3.2}}

POST /webhook/register

curl -X POST https://api.urbeia.com/dev/packages/integration/webhook/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://example.com/hooks/urbeia","events":["alerts","changes"]}'

{"data": {"webhook_id": "wh_01JQ", "status": "registered", "events": ["alerts", "changes"]}}

GET /changelog

curl -H "Authorization: Bearer $TOKEN" "https://api.urbeia.com/dev/packages/integration/changelog"

{"data": {"items": [{"version": "2026.03.10", "summary": "Temporal humanized contracts for developer pack"}]}}

Institutional integration uses HMAC and a dedicated scope.

Technical quickstart (2 values)

UrbeIA provides URBEIA_KEY_ID and URBEIA_SECRET. The remaining headers are generated client-side on every request.

export URBEIA_KEY_ID="YOUR_KEY_ID"
export URBEIA_SECRET="YOUR_SECRET"

BODY='{
  "metadata": {"city":"VLC"},
  "station_id":"S-104",
  "entries":281,
  "exits":244,
  "geo":{"lat":39.4699,"lon":-0.3763}
}'

TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
NONCE=$(cat /proc/sys/kernel/random/uuid)
BODY_SHA=$(printf '%s' "$BODY" | sha256sum | awk '{print $1}')
CANONICAL=$(printf "POST\n/uil/signals\n%s\n%s\n%s" "$BODY_SHA" "$TS" "$NONCE")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$URBEIA_SECRET" -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
IDEMP="uil-$NONCE"

curl -X POST https://api.urbeia.com/uil/signals \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $URBEIA_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIG" \
  -H "Idempotency-Key: $IDEMP" \
  -d "$BODY"

Current contract for POST /uil/signals

The endpoint now accepts three input shapes:

metadata and city binding rule

• If the payload already contains metadata, UrbeIA preserves it and forcibly injects metadata.city and metadata.city_code from the UIL key scope.
• If the payload does not contain metadata, UrbeIA creates metadata and stores the original body under dataset.
• If one UIL key spans multiple cities and the payload does not declare a city, the request is rejected with 422 due to ambiguity.

Example 1. Raw JSON with metadata

curl -X POST https://api.urbeia.com/uil/signals \
  -H \"Content-Type: application/json\" \
  -H \"X-Key-Id: YOUR_KEY_ID\" \
  -H \"X-Timestamp: 2026-03-07T12:00:00Z\" \
  -H \"X-Nonce: 7f1d3c4e-...\" \
  -H \"X-Signature: ...\" \
  -H \"Idempotency-Key: raw-meta-001\" \
  -d '{\n+    \"metadata\": {\n+      \"source\": \"valencia.mobility.hooks\",\n+      \"schema\": \"mobility.turnstiles.v1\",\n+      \"ts\": \"2024-06-07T23:35:00.308791+00:00\"\n+    },\n+    \"station_id\": \"S-104\",\n+    \"entries\": 281,\n+    \"exits\": 244,\n+    \"geo\": {\"lat\": 39.4699, \"lon\": -0.3763}\n+  }'

Example 2. Raw JSON without metadata

curl -X POST https://api.urbeia.com/uil/signals \
  -H \"Content-Type: application/json\" \
  -H \"X-Key-Id: YOUR_KEY_ID\" \
  -H \"X-Timestamp: 2026-03-07T12:00:00Z\" \
  -H \"X-Nonce: 7f1d3c4e-...\" \
  -H \"X-Signature: ...\" \
  -H \"Idempotency-Key: raw-bare-001\" \
  -d '{\n+    \"sensor\": \"AQ-17\",\n+    \"pm25_ugm3\": 12.4,\n+    \"pm10_ugm3\": 21.8,\n+    \"captured_at\": \"2024-06-07T23:35:00.308791+00:00\"\n+  }'

Example 3. Normalized UIL batch

curl -X POST https://api.urbeia.com/uil/signals \
  -H \"Content-Type: application/json\" \
  -H \"X-Key-Id: YOUR_KEY_ID\" \
  -H \"X-Timestamp: 2026-03-07T12:00:00Z\" \
  -H \"X-Nonce: 7f1d3c4e-...\" \
  -H \"X-Signature: ...\" \
  -H \"Idempotency-Key: norm-001\" \
  -d '{\n+    \"city_code\": \"VLC\",\n+    \"resolved_at\": \"9140.793538172\",\n+    \"ts_physical\": \"2024-06-07T23:35:00.308791+00:00\",\n+    \"signals\": [\n+      {\n+        \"signal_key\": \"mobility.pressure\",\n+        \"normalized_value\": 0.72,\n+        \"confidence_score\": 0.93,\n+        \"projection_vector\": {\"mobility\": 0.91, \"logistics\": 0.44}\n+      }\n+    ]\n+  }'

The response now also reports whether the request was staged and which ingest mode was used:

{\n+  \"status\": \"ingested\",\n+  \"request_id\": \"...\",\n+  \"city_code\": \"VLC\",\n+  \"resolved_at\": \"9140.793538172\",\n+  \"inserted\": 1,\n+  \"staged\": true,\n+  \"ingest_mode\": \"normalized_batch\",\n+  \"idempotency\": \"new\"\n+}

What this program actually does

UrbeIA lets developers build products on top of urban cognition. This program adds a second lane: if you send back high-quality pulses or datasets from your own domain, and that signal passes contract, rights, privacy, anti-gaming, stability, and integration gates, it may generate platform credits.

Technical state and economic state are intentionally separate. A contribution can be accepted and still not be credited. Credits live in an auditable ledger and can be reversed if a later review finds fraud, invalidity, or loss of eligibility.

Per-endpoint examples

POST /contributions

curl -X POST https://api.urbeia.com/api/v1/dev/contributions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "schema_version": "dcp.v0.2",
      "city_code": "VLC",
      "contribution_type": "operational_pulse",
      "source_timestamp": "2026-03-14T10:30:00Z"
    },
    "source": {
      "deployment_env": "production",
      "estimated_reliability": 0.91,
      "privacy_mode": "pseudonymized"
    },
    "contribution": {
      "contributor_org_id": "org_dev_studio_01",
      "app_id": "app_robot_nav",
      "integration_id": "int_robot_nav_01",
      "declared_domain": "robotics_navigation",
      "declared_intent": "production",
      "idempotency_key": "nav-pulse-001"
    },
    "traceability": {
      "source_event_id": "robot-evt-7781",
      "fingerprint": "sha256:abc123",
      "data_rights_asserted": true
    },
    "payload": {
      "event": {
        "robot_id": "rb-17",
        "pose_confidence": 0.94,
        "friction_score": 0.28
      }
    }
  }'

{
  "contribution_id": "CTRB_01JQ...",
  "status": "submitted",
  "technical_state": "accepted",
  "economic_state": "credit_pending",
  "delivery_channel": "heartbeat_inbox",
  "queued": true,
  "credit_eligible_initial": true,
  "policy_version": "dcp_credit_policy_v0_2"
}

GET /contributions/{contribution_id}/audit

{
  "contribution_id": "CTRB_01JQ...",
  "audit_events": [
    {"stage": "ingest", "result": "submitted", "reason_family": "ingest"},
    {"stage": "policy_screening", "result": "accepted", "reason_family": "policy"},
    {"stage": "canonical_routing", "result": "integrated_experience", "routing_result": "experience"},
    {"stage": "credit_scoring", "result": "credited", "reason_family": "economic"}
  ]
}

GET /credit-summary

{
  "org_id": "org_dev_studio_01",
  "billing_cycle": "2026-03",
  "totals": {"credited_units": 5.0, "pending_units": 0.0, "applied_units": 5.0},
  "health": {"submitted_count": 4, "accepted_count": 3, "credited_count": 1}
}

Developer: Bearer API key.

UIL: HMAC request signing + key ID.

Legacy compatibility: /api/v1/public/*, /api/v2/packages/*, /api/v1/integration/uil/*.