Getting Started

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

1

Create an account

Sign up for a free account at SpaceDB. No credit card required.

2

Create an app

From the developer portal, click New App. Give it a name — this is just for your own reference.

A read token is provisioned automatically as soon as the app is created.

3

Copy your token

Your token is displayed once immediately after app creation. Copy it somewhere safe — it won't be shown again. You can always create a new token from the app detail page if you lose it.

4

Send your first request

Pass your token in the Authorization header. The example below fetches the list of planets:

Terminal

curl https://spacedb.cloud/api/v1/planets \
  -H "Authorization: Bearer YOUR_TOKEN"

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 \
  -H "Authorization: Bearer YOUR_TOKEN"

Open Postman and create a new request:

Set the method to GET and enter the URL https://spacedb.cloud/api/v1/planets
Click the Authorization tab, set the type to Bearer Token, and paste your token into the Token field.
Click Send.

To reuse your token across requests, add it to a Collection Variable named token and reference it as {{token}} in the Bearer Token field.

Open Insomnia and create a new HTTP request:

Set the method to GET and enter the URL https://spacedb.cloud/api/v1/planets
Open the Auth tab and select Bearer Token from the dropdown.
Paste your token into the Token field and click Send.

To share the token across multiple requests, create an Environment with a variable token and reference it as _.token in the Bearer Token field.

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