Open Data API · v0

API reference

A read-only, deterministic projection of the knowledge graph. Ten endpoints are implemented today; every response is wrapped in a provenance envelope.

Basics

Base path: /api/v0
Format: JSON, UTF-8. Method: GET only.
No authentication, no API keys, no rate limits.
No cookies, tracking, user data, or write/upload endpoints.
Cacheable & deterministic — the same request returns the same bytes for a data version.
Spec: /api/v0/openapi.json

The response envelope

Every response carries provenance metadata alongside its data:

{
  "meta": {
    "apiVersion": "v0",
    "schemaVersion": "1.0.0",
    "dataVersion": "1.0.0",
    "generatedAt": "2026-06-29T00:00:00Z",
    "source": "Asteria Star — Scientific Data Engine & Knowledge Graph",
    "license": "CC BY-SA 4.0",
    "attribution": "Asteria Star (asteriastar) — https://asteriastar.com. Underlying source data retains its own licenses; see https://asteriastar.com/data/licensing.",
    "provenance": "How this response was derived.",
    "docs": "https://asteriastar.com/developers/api"
  },
  "count": 8,
  "data": "…"
}

Endpoints

entities relationships search traversal assistant datasets citations images sources graph live-sky meta contributions

GET/api/v0/entities

Implemented

Paginated list of canonical entities, sorted by stable id. Every item carries its id, type, name, domain, and canonical path.

Parameter	In	Type	Description
type	query	string	Filter by entity type (e.g. star, planet, galaxy).
domain	query	string	Filter by domain (science, culture, astrology).
limit	query	integer	Maximum results to return (default 100, max 1000).
offset	query	integer	Number of results to skip for pagination.

Returns

{ total, offset, limit, count, items: Entity[] }

Try it

/api/v0/entities?type=planet&limit=8

GET/api/v0/entities/{id}

Implemented

Resolve a single entity by its stable id, including its typed relationships (with direction and the entity on the other end).

Parameter	In	Type	Description
id*	path	string	Stable entity id (type:slug).

Returns

Entity & { relationships: RelationshipEdge[] }

Try it

/api/v0/entities/planet:mars

GET/api/v0/relationships

Implemented

Paginated list of typed, domain-tagged relationships. Filter by relation type, domain, or a specific from/to entity id.

Parameter	In	Type	Description
type	query	string	Filter by relation type.
domain	query	string	Filter by domain (science, culture, astrology).
from	query	string	Filter to relationships originating at this entity id.
to	query	string	Filter to relationships pointing at this entity id.
limit	query	integer	Maximum results to return (default 200, max 2000).
offset	query	integer	Number of results to skip for pagination.

Returns

{ total, offset, limit, count, items: Relationship[] }

Try it

/api/v0/relationships?from=planet:mars

GET/api/v0/search

Implemented

Deterministic, non-semantic entity search over name, aliases, and id. Ranking is fixed (exact > prefix > alias > substring); there is no AI or fuzzy relevance.

Parameter	In	Type	Description
q*	query	string	Search query.
type	query	string	Filter by entity type (e.g. star, planet, galaxy).
domain	query	string	Filter by domain (science, culture, astrology).
limit	query	integer	Maximum results to return (default 20, max 100).

Returns

{ query, count, results: SearchHit[] }

Try it

/api/v0/search?q=andromeda&limit=5

GET/api/v0/traversal

Implemented

Breadth-first traversal from a start entity, returning nodes and edges. Cycle-protected and bounded by maxDepth and limit; truncation is reported in warnings.

Parameter	In	Type	Description
start*	query	string	Start entity id.
maxDepth	query	integer	Traversal depth (default 2, max 5).
relationTypes	query	string	Comma-separated relation types to follow.
domain	query	string	Restrict to science, culture/astrology (interpretive), or all.
limit	query	integer	Maximum results to return (default 100, max 500).

Returns

{ start, nodes[], edges[], truncated, warnings[] }

Try it

/api/v0/traversal?start=star:sirius&maxDepth=2

GET/api/v0/assistant/explain

Implemented

A grounded explanation of an entity — its description, its real graph relations, and its cited sources. Deterministic; no language model. Nothing is generated or invented.

Parameter	In	Type	Description
id*	query	string	Entity id to explain.

Returns

{ entity, description?, sources?, links[], citations[] }

Try it

/api/v0/assistant/explain?id=planet:mars

GET/api/v0/assistant/compare

Implemented

Compares two entities by the real common ground between them — the entities they both connect to in the graph. Deterministic; no language model.

Parameter	In	Type	Description
a*	query	string	First entity id.
b*	query	string	Second entity id.

Returns

{ a, b, shared: Ref[] }

Try it

