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.

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.

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"
  }
}

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="