Loading…
Loading contentLoading…
Loading contentA read-only, deterministic projection of the knowledge graph. Ten endpoints are implemented today; every response is wrapped in a provenance 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": "…"
}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[] }
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[] }
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[] }
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[] }
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[] }
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[] }
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[] }
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[] }
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/datasetsMetadata 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/starsThe 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[] }
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 }
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=10The 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/sourcesThe 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[] }
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 }
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 }
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 }
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 }
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.jsonThe typed contribution models the scientific review workflow accepts, with their required targets, review track, and quality impact. Read-only.
Returns
{ count, contributionTypes: ContributionType[] }
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-statesThe 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 }
Documented for transparency; intentionally absent from the OpenAPI spec until real.
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)
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)
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)
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
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)