/api/v0/assistant/compare?a=planet:mars&b=planet:venus

GET/api/v0/assistant/path

Implemented

The shortest evidence path between two entities — a real chain of graph relations. Deterministic; no language model. 404 with an honest message when no path exists.

Parameter	In	Type	Description
from*	query	string	Start entity id.
to*	query	string	Target entity id.

Returns

{ from, to, length, path: NeighborNode[] }

Try it

/api/v0/assistant/path?from=astronomer:edwin-hubble&to=cosmology_concept:dark-energy

GET/api/v0/datasets

Implemented

The full open-data catalogue — domain datasets and graph-level datasets — with real record counts, licenses, formats, and status.

Returns

{ count, datasets: CatalogueEntry[] }

Try it

/api/v0/datasets

GET/api/v0/datasets/{id}

Implemented

Metadata for a single dataset by id, including its formats and (where a pre-generated file exists) real size and sha256.

Parameter	In	Type	Description
id*	path	string	Dataset id.

Returns

CatalogueEntry

Try it

/api/v0/datasets/stars

GET/api/v0/citations

Implemented

The real citation registry — source-backed references across flagship entities and datasets, with DOIs where verified. Filter by type, source, entity, or dataset.

Parameter	In	Type	Description
type	query	string	Filter by citation type (e.g. peer_reviewed_paper, dataset).
source	query	string	Filter by source-registry key (e.g. nasa, esa).
entity	query	string	Filter to citations supporting an entity id.
dataset	query	string	Filter to citations supporting a dataset slug.
limit	query	integer	Maximum results (default 200, max 500).
offset	query	integer	Pagination offset.

Returns

{ total, offset, limit, count, items: Citation[] }

Try it

/api/v0/citations?type=peer_reviewed_paper

GET/api/v0/citations/{id}

Implemented

A single citation by id, including its type, DOI (if verified), links to entities/datasets/provenance, and formatted references.

Parameter	In	Type	Description
id*	path	string	Citation id.

Returns

Citation & { formats }

Try it

/api/v0/citations/cite:mayor-queloz-1995

GET/api/v0/images

Implemented

Catalogue of verified scientific images with depicted object, capturing instrument, source, and license. Image files retain their upstream license.

Parameter	In	Type	Description
limit	query	integer	Maximum results to return (default 50, max 200).

Returns

{ total, count, items: Image[] }

Try it

/api/v0/images?limit=10

GET/api/v0/sources

Implemented

The platform's source registry — every source's name, organisation, canonical URL, scope, authority type, and usage terms. The provenance behind every cited fact.

Returns

{ count, sources: Source[] }

Try it

/api/v0/sources

GET/api/v0/live-sky/providers

Implemented

The registry of external providers the live-sky layer is designed to integrate. Every provider reports its integration status honestly (currently all planned).

Returns

{ count, connected, providers: Provider[] }

Try it

/api/v0/live-sky/providers

GET/api/v0/live-sky/moon

Implemented

The computed Moon (method: computed — not a live provider feed), with its own honesty envelope. WITHOUT latitude/longitude: the global Moon phase and illuminated fraction. WITH latitude and longitude: location-aware moonrise, moonset, transit, topocentric position, phase, and horizon status for the date (polar and no-rise/no-set cases handled honestly). Location is only ever what you pass in — never inferred, geolocated, or stored.

Parameter	In	Type	Description
date	query	string	Compute for a specific date (YYYY-MM-DD or ISO-8601). Defaults to the current instant / today.
latitude	query	string	Observer latitude, −90 to 90. When given (with longitude), returns location-aware moonrise/moonset/position.
longitude	query	string	Observer longitude, −180 to 180. Required together with latitude.
timezone	query	string	IANA timezone id for local event times (e.g. Europe/Prague). Defaults to UTC.

Returns

MoonData & { envelope } | MoonPositionData & { envelope }

Try it

/api/v0/live-sky/moon?latitude=50.08&longitude=14.44&timezone=Europe/Prague

GET/api/v0/live-sky/sun

Implemented

Sunrise, sunset, solar noon, civil/nautical/astronomical twilight, day length, and a solar summary for an EXPLICIT location and date, deterministically COMPUTED from the public-domain NOAA Solar Calculator algorithm (method: computed — not a live provider feed). Polar day/night is handled honestly (null events + a status). Location is only ever what you pass in — never inferred, geolocated, or stored.

Parameter	In	Type	Description
latitude*	query	string	Observer latitude as a decimal number, −90 to 90.
longitude*	query	string	Observer longitude as a decimal number, −180 to 180.
date	query	string	Civil date (YYYY-MM-DD). Defaults to today (UTC).
timezone	query	string	IANA timezone id for local times (e.g. Europe/Prague). Defaults to UTC.

