API Reference

https://api.heliora.app/api

Authorization: Bearer hlr_your_api_key_here

{
  "data": { ... },
  "meta": {
    "timestamp": "2026-04-05T14:32:00Z",
    "freshness_state": "LIVE",
    "source": "SDO/HMI SHARP",
    "phase": "NOMINAL"
  }
}

{
  "error": "Invalid API key"
}

// HTTP status codes:
// 400 - Bad request (invalid parameters)
// 401 - Invalid or missing API key
// 403 - Insufficient tier for this endpoint
// 404 - Resource not found
// 429 - Rate limit exceeded (check Retry-After header)

curl -H "Authorization: Bearer hlr_your_key" \
  https://api.heliora.app/api/status

{
  "data": {
    "phase": "WATCH",
    "label": "Active Region Developing",
    "text": "AR 13664 showing increasing magnetic complexity.",
    "evidence_type": "photospheric",
    "timestamp": "2026-04-05T14:32:00Z",
    "ar_count": 3
  },
  "meta": {
    "timestamp": "2026-04-05T14:32:00Z",
    "freshness_state": "LIVE",
    "source": "Heliora Status Engine",
    "phase": "WATCH"
  }
}

curl -H "Authorization: Bearer hlr_your_key" \
  https://api.heliora.app/api/regions

{
  "data": [
    {
      "ar": 13664,
      "danger_rank": 1,
      "danger_score": 7.2,
      "confidence": 68,
      "trend": "rising",
      "threat_band": "CRITICAL",
      "shape_locked": true,
      "rope_reorienting": false,
      "severity_indicator": "X-class likely",
      "hours_observed": 120,
      "location": "S17W42",
      "lifecycle_stage": "mature"
    }
  ],
  "meta": { ... }
}

curl -X POST \
  -H "Authorization: Bearer hlr_enterprise_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ops.example.com/heliora/events",
    "event_types": ["phase_transition", "cme_detected", "l1_crossing"],
    "filters": { "min_g_level": "G3" }
  }' \
  https://api.heliora.app/api/webhooks

{
  "data": {
    "id": "wh_1712345678_a1b2c3d4e5f6",
    "url": "https://ops.example.com/heliora/events",
    "event_types": ["phase_transition", "cme_detected", "l1_crossing"],
    "filters": { "min_g_level": "G3" },
    "secret": "whsec_...",
    "created_at": "2026-04-05T14:32:00Z",
    "active": true
  }
}

{
  "event_type": "phase_transition",
  "timestamp": "2026-04-05T14:32:00Z",
  "data": {
    "from_phase": "WATCH",
    "to_phase": "ADVISORY",
    "trigger": "AR 13664 danger score crossed 7.0",
    "evidence_type": "photospheric"
  }
}

X-Heliora-Signature: a1b2c3d4e5f6...  (HMAC-SHA256 hex)
X-Heliora-Event: phase_transition
X-Heliora-Delivery: dlv_1712345678_a1b2c3

import hmac, hashlib

def verify_signature(body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

import crypto from 'crypto';

function verifySignature(body, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

curl -X POST \
  -H "Authorization: Bearer hlr_enterprise_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Team",
    "triggers": [
      { "type": "score_rising", "threshold": 70, "enabled": true },
      { "type": "new_cme", "threshold": 0, "enabled": true },
      { "type": "phase_change", "threshold": 0, "enabled": true },
      { "type": "window_shift", "threshold": 4, "enabled": false }
    ]
  }' \
  https://api.heliora.app/api/profiles

{
  "data": {
    "id": "prof_1712345678_a1b2c3d4e5f6",
    "name": "Ops Team",
    "triggers": [
      { "type": "score_rising", "threshold": 70, "enabled": true },
      { "type": "new_cme", "threshold": 0, "enabled": true },
      { "type": "phase_change", "threshold": 0, "enabled": true },
      { "type": "window_shift", "threshold": 4, "enabled": false }
    ]
  }
}

curl -X PUT \
  -H "Authorization: Bearer hlr_enterprise_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Team (updated)",
    "triggers": [
      { "type": "score_rising", "threshold": 60, "enabled": true },
      { "type": "new_cme", "threshold": 0, "enabled": true }
    ]
  }' \
  https://api.heliora.app/api/profiles/{id}

