allskyhub

Connect a camera: connect/v1

SharedSky › For developers

With this interface any all-sky camera can measure along in SharedSky, whatever software it runs: commercial programs, your own scripts or tinkering projects. The camera sends to the hub over HTTPS. No MQTT, no FTP, no port forwarding. The contract behind it is SPEC §10.

For indi-allsky its configuration is enough, see below. Allsky has a module for it, see below. Allsky and every other camera that shows its latest image at a fixed address can also connect without any code of their own through that address ("Allsky / image address" under Connect a camera).

Signing in

Create a free account and choose Connect a camera. The hub then shows you once the station ID (26 characters) and the secret (64 hex characters). You can make a new secret at any time; the old one stops working at once. Every request carries the header

Authorization: Bearer <station ID>:<secret>

The address is https://allskyhub.org/api/connect/v1. All times are ISO 8601 in UTC, for example 2026-11-05T21:40:12Z.

1. Report the station: PUT /station

At start and whenever something changes:

{
  "name": "Hilltop Observatory",
  "latitude": 48.3, "longitude": 4.29, "elevation_m": 300,
  "software": "MySky", "software_version": "1.2",
  "lens": {"focal_mm": 1.55, "f_ratio": 2.0, "projection": "equidistant"},
  "width": 3096, "height": 2080,
  "clock_synced": true
}

Answer: {"orientation": null, "want_full_frame": false}

The orientation. Once the hub has oriented the camera by the stars, orientation is {north_deg, mirrored, solved_at, stars, rms_deg, lens: {cx, cy, a1, a3, tilt_east_deg, tilt_north_deg, width, height}}. north_deg is the image direction of north at the horizon (0 = up, clockwise); mirrored means east lies counter-clockwise from north, the usual view of a camera looking up. A direction (altitude, azimuth) lands at t = (90° − altitude) / 90°, r = a1·t + a3·t³, angle = north_deg − azimuth (mirrored) or north_deg + azimuth, x = cx + r·sin(angle), y = cy − r·cos(angle), in pixels of a width × height image; a leaning camera first turns the direction by its tilt (SPEC §4.8). Ready-made in Python: sky_to_pixel() in the Allsky module, for constellations or the cardinal points in your own image.

2. Send an image: POST /frames

About once a minute, multipart with two parts:

Answer: {"want_full_frame": false}

3. Report a meteor: POST /events

Multipart: metadata as JSON and image, the full image with the meteor, exactly width × height.

{
  "kind": "meteor",
  "start": "2026-11-05T21:40:00Z", "end": "2026-11-05T21:40:30Z",
  "peak": 0.8,
  "track": [[812, 431], [990, 502], [1140, 566]],
  "clock_synced": true
}

track is 2 to 32 points along the streak, in pixels of the full image. peak (0 to 1) is optional; without it the hub measures the brightness itself. Answer: {"id": "meteor-20261105T214000Z"}

Test mode

Under /api/connect/v1/test/station, /test/frames and /test/events the hub checks every request the same way but stores nothing, and answers what it understood: {"ok": true, "understood": {…}}. Try out a connection without any risk.

Limits and errors

120 requests a minute per station. The hub looks at every image and keeps a thumbnail every 5 minutes; at most 3000 meteors a night, at most 500 MB per station (above that the oldest full images go first). Errors come as {"error": "<code>"}:

StatuserrorMeaning
400bad_requesta field is missing or out of range, with field
400bad_imagenot a readable JPEG
400wrong_sizethe full image is not width × height
401unauthorizedunknown station or wrong secret
413too_largeimage too large
429too_often / night_fulltoo many requests, or too many meteors this night, with Retry-After

Example with curl

AUTH="Authorization: Bearer $STATION_ID:$SECRET"
curl -X PUT https://allskyhub.org/api/connect/v1/station -H "$AUTH" \
     -H 'Content-Type: application/json' -d @station.json
curl https://allskyhub.org/api/connect/v1/frames -H "$AUTH" \
     -F 'metadata={"time":"2026-11-05T21:40:15Z","exposure_s":30,"night":true,"clock_synced":true};type=application/json' \
     -F image=@thumb.jpg

Example in Python

import json

import requests

BASE = "https://allskyhub.org/api/connect/v1"
AUTH = {"Authorization": f"Bearer {STATION_ID}:{SECRET}"}

requests.put(f"{BASE}/station", json=station, headers=AUTH, timeout=30).raise_for_status()

meta = {"time": "2026-11-05T21:40:15Z", "exposure_s": 30, "night": True, "clock_synced": True}
with open("thumb.jpg", "rb") as image:
    r = requests.post(
        f"{BASE}/frames",
        headers=AUTH,
        files={"metadata": (None, json.dumps(meta), "application/json"), "image": image},
        timeout=30,
    )
print(r.json())  # {"want_full_frame": false}

Allsky

The SharedSky module for Allsky's module system sends the station, a small image about once a minute, the full frame when the hub asks for it, and every meteor the Meteor Detection (temporal) module saved, with its track. Copy allsky_sharedsky.py into ~/allsky/config/myFiles/modules/, add it to the day and night flows (at night after the meteor detection, before the overlay), enter the station ID and the secret, and press Test: the module then sends to the test mode above.

indi-allsky

indi-allsky needs no installation. In its configuration under SyncAPI: turn it on, Base URL https://allskyhub.org/indi-allsky, Username the station ID, API Key the secret, sync images: every image. indi-allsky then sends its location, lens, exposure, star count and the number of detected meteor trails with every image.

What happens to the data