Getting Started

Up and running in under five minutes. Follow the steps below for your preferred tool.

1

No setup required

The API is public and read-only. You don't need an account or token — just send a GET request.

2

Send your first request

The example below fetches the list of planets:

Terminal

curl https://spacedb.cloud/api/v1/planets

You should receive a paginated JSON response with planet data. Try swapping planets for stars, moons, or spaceships to explore the other resources.

Fetch a single record

curl https://spacedb.cloud/api/v1/stars/1

Open Postman and create a new request:

Set the method to GET and enter the URL https://spacedb.cloud/api/v1/planets
Click Send.

Open Insomnia and create a new HTTP request:

Set the method to GET and enter the URL https://spacedb.cloud/api/v1/planets
Click Send.

API Documentation

SpaceDB is a REST API providing data on stars, planets, moons, and spacecraft. All responses are JSON. The API is read-only and fully public — no authentication required.

Download OpenAPI spec

Base URL

All endpoints are prefixed with:

http://spacedb.test/api/v1

Authentication

No authentication is currently required. All endpoints are public and read-only — only GET requests are supported.

Example request

curl http://spacedb.test/api/v1/stars

Requests are rate limited to 120 per minute. Exceeding the limit returns 429 Too Many Requests.

Responses

All successful responses return JSON. Single resources are wrapped in a data object. Collection responses include data, links, and meta.

Single resource — GET /api/v1/stars/1

{
  "data": {
    "id": 1,
    "name": "Sol",
    "type": "main_sequence",
    "mass_solar": 1,
    "luminosity_solar": 1,
    "temperature_k": 5778,
    "distance_ly": 0,
    "constellation": null,
    "discovered_at": null,
    "planet_count": 9,
    "created_at": "2026-01-01T00:00:00+00:00",
    "updated_at": "2026-01-01T00:00:00+00:00"
  }
}

Collection — GET /api/v1/stars

{
  "data": [ ... ],
  "links": {
    "first": "http://spacedb.test/api/v1/stars?page=1",
    "last":  "http://spacedb.test/api/v1/stars?page=1",
    "prev":  null,
    "next":  null
  },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 8
  }
}

Pagination

List endpoints return 25 results per page by default. Use the page and per_page query parameters to paginate. Maximum per_page is 100.

GET /api/v1/planets?page=2&per_page=10

Errors

Status	Meaning
200	OK — request succeeded
404	Not Found — resource or endpoint does not exist
405	Method Not Allowed — the API is read-only; only `GET` is supported
429	Too Many Requests — rate limit exceeded

Stars

Stellar objects including main sequence stars, giants, white dwarfs, neutron stars, and supergiants.

The star object

Field	Type	Description
`id`	integer	Unique identifier
`name`	string	Name of the star
`type`	enum	`main_sequence`, `red_giant`, `white_dwarf`, `neutron`, `supergiant`
`mass_solar`	float	Mass relative to the Sun (Sol = 1.0)
`luminosity_solar`	float	Luminosity relative to the Sun
`temperature_k`	integer	Surface temperature in Kelvin
`distance_ly`	float	Distance from Earth in light-years
`constellation`	string \| null	Host constellation
`discovered_at`	date \| null	Discovery date (ISO 8601)
`planet_count`	integer	Number of planets linked to this star

GET /api/v1/stars List all stars

Returns a paginated list of all stars.

Request

curl http://spacedb.test/api/v1/stars

GET /api/v1/stars/{id} Get a star

Returns a single star by ID.

Request

curl http://spacedb.test/api/v1/stars/1

Planets

Planetary bodies including terrestrial planets, gas giants, ice giants, and dwarf planets.

The planet object

Field	Type	Description
`id`	integer	Unique identifier
`name`	string	Name of the planet
`type`	enum	`terrestrial`, `gas_giant`, `ice_giant`, `dwarf`
`star_id`	integer \| null	ID of the parent star
`mass_earth`	float	Mass relative to Earth (Earth = 1.0)
`radius_km`	float	Mean radius in kilometres
`orbital_period_days`	float	Orbital period in Earth days
`distance_au`	float	Semi-major axis in astronomical units
`has_rings`	boolean	Whether the planet has a ring system
`discovered_at`	date \| null	Discovery date
`moon_count`	integer	Number of moons linked to this planet

GET/api/v1/planetsList all planets

curl http://spacedb.test/api/v1/planets

GET/api/v1/planets/{id}Get a planet

curl http://spacedb.test/api/v1/planets/3

Moons

Natural satellites orbiting planets.

The moon object

Field	Type	Description
`id`	integer	Unique identifier
`name`	string	Name of the moon
`planet_id`	integer \| null	ID of the parent planet
`mass_kg`	float	Mass in kilograms
`radius_km`	float	Mean radius in kilometres
`orbital_period_days`	float	Orbital period in Earth days
`discovered_at`	date \| null	Discovery date

GET/api/v1/moonsList all moons

curl http://spacedb.test/api/v1/moons

GET/api/v1/moons/{id}Get a moon

curl http://spacedb.test/api/v1/moons/1

Spaceships

Real and fictional spacecraft, probes, space stations, and rockets.

The spaceship object

Field	Type	Description
`id`	integer	Unique identifier
`name`	string	Name of the spacecraft
`type`	enum	`spacecraft`, `probe`, `station`, `rocket`
`operator`	string \| null	Operating agency or owner
`launch_date`	date \| null	Launch date
`status`	enum	`active`, `retired`, `planned`, `lost`
`crew_capacity`	integer \| null	Maximum crew size (null if uncrewed)
`mass_kg`	float \| null	Mass in kilograms
`description`	string \| null	Brief description

GET/api/v1/spaceshipsList all spaceships

curl http://spacedb.test/api/v1/spaceships

GET/api/v1/spaceships/{id}Get a spaceship

curl http://spacedb.test/api/v1/spaceships/1