curl -H "Authorization: Bearer hlr_enterprise_key" \
  "https://api.heliora.app/api/archive/events?start_after=2024-01-01&g_level=G3&limit=10"

{
  "data": [
    {
      "id": "evt-20250115-001",
      "source_ar": 13955,
      "flare_class": "X2.3",
      "g_level": "G3",
      "phase_reached": "WARNING",
      "cme_speed": 1550,
      "start_time": "2025-01-15T16:00:00Z",
      "end_time": "2025-01-17T22:00:00Z",
      "peak_dst": -210,
      "peak_kp": 7
    }
  ],
  "pagination": {
    "cursor": "evt-20250115-001",
    "limit": 10,
    "total": 5
  }
}

curl -H "Authorization: Bearer hlr_enterprise_key" \
  -H "Accept: text/csv" \
  "https://api.heliora.app/api/archive/events?g_level=G3"

curl -H "Authorization: Bearer hlr_enterprise_key" \
  https://api.heliora.app/api/archive/events/evt-20240510-001/timeline

{
  "data": [
    {
      "timestamp": "2024-05-10T06:00:00Z",
      "phase": "WATCH",
      "danger_score": 5.2,
      "confidence": 45,
      "bz": null,
      "speed": null,
      "dst": -12,
      "note": "X5.8 flare detected from AR 13664"
    },
    {
      "timestamp": "2024-05-11T16:37:00Z",
      "phase": "EMERGENCY",
      "danger_score": 9.6,
      "confidence": 95,
      "bz": -38,
      "speed": 820,
      "dst": -110,
      "note": "Interplanetary shock detected at L1"
    }
  ]
}

import requests

API_KEY = "hlr_your_api_key"
BASE_URL = "https://api.heliora.app/api"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Get current status
status = requests.get(f"{BASE_URL}/status", headers=headers).json()
print(f"Phase: {status['data']['phase']}")

# List active regions
regions = requests.get(f"{BASE_URL}/regions", headers=headers).json()
for ar in regions["data"]:
    print(f"AR {ar['ar']}: score={ar['danger_score']}, trend={ar['trend']}")

# Get historical events as CSV
resp = requests.get(
    f"{BASE_URL}/archive/events",
    headers={**headers, "Accept": "text/csv"},
    params={"g_level": "G3"}
)
with open("events.csv", "w") as f:
    f.write(resp.text)

# Register a webhook
webhook = requests.post(
    f"{BASE_URL}/webhooks",
    headers=headers,
    json={
        "url": "https://ops.example.com/heliora",
        "event_types": ["phase_transition", "l1_crossing"]
    }
).json()
print(f"Webhook ID: {webhook['data']['id']}")
print(f"Secret: {webhook['data']['secret']}")

const API_KEY = "hlr_your_api_key";
const BASE = "https://api.heliora.app/api";

const headers = { Authorization: `Bearer ${API_KEY}` };

// Get current status
const status = await fetch(`${BASE}/status`, { headers }).then(r => r.json());
console.log(`Phase: ${status.data.phase}`);

// List active regions
const regions = await fetch(`${BASE}/regions`, { headers }).then(r => r.json());
for (const ar of regions.data) {
  console.log(`AR ${ar.ar}: score=${ar.danger_score}`);
}

// Register a webhook
const webhook = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://ops.example.com/heliora",
    event_types: ["phase_transition", "l1_crossing"],
  }),
}).then(r => r.json());

console.log(`Webhook: ${webhook.data.id}`);
console.log(`Secret: ${webhook.data.secret}`);

// Poll for transit data
const transit = await fetch(`${BASE}/transit`, { headers }).then(r => r.json());
for (const cme of transit.data) {
  console.log(`CME ${cme.id}: ${cme.speed_km_s} km/s, ${cme.position_pct}% to Earth`);
}

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": "Rate limit exceeded"
}