Cloudron API
Introduction
Cloudron provides a RESTful API to manage apps, users, groups, domains and other resources.
All of the functionality in the Cloudron Dashboard is available through the API, allowing you to script complex actions.
If you are an app developer, the Cloudron CLI tool implements a workflow that allows you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.
Requests
The API follows standard HTTP REST API conventions.
| Method | Usage |
|---|---|
| GET | Retrieveal operations |
| DELETE | Destroys a resource |
| POST | Create new objects or start a new task. Also used to update parts of a resource |
| PUT | Idempotent operation that replaces a resource |
| PATCH | API does not support PATCH |
| HEAD | Read response headers and get no response |
HTTP Statuses
The API follows standard HTTP REST API response conventions.
2xx responses indicate success. 4xx responses indicate request errors. 5xx responses indicate server errors.
| Name | Description |
|---|---|
| 200 | Success. Operation succeeded, response body contains more information |
| 204 | Success. Operation succeeded, empty response body |
| 401 | Access Denied. Usually caused by missing, invalid or expired token |
| 403 | Forbidden. Authenticated but operation not permitted. Usually caused by insufficient role/permissions |
| 5xx | Internal Server error |
Pagination
When listing objects, query parameters page and per_page can be passed in. Note that these parameters have index
starting from 1.
API Token
To use the REST API, you must first create an API token. This token can be provided in two ways:
- Via the request query parameter
?access_token=<token> - Via the Authorization header
Bearer <token>
API Tokens can be created as Readonly or Read and Write. With Readonly token, only GET operations can be performed.
cURL Examples
We use curl to demonstrate how to use the API. The Cloudron Dashboard Domain and the API Token are variable fields.
You can export them in your shell as follows:
export CLOUDRON_DOMAIN=my.domain.com
export CLOUDRON_TOKEN=your_token_here
To list the domains using cURL and the Authorization header:
curl -H 'ContentType: application/json' -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/domains
Alternately, to use the query parameter:
curl -H 'ContentType: application/json' "https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN"
Authorization
<!-- Redoc-Inject: <security-definitions> -->
Authentication
- HTTP: Bearer Auth
- API Key: query_auth
To use the Bearer Authentication, you must first create an API token.
The API Token can be passed via the Authorization header Bearer <token>:
curl -H 'ContentType: application/json' -H 'Authorization: Bearer $CLOUDRON_TOKEN' https://$CLOUDRON_DOMAIN/api/v1/domains
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
To use the Query Parameter Authentication, you must first create an API token.
The API Token can be passed via the access_token query parameter:
curl -H 'ContentType: application/json' 'https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN'
Security Scheme Type: | apiKey |
|---|---|
Query parameter name: | access_token |
Contact
License
Apache 2.0