API¶
You can automate your Asteroid's configuration through the Marvin API, which is also used by the uberspace command.
The API base URL is https://marvin.uberspace.is/api/v1/.
User-facing configuration endpoints are under external/.
The API reference describes request fields, response bodies, and allowed methods. It also contains internal endpoints; use the external endpoints described here for your Asteroid.
Authentication¶
Each Asteroid has an API key in /readonly/<username>/marvin_client.toml, in the api_key field.
Authenticate requests with the header Authorization: Api-Key <your-key>.
Use the Asteroid's name in URLs, and its own key for authentication.
The key does not grant administrative access to other Asteroids or hosts.
Treat this key like a password: anyone with it can change your Asteroid's configuration. Keep it out of source control and logs. If you use the API from another computer, store the key securely there and send requests over HTTPS.
What you can manage¶
The paths below are relative to /api/v1/external/asteroids/<username>/.
Replace placeholders with your own Asteroid, domain, or resource identifiers.
| Area | Path | Available operations |
|---|---|---|
| Asteroid settings | The Asteroid URL itself | Read details; change log settings, the replacement HTTP 500 page, and the SSH password. |
| Web domains | webdomains/ |
List, add, inspect, and remove domains; read DNS validation status. |
| Web backends | webdomains/<domain>/backends/ |
List, add, inspect, and remove backends for a domain. |
| HTTP response headers | webdomains/<domain>/headers/ |
List, add, inspect, and remove headers for a domain. |
| Mail domains | maildomains/ |
List, add, inspect, and remove mail domains. |
| Mail users | maildomains/<domain>/users/ |
List, add, inspect, update, and remove mail users. |
| Mail forwarding | maildomains/<domain>/users/<local>/forwards/ |
List, add, inspect, and remove forwarding destinations. |
| SSH keys | sshkeys/ |
List, add, inspect, and remove keys. |
| PostgreSQL databases | postgresdatabases/ |
List, create, inspect, and remove databases. |
| Software versions | toolversions/ |
List selected versions; read or change a tool's selection at toolversions/<tool>/. |
You can also list all mail users, web backends, and web headers for your Asteroid at mailusers/, webbackends/, and webheaders/.
Available tools and their versions are listed separately under /api/v1/external/tools/ and /api/v1/external/tools/<tool>/versions/.
Use GET to read, POST to create, PATCH to update supported fields, and DELETE to remove a resource.
Check the reference for each endpoint's methods and required fields; not every resource supports every method.
Keep the trailing slash in URLs, and URL-encode domain names, paths, or addresses when needed.
Normal requirements still apply, such as configuring and verifying DNS for web domains.
Requests and responses¶
Send request bodies as JSON with Content-Type: application/json, and request JSON responses with Accept: application/json.
The API reference lists the writable fields for each endpoint. Fields marked read-only describe the resource and cannot be changed through that request.
List responses are paginated: entries are in results, and next contains the next page's URL or null when there are no more pages.
Follow next to retrieve the entire collection. List endpoints also accept limit and offset query parameters.
A successful deletion generally returns HTTP 204 with no response body.
Deleting a mailbox or database can also delete its stored data.
Wait for changes to finish¶
Configuration changes can be processed in the background. An HTTP success response does not by itself mean the change has finished on the host.
When a response includes X-MARVIN-EVENT-ID, use its event IDs to check progress.
The header can contain multiple comma-separated IDs; check each one.
Events and their logs are available to your Asteroid's key under the shared endpoints /api/v1/common/events/<id>/ and /api/v1/common/events/<id>/logs/.
Read the event's state to check the result:
DONE: processing completed.FAILED: processing failed; inspect the event's logs.SKIPPED: the event was skipped; inspect its logs and check the resulting resource.
For other states, wait briefly before checking again. Once processing finishes, read the affected external endpoint again to confirm its configuration.
Errors¶
Read the HTTP response body for details: 400 usually indicates invalid input, 403 indicates an authentication or permission problem, and 404 indicates an unavailable resource or incorrect URL.
If a change times out, check the resource and any event IDs you received before repeating it: the server may already have accepted the request.