Endpoints
HTTP Interface
To use karma.run's RPC interface over HTTP/TLS, send a POST request to port 443.
Alternatively you can use port 80 for plain-text communication. This is useful for local development but not recomended for production instances.
Make sure to set the following headers:
X-Karma-Codec
The transport format you'd like to speak e.g. json.Expect
Must be set to the empty string. *
* This is required because our infrastructure does not allow 100-Continue requests.
Authentication Endpoint
To authenticate with karma.run, logging in is required. The auth endpoint is reachable at the path /auth
.
Authentication workflow
In karma.run, there are two different levels of access:
- Normal users
- Administrators
Normal Users
Normal users access karma.run by logging in through the authentication endpoint. They then have access to the KVM endpoint but none of the administrative ones.
Administrators
Every Karma Instance comes with a default "admin" user, which is undeletable in every karma.run database. Log in with the username "admin" and base64-encoded instance secret as password. They then have access to the KVM endpoint as well as to the administrative endpoints.
/auth
To login, send a POST request containing a struct with two string fields: username and password, validly encoded with your codec o choice (X-Karma-Codec).
POST /auth HTTP/1.1
X-Karma-Codec: json
{
"username": "...",
"password": "..."
}
If authentication fails, the HTTP response will have a non-200 status code and contain an error object. Normally you'll get HTTP status 403 Forbidden if the password doesn't match.
When you authenticate successfully, you receive an HTTP status of 200 OK and a single string (encoded by your codec) as response. This string is your signature. You may now access other endpoints by providing this (base64-encoded) signature as X-Karma-Signature header.
Keeping a session active
The signature you obtain from the auth endpoint is valid for 15 minutes. In order to keep the session active, send a GET request to /auth
periodically (e.g. every 10 minutes) with your current signature set as X-Karma-Signature
header. This will return a new signature that expires 15 minutes after.

KVM Endpoint
The KVM (Karma Virtual Machine) endpoint is the main entrypoint for all common user queries to karma.run, found on path /
.
In order to access this endpoint, you need to log in first. After you've logged in and obtained a valid signature, use it as HTTP header X-Karma-Signature when interacting with the KVM endpoint. Send any expression validly encoded with your codec of choice to have it executed on the KVM.
Path: /
Method: POST
Protocol: HTTP/1.1
Headers:
X-Karma-Signature: pupUry8HQFrFv+zfonCA...RCHUOxdEW+6jcOobo5+s=
X-Karma-Codec: json
Body:
{
"all": {
"tag": "_tag"
}
}
Administrative Endpoints
Once logged-in, database admins have access to the following additional endpoints:
export
This endpoint enables a database admin to create a compressed dump of their database and download it onto their local machine. To do so, send a simple GET request to this endpoint.
Path: /admin/export
Method: GET
Protocol: HTTP/1.1
Headers:
X-Karma-Signature: pupUry8HQFrFv+zfonCA...RCHUOxdEW+6jcOobo5+s=
X-Karma-Codec: json
Response: "upRqDQygpGKXV6WxehJb...fxVNBXTG2H1mT8hYuogM="
import
This endpoint allows a database admin to restore a previously dumped database file. To do so, POST the contents of the file as HTTP request body to this endpoint.
Path: /admin/import
Method: GET
Protocol: HTTP/1.1
Headers:
X-Karma-Signature: pupUry8HQFrFv+zfonCA...RCHUOxdEW+6jcOobo5+s=
X-Karma-Codec: json
Response: <file.gz>
reset
This endpoint resets a running database, effectively deleting all data in it and setting it up from zero. To do this, send a POST request containing as body a validly encoded (by your codec of choice) string representation of the base64-encoding of your new database secret.
Path: /admin/reset
Method: POST
Protocol: HTTP/1.1
Headers:
X-Karma-Signature: pupUry8HQFrFv+zfonCA...RCHUOxdEW+6jcOobo5+s=
X-Karma-Codec: json
Response: "upRqDQygpGKXV6WxehJb...fxVNBXTG2H1mT8hYuogM="