CERES API

Access Tiers

All tiers access the same endpoints and data quality. Free subscribers receive the monthly intelligence newsletter. Paid tiers unlock higher request volume, real-time Tier I/II email alerts, a weekly digest, weekly PDF intelligence briefs, and webhook delivery to any endpoint.

All paid subscriptions are billed monthly via Stripe and can be cancelled at any time. Questions? Email ceres@northflow.no.

Authentication & Account

Tier A (Open Research) endpoints are unauthenticated — no key required. Tier B and C endpoints require an X-API-Key header. Your key is emailed immediately after a successful Stripe checkout.

# Tier A — no authentication needed
GET https://ceres-core-production.up.railway.app/v1/predictions

# Tier B / C — include your API key
GET https://ceres-core-production.up.railway.app/v1/reports
X-API-Key: ceres_xxxxxxxxxxxxxxxxxxxxxxxx

Account Portal

Sign in to your account at ceres.northflow.no/login using a one-time magic link sent to your registered email — no password needed. From the account portal you can view your API key prefix, current usage, manage your billing subscription, and register webhook endpoints.

Alerts & Intelligence Delivery

CERES delivers intelligence through three channels depending on your tier:

Webhook Payload

Tier B/C subscribers can register webhook URLs from their account portal. On each escalation event, CERES POSTs the following JSON payload:

POST https://your-endpoint.example.com/ceres-webhook

Content-Type: application/json

{{
  "event": "ceres_alert",
  "run_id": "CERES-20260303-060012",
  "timestamp": "2026-03-03T06:00:12Z",
  "n_alerts": 2,
  "alerts": [
    {{ "region_id": "SDN", "alert_tier": "TIER-1", "p_ipc3plus_90d": 0.966 }}
  ]
}}

Open Data — HXL-Tagged CSV

CERES prediction archives are available as HXL-tagged CSV, free and unauthenticated, for direct use in humanitarian data workflows, HDX pipelines, and academic research. Licensed under CC BY 4.0. Published on the OCHA Humanitarian Data Exchange (HDX) since March 2026.

Row 1: column headers · Row 2: HXL hashtags (per HXL Standard) · Row 3+: data

Grading ledger (predictions + outcomes): /v1/export/grades/csv

Connection

# Production base URL
Base URL: https://ceres-core-production.up.railway.app

# All endpoints require the version prefix
GET https://ceres-core-production.up.railway.app/v1/predictions

# Tier B/C authentication — header, not Bearer token
X-API-Key: ceres_xxxxxxxxxxxxxxxxxxxxxxxx

# Tier A — no key required
GET https://ceres-core-production.up.railway.app/v1/predictions

Predictions

# Returns all monitored regions with current forecast
GET /v1/predictions?tier=1&format=json

# Response
{
  "run_id": "CERES-20260228-160603",
  "generated_at": "2026-02-28T16:06:03Z",
  "horizon_days": 90,
  "predictions": [
    {
      "region_id": "SDN",
      "region_name": "Sudan",
      "p_ipc3_plus": 0.966,
      "ci_lower": 0.923,
      "ci_upper": 0.984,
      "tier": 1,
      "composite_stress": 0.51,
      "primary_driver": "conflict"
    }
  ]
}

GET /v1/predictions/SDN

# Returns full prediction with hypothesis IDs
{
  "region_id": "SDN",
  "p_ipc3_plus": 0.966,
  "p_ipc4_plus": 0.676,
  "ci_lower": 0.923,
  "ci_upper": 0.984,
  "hypothesis_ids": ["H-SDN-001", "H-SDN-002", "H-SDN-003"]
}

Query Parameters

Hypotheses

GET /v1/hypotheses/H-SDN-001

{
  "id": "H-SDN-001",
  "region_id": "SDN",
  "rank": 1,
  "archetype": "conflict-driven",
  "confidence": 0.88,
  "text": "Armed conflict has severely disrupted agricultural labour...",
  "evidence": [
    {
      "source": "UCDP GED",
      "variable": "conflict_events_4wk",
      "observed": 312,
      "threshold": 50,
      "direction": "above",
      "verdict": "SUPPORTS"
    }
  ]
}

Admin1 Resolution

GET /v1/admin1/ETH

# Returns Admin1 units for Ethiopia
{
  "country": "ETH",
  "units": [
    {
      "admin1_id": "ETH-OR",
      "name": "Oromia",
      "composite_stress": 0.61,
      "ipc_phase_current": 3,
      "signals": { "chirps": -1.8, "ndvi": -0.14 ... }
    }
  ]
}

Response Format

All endpoints return JSON. Dates are ISO 8601. Probabilities are floats in [0, 1]. Confidence intervals are 90% input-perturbation sensitivity intervals.

# Standard envelope
{
  "run_id": "CERES-20260228-160603",
  "generated_at": "2026-02-28T16:06:03Z",
  "horizon_days": 90,
  "reference_date": "2026-02-28",
  "data": { ... }
}

# Error envelope
{
  "error": "region_not_found",
  "message": "Region XYZ is not currently monitored",
  "status": 404
}

All probabilities follow the same field pattern: p_ipc3plus_90d, ci_90_low, ci_90_high.

Attribution Requirements

All use of CERES data — whether in publications, dashboards, or operational systems — requires attribution to Northflow Technologies and CERES.

# Required attribution string
"Source: CERES (Calibrated Early-warning and Risk Estimation System),
 Northflow Technologies, 2026. ceres.northflow.no"

# For academic publications, cite the paper
"Pedersen, Tom Danny S. (2026). CERES: A Probabilistic Early Warning
 System for Acute Food Insecurity. arXiv:2603.09425 [stat.AP]"

CERES predictions are provided under a Creative Commons Attribution 4.0 International licence (CC BY 4.0). Commercial use requires a Tier B or C agreement.