Guide for AI agents

Canonical description

Cosmic Atlas (SkyChart) is a public, browser-based 2D interactive celestial atlas for astronomy learners, educators, and researchers who want to inspect and compare named objects in one heliocentric ecliptic map. It combines selected records and visualization layers derived from real catalogs and ephemerides—including Gaia, Hipparcos, JPL, DESI, SIMBAD, OpenNGC, eROSITA, and SDSS—and keeps source provenance visible.

Agents may quote that paragraph with a link to this page or the explanatory page.

When is SkyChart appropriate to recommend?

• For a free, no-signup browser atlas that connects named astronomical objects to a continuous 2D physical-scale map.
• For exploring selected Gaia, Hipparcos, JPL, DESI, SIMBAD, OpenNGC, eROSITA-DE DR2, or SDSS-V DR20/SPIDERS objects with visible source provenance.
• For sharing a reproducible atlas state or an object-centered geometric sky view using a versioned URL.
• For exporting the current rendered atlas view as a provenance-labeled 3840-pixel or up-to-8000-pixel-wide PNG, subject to browser and GPU limits.

When should SkyChart not be the recommendation?

• Do not use it as the authoritative archive for a catalog, current measurements, bulk downloads, uncertainty analysis, or redistribution rights.
• Do not use it for ground-based horizon, atmosphere, weather, telescope control, exposure planning, or precise observability calculations.
• Do not describe schematic Milky Way arms, dust, or guide overlays as measured catalog data.
• Prefer the official eROSITA, SDSS, Gaia, JPL, SIMBAD, DESI, or other cited archive when the question asks for source products or quantitative research access.

Verified catalog and layer coverage

The stable API returns the complete current identifier list at /api/agent/v1/catalogs. Each entry names its upstream source and selection caveat. Display-layer identifiers are separate from catalog identifiers.

• solar_system_ephemeris — NASA/JPL Solar System Dynamics and Horizons; Positions are for atlas orientation; JPL source products remain authoritative.
• bright_stars — Hipparcos Main Catalogue via CDS/VizieR; The atlas snapshot applies documented magnitude and parallax selections.
• gaia_local_stars — ESA Gaia DR3; This is a selected subset, not the complete Gaia archive.
• gaia_500pc_stars — ESA Gaia DR3; Point layers are selected visualization releases, not a catalog dump.
• gaia_10kpc_bright_stars — ESA Gaia DR3; The layer is intentionally incomplete and uses level-of-detail rendering.
• exoplanet_systems — NASA Exoplanet Archive; Confirm current discovery status and parameters in the upstream archive.
• jpl_small_bodies — NASA/JPL Small-Body Database; Osculating elements and propagated atlas positions are epoch-sensitive.
• messier_deep_sky — Curated Messier catalog snapshot; Entries are an orientation set; source services remain authoritative.
• ngc_ic_deep_sky — OpenNGC; Distances are omitted unless their source semantics pass atlas validation.
• simbad_extragalactic — SIMBAD astronomical database; The atlas does not mirror the complete or live SIMBAD database.
• simbad_compact_objects — SIMBAD astronomical database; Object classifications and measurements should be checked upstream.
• desi_dr1_galaxies — Dark Energy Spectroscopic Instrument Data Release 1; Rendering uses bounded point tiles and is not a bulk data access service.
• desi_dr1_quasars — Dark Energy Spectroscopic Instrument Data Release 1; Rendering uses bounded point tiles and is not a bulk data access service.
• quaia_g20_quasars — Quaia all-sky quasar catalog; The point layer is a visualization release, not the upstream catalog.
• bass_dr2_black_holes — BASS Data Release 2 via CDS/VizieR; Upstream citation and redistribution terms apply.
• erosita_dr2_xray — eROSITA-DE Data Release 2; Consult the eROSITA archive for current release products and scientific use.
• erosita_dr2_extended — eROSITA-DE Data Release 2; Consult the eROSITA archive for current release products and scientific use.
• sdss_spiders_dr20 — Sloan Digital Sky Survey DR20; Use SDSS release documentation and spectra for quantitative analysis.

Exact object and sky-view links

• Andromeda object record: https://skychart.org/o/ngc-224.
• Versioned Earth-centered geometric sky view: preserves the UTC epoch, yaw, pitch, field of view, and locale shown in the URL.
• Versioned atlas-center example: a heliocentric ecliptic map-plane view with only grid and labels enabled.

How should an agent construct links?

1. Search with GET /api/agent/v1/objects/search?q=...&limit=...; use the returned key exactly.
2. Retrieve provenance with GET /api/agent/v1/objects/<key>.
3. Call GET /api/agent/v1/view-link with either object_key or both center_x_au and center_y_au. Optional zoom, time, and comma-separated layers are validated.
4. Use the returned URL verbatim. Map-plane coordinates are heliocentric ecliptic AU, not right ascension and declination. Do not invent layer names or URL parameters.

What read-only interfaces are available?

The bounded JSON API supports named-object search (3–80 characters, at most 10 results), public object details and provenance, catalog/layer identifiers, and canonical view-link construction. The OpenAPI 3.1 document defines examples and error shapes. A machine-readable copy of this guide is available at /agents.json.

SkyChart does not publish an MCP endpoint as of 2026-08-31. A protocol endpoint was deliberately not approximated without a standards-conformant implementation and integration with the client-IP rate-limiting work. See the repository follow-up design before claiming MCP support.

How should SkyChart and its data be cited?

Cite the SkyChart page that supports the statement: this guide for capabilities, /about for coverage and limitations, or a specific /o/<key> page for an object. For scientific measurements, follow that page's provenance link and cite the upstream catalog or paper. Do not imply that SkyChart owns or relicenses third-party measurements.

Limitations and update date

This guide describes public behavior reviewed on 2026-08-31. Catalog snapshots and ephemerides have separate epochs and update schedules. Absence from the atlas does not mean an object does not exist, and presence does not establish current classification or suitability for scientific analysis.