Returns

SunData & { envelope }

Try it

/api/v0/live-sky/sun?latitude=50.08&longitude=14.44&date=2025-06-21&timezone=Europe/Prague

GET/api/v0/live-sky/planets

Implemented

Computed, location-aware visibility for the naked-eye planets (Mercury–Saturn; Uranus/Neptune via ?planet): rise, set, transit, topocentric position, approximate magnitude, and conservative honest observing rules (method: computed — not a live provider feed). Positions use the public-domain NASA/JPL approximate planetary elements. Location is only ever what you pass in — never inferred, geolocated, or stored.

Parameter	In	Type	Description
latitude*	query	string	Observer latitude as a decimal number, −90 to 90.
longitude*	query	string	Observer longitude as a decimal number, −180 to 180.
date	query	string	Civil date (YYYY-MM-DD). Defaults to today.
timezone	query	string	IANA timezone id for local times (e.g. Europe/Prague). Defaults to UTC.
planet	query	string	One planet (mercury\|venus\|mars\|jupiter\|saturn\|uranus\|neptune). Default is the five naked-eye planets.

Returns

PlanetVisibilityData & { envelope }

Try it

/api/v0/live-sky/planets?latitude=50.08&longitude=14.44&timezone=Europe/Prague

GET/api/v0/live-sky/tonight

Implemented

A computed COMPOSITE of the Sun & Twilight, Moon, and Planet engines (method: computed_composite — not a live provider feed): twilight/darkness summary and night type, Moon phase/rise/set/position and moonlight impact, ranked naked-eye planet visibility, and best observing windows for an EXPLICIT location and date. It invents no weather, cloud, seeing, ISS, aurora, meteor, or comet data; a sub-engine failure yields a null section plus a limitation. Location is only ever what you pass in — never inferred, geolocated, or stored.

Parameter	In	Type	Description
latitude*	query	string	Observer latitude as a decimal number, −90 to 90.
longitude*	query	string	Observer longitude as a decimal number, −180 to 180.
date	query	string	Civil date (YYYY-MM-DD). Defaults to today.
timezone	query	string	IANA timezone id for local times (e.g. Europe/Prague). Defaults to UTC.

Returns

TonightObservingData & { envelope }

Try it

/api/v0/live-sky/tonight?latitude=50.08&longitude=14.44&timezone=Europe/Prague

GET/api/v0/openapi.json

Implemented

The OpenAPI 3.1 description of every implemented endpoint. Planned endpoints are intentionally absent from the spec.

Returns

OpenAPI 3.1 document

Try it

/api/v0/openapi.json

GET/api/v0/contribution-types

Implemented

The typed contribution models the scientific review workflow accepts, with their required targets, review track, and quality impact. Read-only.

Returns

{ count, contributionTypes: ContributionType[] }

Try it

/api/v0/contribution-types

GET/api/v0/review-states

Implemented

The contribution review-state machine: every state, its description, and its valid next states. Read-only.

Returns

{ count, states: ReviewState[] }

Try it

/api/v0/review-states

GET/api/v0/contribution-guidelines

Implemented

The workflow's core principle, contribution types, review states, roles, and security model — everything a future contributor or client needs. Read-only.

Returns

{ principle, types, states, roles, security }

Try it

/api/v0/contribution-guidelines

Planned

Documented for transparency; intentionally absent from the OpenAPI spec until real.

POST/api/v0/graph/sparql

Planned

A SPARQL 1.1 query endpoint over the graph's RDF. Architecture-ready: the JSON-LD/RDF export is live at /data/graph.jsonld and loads into any triple store today; a hosted SPARQL service is not yet available. No live endpoint is advertised.

Returns

SPARQL results (planned)

POST/api/v0/graph/graphql

Planned

A GraphQL endpoint over the same typed graph. Architecture-ready: the schema maps onto the graph and the REST API delivers the same data today; the resolver layer is not yet served.

Returns

GraphQL results (planned)

POST/api/v1/contributions

Planned

Planned (v1, future). Would accept a structured proposal for review. NOT implemented: there is no write endpoint, no authentication, and no persistence in this program.

Returns

Accepted proposal receipt (not available)

GET/api/v0/relationships/{id}

Planned

Planned. Relationship ids (from|type|to) are not URL-safe as path segments; today, filter the list endpoint by from/to/type instead.

Parameter	In	Type	Description
id*	path	string	Relationship id (from\|type\|to).

Returns

Relationship

GET/api/v0/live-sky/{provider}/now

Planned

Planned. Requires a connected external provider; no provider is connected yet, so no live data is served. The provider registry above is real.

Parameter	In	Type	Description
provider*	path	string	Provider key.

Returns

Live observation data (not available)