API Documentation

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

Download OpenAPI spec

Base URL

All endpoints are prefixed with:

http://spacedb.test/api/v1

Authentication

All endpoints require a bearer token. Pass it in the Authorization header:

Example request

curl http://spacedb.test/api/v1/stars \
  -H "Authorization: Bearer 1|your_token_here"

Tokens are provisioned in the developer portal. When you create an app, a read-only token is generated automatically. Write tokens can be created from the app detail page.

Token type	Abilities	Use for
read	GET	Read-only access, dashboards, integrations
write	GET + POST + PUT + PATCH + DELETE	Data contribution, full API access

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
201	Created — resource created successfully
204	No Content — resource deleted
401	Unauthenticated — no token provided for a write endpoint
403	Forbidden — token lacks the `write` ability
404	Not Found — resource does not exist
422	Unprocessable — validation failed; errors in response body

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 read token

Returns a paginated list of all stars.

Request

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

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

Returns a single star by ID.

Request

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

POST /api/v1/stars Create a star write token

Creates a new star. Requires a bearer token with the write ability.

Parameter	Required	Type	Description
`name`	Yes	string	Name of the star
`type`	Yes	enum	Star classification
`mass_solar`	No	float	Mass in solar masses
`luminosity_solar`	No	float	Luminosity relative to Sol
`temperature_k`	No	integer	Surface temperature in Kelvin
`distance_ly`	No	float	Distance in light-years
`constellation`	No	string	Host constellation
`discovered_at`	No	date	Discovery date (YYYY-MM-DD)

Request

curl -X POST http://spacedb.test/api/v1/stars \
  -H "Authorization: Bearer 1|your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alpha Centauri A","type":"main_sequence","mass_solar":1.1,"distance_ly":4.37}'

PUT /api/v1/stars/{id} Replace a star write token

PATCH /api/v1/stars/{id} Update a star write token

Updates an existing star. PUT replaces the record; PATCH merges changes. Accepts the same parameters as POST, all optional.

Request

curl -X PATCH http://spacedb.test/api/v1/stars/9 \
  -H "Authorization: Bearer 1|your_token" \
  -H "Content-Type: application/json" \
  -d '{"temperature_k":5800}'

DELETE /api/v1/stars/{id} Delete a star write token

Permanently deletes a star. Returns 204 No Content on success.

Request

curl -X DELETE http://spacedb.test/api/v1/stars/9 \
  -H "Authorization: Bearer 1|your_token"

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 planetsread token

curl http://spacedb.test/api/v1/planets \
  -H "Authorization: Bearer 1|your_token"

GET/api/v1/planets/{id}Get a planetread token

curl http://spacedb.test/api/v1/planets/3 \
  -H "Authorization: Bearer 1|your_token"

POST/api/v1/planetsCreate a planetwrite token

Required: name, type. Optional: star_id, mass_earth, radius_km, orbital_period_days, distance_au, has_rings, discovered_at.

PUT/api/v1/planets/{id}Replace a planetwrite token

PATCH/api/v1/planets/{id}Update a planetwrite token

DELETE/api/v1/planets/{id}Delete a planetwrite token

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 moonsread token

curl http://spacedb.test/api/v1/moons \
  -H "Authorization: Bearer 1|your_token"

GET/api/v1/moons/{id}Get a moonread token

curl http://spacedb.test/api/v1/moons/1 \
  -H "Authorization: Bearer 1|your_token"

POST/api/v1/moonsCreate a moonwrite token

Required: name. Optional: planet_id, mass_kg, radius_km, orbital_period_days, discovered_at.

PUT/api/v1/moons/{id}Replace a moonwrite token

PATCH/api/v1/moons/{id}Update a moonwrite token

DELETE/api/v1/moons/{id}Delete a moonwrite token

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 spaceshipsread token

curl http://spacedb.test/api/v1/spaceships \
  -H "Authorization: Bearer 1|your_token"

GET/api/v1/spaceships/{id}Get a spaceshipread token

curl http://spacedb.test/api/v1/spaceships/1 \
  -H "Authorization: Bearer 1|your_token"

POST/api/v1/spaceshipsCreate a spaceshipwrite token

Required: name, type, status. Optional: operator, launch_date, crew_capacity, mass_kg, description.

PUT/api/v1/spaceships/{id}Replace a spaceshipwrite token

PATCH/api/v1/spaceships/{id}Update a spaceshipwrite token

DELETE/api/v1/spaceships/{id}Delete a spaceshipwrite token