API Documentation

GET /regions

List all regions with their current escalation levels. No authentication required.

curl https://darchow.com/api/v1/regions

{
  "data": [
    {
      "slug": "middle-east",
      "name": "Middle East",
      "escalation_level": 3,
      "darchow_index": 67,
      "delta_24h": 12,
      "trend": "escalating",
      "escalation_label": "HIGH",
      "data_quality_confidence": "high",
      "surge_active": false,
      "manual_override": false
    }
  ],
  "meta": {
    "total": 5,
    "generated_at": "2026-03-06T12:00:00Z",
    "tier": "public",
    "rate_limit_remaining": 95
  }
}

GET /regions/:slug/briefing

Current AI-compiled briefing for a region. Public access returns the lede and developments. Pro accounts receive full source provenance.

curl -H "Authorization: Bearer darchow_your_key_here" \
  https://darchow.com/api/v1/regions/middle-east/briefing

{
  "data": {
    "lede": "Escalation in southern Lebanon...",
    "developments": [...],
    "generated_at": "2026-03-06T06:00:00Z",
    "sources": {
      "gated": true,
      "reason": "Pro tier required for full source provenance",
      "upgrade_url": "https://darchow.com/pricing",
      "domain_count": 14,
      "source_count": 28,
      "domains": ["reuters.com", "t.me", "aljazeera.com"]
    }
  },
  "meta": {
    "region": "middle-east",
    "source_count": 14,
    "tier": "free",
    "rate_limit_remaining": 180
  }
}

GET /regions/:slug/cards

Inference cards for a region, sorted by confidence score. Each card represents a cluster of correlated events graded by the Admiralty Engine.

curl -H "Authorization: Bearer darchow_your_key_here" \
  "https://darchow.com/api/v1/regions/middle-east/cards?limit=10&grade=A,B"

Free tier response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "admiralty_grade": "B",
      "confidence_score": 0.74,
      "headline": "Artillery strikes reported near Kherson",
      "summary": "Multiple RSS and Telegram sources report...",
      "sources": {
        "gated": true,
        "reason": "Pro tier required for full source provenance",
        "upgrade_url": "https://darchow.com/pricing",
        "domain_count": 2,
        "source_count": 4,
        "domains": ["liveuamap.com", "t.me"]
      },
      "provenance": {
        "gated": true,
        "reason": "Pro tier required for full provenance timeline",
        "upgrade_url": "https://darchow.com/pricing"
      },
      "event_time": "2026-03-06T08:30:00Z"
    }
  ],
  "meta": { "region": "ukraine-russia", "total": 42, "tier": "free" }
}

Pro tier response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "admiralty_grade": "B",
      "confidence_score": 0.74,
      "headline": "Artillery strikes reported near Kherson",
      "summary": "Multiple RSS and Telegram sources report...",
      "sources": [
        { "type": "rss", "domain": "liveuamap.com", "headline": "..." },
        { "type": "telegram", "channel": "ua_south_front", "headline": "..." }
      ],
      "provenance": {
        "unique_source_count": 2,
        "has_physical_proof": false,
        "coordinates": { "lat": 46.63, "lng": 32.62 }
      },
      "event_time": "2026-03-06T08:30:00Z"
    }
  ],
  "meta": { "region": "ukraine-russia", "total": 42, "tier": "pro" }
}

GET /regions/:slug/cards/:id

Single inference card by UUID. Returns the same fields as the cards list endpoint, with sources and provenance gated by tier.

curl -H "Authorization: Bearer darchow_your_key_here" \
  https://darchow.com/api/v1/regions/middle-east/cards/a1b2c3d4-...

GET /regions/:slug/cards/:id/provenance

Pro only

Full source provenance for a card: every source event, its origin URL or channel, coordinates and the Admiralty confidence breakdown.

curl -H "Authorization: Bearer darchow_your_key_here" \
  https://darchow.com/api/v1/regions/middle-east/cards/a1b2c3d4-.../provenance

{
  "data": {
    "sources": [
      {
        "source_type": "rss",
        "headline": "Clashes reported near...",
        "url": "https://example.com/article",
        "occurred_at": "2026-03-06T08:15:00Z"
      }
    ],
    "confidence_breakdown": {
      "admiralty_grade": "B",
      "unique_sources": 2,
      "event_count": 4
    }
  },
  "meta": { "region": "middle-east", "card_id": "a1b2c3d4-...", "tier": "pro" }
}

Free tier requests to this endpoint receive a 403 with an upgrade URL.

GET /regions/:slug/escalation

Current escalation level for a region. Pass ?history=true&days=30 to include historical data points.

curl https://darchow.com/api/v1/regions/east-asia/escalation

{
  "data": {
    "level": 2,
    "darchow_index": 38,
    "delta_24h": -4,
    "trend": "de-escalating",
    "label": "ELEVATED",
    "confirmed_at": "2026-03-06T03:45:00Z",
    "surge_active": false,
    "intelligence": {
      "cards_active": 12,
      "cards_by_grade": { "A": 0, "B": 3, "C": 5, "D": 4 },
      "sources_active": 3,
      "source_types": ["rss", "telegram", "firms"],
      "has_physical_corroboration": false
    },
    "data_quality": {
      "confidence": "high",
      "warnings": [],
      "active_weight_pct": 94
    }
  },
  "meta": {
    "region": "east-asia",
    "tier": "public",
    "rate_limit_remaining": 88
  }
}

The darchow_index field is a 0 to 100 integer remapping of the raw escalation score. It is available on all tiers. The delta_24h field is the change in index points over the past 24 hours, null if less than 24 hours of history is available.

Authenticated requests include additional fields: component breakdown, raw mechanical score and escalation history when requested.

Additional endpoints