Référence API

• Base URL : https://nova-obsrouen.pages.dev
• Format : JSON (UTF-8) sauf indication contraire
• Timestamps : ISO 8601 UTC (2026-06-21T22:34:15.123Z)
• Coordonnées : J2000, RA en heures décimales (0-24), Dec en degrés (-90 à +90)
• Magnitudes : Bande V (visuelle) sauf précision
• Authentification : Bearer token Authorization: Bearer nva_xxx (endpoints /api/control/*)
• Erreurs : codes HTTP standards (401 Unauthorized, 400 Bad Request, 429 Rate Limit, 500 Internal)
• CORS : ouvert pour endpoints publics, fermé pour endpoints contrôle
• Rate limit : 60 req/min pour endpoints publics, 120 req/min pour endpoints agent

Statut du ciel à l'instant T pour l'observatoire (Rouen par défaut). Pas d'authentification.

GET /api/now.json HTTP/1.1
Host: nova-obsrouen.pages.dev

200 OK
{
  "timestamp": "2026-06-21T22:34:15Z",
  "observatory": { "lat": 49.44649, "lon": 1.09760, "altitude_m": 65 },
  "sun": { "alt_deg": -23.4, "az_deg": 358.2 },
  "moon": {
    "alt_deg": 41.2, "az_deg": 145.3,
    "illumination": 0.42, "age_days": 11.3,
    "phase": "waxing gibbous"
  },
  "astronomical_night": {
    "start": "2026-06-21T23:42:00Z",
    "end": "2026-06-22T01:18:00Z",
    "duration_min": 96
  },
  "weather": { "cloud_pct": 12, "humidity_pct": 78, "wind_kmh": 8.5 }
}

Liste des cibles imageables cette nuit avec score composite, triées par score décroissant.

GET /api/tonight.json HTTP/1.1

200 OK
{
  "night_start": "2026-06-21T23:42:00Z",
  "night_end": "2026-06-22T01:18:00Z",
  "targets": [
    {
      "id": "M13", "name": "Hercules Cluster",
      "score": 88,
      "altitude_max_deg": 75.2,
      "transit_time": "2026-06-22T00:18:00Z",
      "window_min": 96,
      "moon_separation_deg": 102
    },
    {
      "id": "M27", "name": "Dumbbell Nebula",
      "score": 84,
      "altitude_max_deg": 71.8,
      "transit_time": "2026-06-22T01:42:00Z",
      "window_min": 88,
      "moon_separation_deg": 87
    }
  ]
}

Export du catalogue complet au format N.I.N.A. Target Scheduler. Importable directement dans le module Sequence de N.I.N.A.

GET /api/nina.json HTTP/1.1

200 OK
Cache-Control: public, max-age=3600

{
  "GeneratedAt": "2026-06-21T22:34:15Z",
  "Generator": "nova-obsrouen.pages.dev",
  "Format": "NINA Target Scheduler · simplified preview",
  "Observatory": {
    "Name": "Observatoire de Rouen",
    "Latitude": 49.44649,
    "Longitude": 1.09760,
    "AltitudeM": 65
  },
  "Equipment": {
    "Mount": "Takahashi EM-400 Temma 2M",
    "Telescope": "Celestron C11",
    "Camera": "Atik 460EX",
    "Guider": "ZWO ASI120MC"
  },
  "TargetCount": 349,
  "Targets": [
    {
      "Id": "M1",
      "Name": "M1 — Crab Nebula",
      "Coordinates": {
        "RAHours": 5, "RAMinutes": 34, "RASeconds": 31.97,
        "DecDegrees": 22, "DecMinutes": 0, "DecSeconds": 52.1,
        "Epoch": "J2000"
      },
      "Type": "SNR",
      "Catalog": "Messier",
      "Constellation": "Taurus",
      "Magnitude": 8.4,
      "SizeArcmin": 6
    }
  ]
}

Calendrier iCal pour une cible donnée. L'événement représente la fenêtre d'observation utile du soir. Importable dans Apple Calendar, Google Calendar, Thunderbird, Proton Calendar.

GET /api/target/M31.ics HTTP/1.1

200 OK
Content-Type: text/calendar; charset=utf-8

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//nova-obsrouen//target M31//FR
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:M31-2026-06-21@nova-obsrouen.pages.dev
DTSTAMP:20260621T223415Z
DTSTART:20260622T013000Z
DTEND:20260622T040000Z
SUMMARY:M31 — Andromeda Galaxy · ALT 65°
DESCRIPTION:Score 92/100 · Pose recommandée 4h LRGB
LOCATION:Observatoire de Rouen
END:VEVENT
END:VCALENDAR

Calendrier multi-nuits pour une campagne pré-curatée. Toutes les nuits sur 30+ jours avec un score > 70 sont incluses, avec répartition LRGB / narrowband selon la phase lunaire.

GET /api/campaigns/m31-deep.ics HTTP/1.1

200 OK
Content-Type: text/calendar; charset=utf-8

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//nova-obsrouen//campaign m31-deep//FR
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:m31-deep-001@nova-obsrouen.pages.dev
SUMMARY:M31 deep · LRGB nuit 1/12
DTSTART:20260902T220000Z
DTEND:20260903T040000Z
END:VEVENT
...12 événements...
END:VCALENDAR

Heartbeat de l'agent — appelé toutes les 30 s par le binaire nova-agent embarqué. Bearer token obligatoire (préfixe nva_). Voir /docs/agent pour le format du payload.

POST /api/control/heartbeat HTTP/1.1
Authorization: Bearer nva_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "agent_version": "0.1.0",
  "timestamp": "2026-06-21T22:34:15Z",
  "mode": "read-only",
  "hardware": { ... },
  "weather": { ... }
}

200 OK
{
  "ok": true,
  "serverTime": "2026-06-21T22:34:15.456Z",
  "next_heartbeat_s": 30
}

Codes d'erreur :

• 401 Unauthorized — token manquant ou ne commence pas par nva_
• 400 Bad Request — body non JSON ou structure invalide

Récupération des commandes en attente. Appelé par l'agent après chaque heartbeat. Retourne un tableau JSON de commandes à exécuter.

GET /api/control/queue HTTP/1.1
Authorization: Bearer nva_xxxxxxxxxxxxxxxxxxxxxxxx

200 OK
[]    # vide pour l'instant (v0.1 stub, sera D1 en v0.13)

En v0.13, format prévu :

[
  {
    "id": "cmd-2026-06-21-001",
    "issued_at": "2026-06-21T22:33:00Z",
    "cmd": "goto",
    "params": { "ra_hours": 0.7128, "dec_deg": 41.269 },
    "deadline": "2026-06-21T22:40:00Z",
    "ack_required": true
  }
]

Soumission du résultat d'une commande exécutée (ou rejetée). Appelé par l'agent après exécution.

POST /api/control/result HTTP/1.1
Authorization: Bearer nva_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "cmd_id": "cmd-2026-06-21-001",
  "status": "ok",
  "executed_at": "2026-06-21T22:35:12.123Z",
  "duration_ms": 8421,
  "result": { ... },
  "logs": [ ... ]
}

200 OK
{ "ok": true }

Statuts possibles :

• "ok" — exécutée avec succès
• "rejected" — refusée par fail-safe (raison dans logs)
• "timeout" — durée dépassée
• "hardware_error" — erreur ASCOM/INDI
• "aborted" — kill switch activé pendant exécution