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
}
width×heightis the size of the full image as the camera saves it, after any crop. All pixel positions refer to this image; when the size changes, the hub orients the camera by the stars anew.clock_synced: the clock runs on NTP or GPS. The hub also checks it on every image.
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:
metadata: JSON{"time", "exposure_s", "gain", "night", "clock_synced", "stars", "sky_brightness"};timeis the middle of the exposure.image: JPEG, normally a thumbnail (at most 640 px on the long side, 300 kB). Only when the last answer said"want_full_frame": true, the full image (at most 8 MB).
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>"}:
| Status | error | Meaning |
|---|---|---|
| 400 | bad_request | a field is missing or out of range, with field |
| 400 | bad_image | not a readable JPEG |
| 400 | wrong_size | the full image is not width × height |
| 401 | unauthorized | unknown station or wrong secret |
| 413 | too_large | image too large |
| 429 | too_often / night_full | too 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
- Images stay yours. The hub shows them only where you allow it, and always with the station's name.
- Measurements (times, tracks, paths, rates, sky brightness) are shared under CC BY 4.0 with the station's name; only so can they go on to scientific partners.
- Location: the exact place is used only for the calculations; publicly it is always rounded.