Backend.AI REST API Reference

GET /acl

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Status Codes:

  • 200 OK – Successful response

GET /config/resource-slots
Status Codes:

  • 200 OK – Successful response

GET /config/resource-slots/details
Query Parameters:

  • sgroup (string) –

Status Codes:

  • 200 OK – Successful response

GET /config/vfolder-types
Status Codes:

  • 200 OK – Successful response

GET /config/docker-registries

Returns the list of all registered docker registries.

Preconditions:

  • Superadmin privilege required.

Status Codes:

  • 200 OK – Successful response

POST /config/get

A raw access API to read key-value pairs from the etcd.

Warning

When reading the keys with prefix=True, it uses a simple string-prefix matching over the flattened keys (with the delimiter “/”). Thus, it may return additional keys that you may not want.

For example, reading “some/key1” will fetch all of the following keys:

some/key1
some/key1/field1
some/key1/field2
some/key12
some/key12/field1
some/key12/field2

To avoid this issue, developers must use dedicated CRUD APIs instead of relying on the etcd raw access APIs whenever possible.

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • key (string, required) –

  • prefix (boolean, required) –

Status Codes:

  • 200 OK – Successful response

POST /config/set

A raw access API to write key-value pairs into the etcd.

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • key (string, required) –

  • value (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /config/delete

A raw access API to delete key-value pairs from the etcd.

Warning

When deleting the keys with prefix=True, it uses a simple string-prefix matching over the flattened keys (with the delimiter “/”). This may result in unexpected deletion of sibling keys.

For example, deleting “some/key1” will DELETE all of the following keys:

some/key1
some/key1/field1
some/key1/field2
some/key12
some/key12/field1
some/key12/field2

To avoid this issue, developers must use dedicated CRUD APIs instead of relying on the etcd raw access APIs whenever possible.

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • key (string, required) –

  • prefix (boolean, required) –

Status Codes:

  • 200 OK – Successful response

GET /events/background-task

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • task_id (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

GET /events/session

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • name (string, required) –

  • ownerAccessKey (string) –

  • sessionId (string:uuid) –

  • group (string, required) –

  • scope (string:enum, required) –

Status Codes:

  • 200 OK – Successful response

GET /auth

Preconditions:

  • User privilege required.

Query Parameters:

  • echo (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth

Preconditions:

  • User privilege required.

Request JSON Object:

  • echo (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /auth/test

Preconditions:

  • User privilege required.

Query Parameters:

  • echo (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/test

Preconditions:

  • User privilege required.

Request JSON Object:

  • echo (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/authorize
Request JSON Object:

  • type (string:enum, required) –

  • domain (string, required) –

  • username (string, required) –

  • password (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /auth/role

Preconditions:

  • User privilege required.

Query Parameters:

  • group (string:uuid) –

Status Codes:

  • 200 OK – Successful response

POST /auth/signup
Request JSON Object:

  • domain (string, required) –

  • email (string, required) –

  • password (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/signout

Preconditions:

  • User privilege required.

Request JSON Object:

  • email (string, required) –

  • password (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/update-password-no-auth

Update user’s password without any authorization to allows users to update passwords that have expired because it’s been too long since a user changed the password.

Request JSON Object:

  • domain (string, required) –

  • username (string, required) –

  • current_password (string, required) –

  • new_password (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/update-password

Preconditions:

  • User privilege required.

Request JSON Object:

  • old_password (string, required) –

  • new_password (string, required) –

  • new_password2 (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /auth/update-full-name

Preconditions:

  • User privilege required.

Request JSON Object:

  • email (string, required) –

  • full_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /auth/ssh-keypair

Preconditions:

  • User privilege required.

Status Codes:

  • 200 OK – Successful response

PATCH /auth/ssh-keypair

Preconditions:

  • User privilege required.

Status Codes:

  • 200 OK – Successful response

POST /auth/ssh-keypair

Preconditions:

  • User privilege required.

Request JSON Object:

  • pubkey (string, required) –

  • privkey (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • name (string, required) –

  • host (string) –

  • usage_mode (string:enum) –

  • permission (string:enum) –

  • unmanaged_path (string) –

  • group (string:uuid) –

  • quota (string) – Size in binary format (e.g. 2KB, 3M, 4GiB)

  • cloneable (boolean, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • all (boolean, required) –

  • group_id –

  • owner_user_email (string:email) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders

Preconditions:

  • Superadmin privilege required.

  • Manager status required: RUNNING

Query Parameters:

  • id (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/{name}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/{name}

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/hosts

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group_id –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/all-hosts

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /folders/_/allowed-types

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /folders/_/all_hosts

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /folders/_/allowed_types

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /folders/_/perf-metric

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • folder_host (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/rename

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • new_name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/update-options

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • cloneable (boolean) –

  • permission (string:enum) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/mkdir

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • path (string, required) –

  • parents (boolean, required) –

  • exist_ok (boolean, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/request-upload

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • path (string, required) –

  • size (integer, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/request-download

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • path (string, required) –

  • archive (boolean, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/move-file

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • src (string, required) –

  • dst (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/rename-file

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • target_path (string, required) –

  • new_name (string, required) –

  • is_dir (boolean, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/{name}/delete-files

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Query Parameters:

  • files (array, required) –

  • recursive (boolean, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/rename_file

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Request JSON Object:

  • target_path (string, required) –

  • new_name (string, required) –

  • is_dir (boolean, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/{name}/delete_files

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Query Parameters:

  • files (array, required) –

  • recursive (boolean, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/{name}/files

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • name (string, required) –

Query Parameters:

  • path (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/invite

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • perm (string:enum, required) –

  • emails[] (string) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/leave

Leave a shared vfolder.

Cannot leave a group vfolder or a vfolder that the requesting user owns.

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • shared_user_uuid (string) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/share

Preconditions:

  • Admin privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • permission (string:enum, required) –

  • emails[] (string) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/{name}/unshare

Unshare a group folder from users.

Preconditions:

  • Admin privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Query Parameters:

  • emails (array, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/{name}/clone

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • name (string, required) –

Request JSON Object:

  • cloneable (boolean, required) –

  • target_name (string, required) –

  • target_host (string) –

  • usage_mode (string:enum) –

  • permission (string:enum) –

Status Codes:

  • 200 OK – Successful response

GET /folders/invitations/list-sent

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /folders/invitations/list_sent

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

POST /folders/invitations/update/{inv_id}

Update sent invitation’s permission. Other fields are not allowed to be updated.

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • inv_id (string, required) –

Request JSON Object:

  • perm (string:enum, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/invitations/list

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

POST /folders/invitations/accept

Accept invitation by invitee.

* `inv_ak` parameter is removed from 19.06 since virtual folder's ownership is
moved from keypair to a user or a group.

:param inv_id: ID of vfolder_invitations row.

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • inv_id (string, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/invitations/delete

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Query Parameters:

  • inv_id (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/shared

List shared vfolders.

Not available for group vfolders.

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • vfolder_id (string:uuid) –

Status Codes:

  • 200 OK – Successful response

POST /folders/_/shared

Update permission for shared vfolders.

If params[‘perm’] is None, remove user’s permission for the vfolder.

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • vfolder (string:uuid, required) –

  • user (string:uuid, required) –

  • perm (string:enum) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/fstab

Return the contents of /etc/fstab file.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • fstab_path (string) –

  • agent_id (string) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/mounts

List all mounted vfolder hosts in vfroot.

All mounted hosts from connected (ALIVE) agents are also gathered. Generally, agents should be configured to have same hosts structure, but newly introduced one may not.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

POST /folders/_/mounts

Mount device into vfolder host.

Mount a device (eg: nfs) located at fs_location into <vfroot>/name in the host machines (manager and all agents). fs_type can be specified by requester, which fallbaks to ‘nfs’.

If scaling_group is specified, try to mount for agents in the scaling group.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • fs_location (string, required) –

  • name (string, required) –

  • fs_type (string, required) –

  • options (string) –

  • scaling_group (string) –

  • fstab_path (string) –

  • edit_fstab (boolean, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /folders/_/mounts

Unmount device from vfolder host.

Unmount a device (eg: nfs) located at <vfroot>/name from the host machines (manager and all agents).

If scaling_group is specified, try to unmount for agents in the scaling group.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: RUNNING

Query Parameters:

  • name (string, required) –

  • scaling_group (string) –

  • fstab_path (string) –

  • edit_fstab (boolean, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/_/change-ownership

Change the ownership of vfolder For now, we only provide changing the ownership of user-folder

Preconditions:

  • Superadmin privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • vfolder (string:uuid, required) –

  • user_email (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/quota

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • folder_host (string, required) –

  • id (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

POST /folders/_/quota

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • folder_host (string, required) –

  • id (string:uuid, required) –

  • input (object, required) – Mapping(String => Any)

Status Codes:

  • 200 OK – Successful response

GET /folders/_/usage

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • folder_host (string, required) –

  • id (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

GET /folders/_/used-bytes

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • folder_host (string, required) –

  • id (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

POST //graphql

Preconditions:

  • User privilege required.

Request JSON Object:

  • query (string, required) –

  • variables (object) – Mapping(String => Any)

  • operation_name (string) –

Status Codes:

  • 200 OK – Successful response

POST //gql

Preconditions:

  • User privilege required.

Request JSON Object:

  • query (string, required) –

  • variables (object) – Mapping(String => Any)

  • operation_name (string) –

Status Codes:

  • 200 OK – Successful response

GET /services

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • name (string) –

Status Codes:

  • 200 OK – Successful response

POST /services

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • name (string, required) –

  • desired_session_count (integer, required) –

  • image (string, required) –

  • arch (string, required) –

  • group (string, required) –

  • domain (string, required) –

  • cluster_size (integer, required) –

  • cluster_mode (string:enum, required) –

  • tag (string) –

  • startup_command (string) –

  • bootstrap_script (string) –

  • callback_url (string:uri) –

  • owner_access_key (string) –

  • open_to_public (boolean, required) –

  • config (object, required) –

  • config.model (string, required) –

  • config.model_version (string) –

  • config.model_mount_destination (string, required) –

  • config.environ (object) – Mapping(String => String)

  • config.scaling_group (string) –

  • config.resources (object) – Mapping(String => Any)

  • config.resource_opts (object) – Mapping(String => Any)

Status Codes:

  • 200 OK – Successful response

GET /services/{service_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /services/{service_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /services/{service_id}/errors

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /services/{service_id}/errors/clear

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /services/{service_id}/scale

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Request JSON Object:

  • to (integer, required) –

Status Codes:

  • 200 OK – Successful response

POST /services/{service_id}/sync

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Status Codes:

  • 200 OK – Successful response

PUT /services/{service_id}/routings/{route_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

  • route_id (string, required) –

Request JSON Object:

  • traffic_ratio (integer, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /services/{service_id}/routings/{route_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

  • route_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /services/{service_id}/token

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • service_id (string, required) –

Request JSON Object:

  • duration (string) – Human-readable time duration representation (e.g. 2y, 3d, 4m, 5h, 6s, …)

  • valid_until (integer) –

Status Codes:

  • 200 OK – Successful response

POST /session

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • name (string, required) –

  • image (string, required) –

  • arch (string, required) –

  • type (string:enum, required) –

  • group (string, required) –

  • domain (string, required) –

  • cluster_size (integer, required) –

  • cluster_mode (string:enum, required) –

  • config (object, required) – Mapping(String => Any)

  • tag (string) –

  • enqueueOnly (boolean, required) –

  • maxWaitSeconds (integer, required) –

  • starts_at (string) –

  • reuseIfExists (boolean, required) –

  • startupCommand (string) –

  • bootstrap_script (string) –

  • dependencies[] (string:uuid) –

  • callback_url (string:uri) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /session/_/create

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • name (string, required) –

  • image (string, required) –

  • arch (string, required) –

  • type (string:enum, required) –

  • group (string, required) –

  • domain (string, required) –

  • cluster_size (integer, required) –

  • cluster_mode (string:enum, required) –

  • config (object, required) – Mapping(String => Any)

  • tag (string) –

  • enqueueOnly (boolean, required) –

  • maxWaitSeconds (integer, required) –

  • starts_at (string) –

  • reuseIfExists (boolean, required) –

  • startupCommand (string) –

  • bootstrap_script (string) –

  • dependencies[] (string:uuid) –

  • callback_url (string:uri) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /session/_/create-from-template

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • template_id (string:uuid) –

  • name (string) –

  • image (string, required) –

  • arch (string) –

  • type (string:enum) –

  • group (string, required) –

  • domain (string, required) –

  • cluster_size (integer, required) –

  • cluster_mode (string:enum, required) –

  • config (object, required) – Mapping(String => Any)

  • tag (string, required) –

  • enqueueOnly (boolean, required) –

  • maxWaitSeconds (integer, required) –

  • starts_at (string) –

  • reuseIfExists (boolean, required) –

  • startupCommand (string, required) –

  • bootstrap_script (string, required) –

  • dependencies[] (string:uuid) –

  • callback_url (string:uri, required) –

  • owner_access_key (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/_/create-cluster

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • clientSessionToken (string, required) –

  • template_id (string:uuid) –

  • type (string:enum, required) –

  • group (string, required) –

  • domain (string, required) –

  • scaling_group (string) –

  • tag (string) –

  • enqueueOnly (boolean, required) –

  • maxWaitSeconds (integer, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

GET /session/_/match

A quick session-ID matcher API for use with auto-completion in CLI.

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/_/sync-agent-registry

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • agent (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

PATCH /session/{session_name}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Request JSON Object:

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

DELETE /session/{session_name}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • forced (boolean, required) –

  • recursive (boolean, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

HEAD /session/_/logs

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • session_name (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/_/logs

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • session_name (string:uuid, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/direct-access-info

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/logs

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/rename

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • session_name (string, required) –

Request JSON Object:

  • name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/interrupt

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/complete

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/shutdown-service

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Request JSON Object:

  • service_name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/upload

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/download

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • files (array, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/download_single

Download a single file from the scratch root. Only for small files.

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • file (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/files

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/start-service

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Request JSON Object:

  • login_session_token (string) –

  • app (string, required) –

  • port (integer) –

  • envs (string) –

  • arguments (string) –

Status Codes:

  • 200 OK – Successful response

POST /session/{session_name}/commit

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • session_name (string, required) –

Request JSON Object:

  • login_session_token (string) –

  • filename (string) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/commit

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • session_name (string, required) –

Query Parameters:

  • login_session_token (string) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/abusing-report

Preconditions:

  • User privilege required.

  • Manager status required: RUNNING

Parameters:

  • session_name (string, required) –

Query Parameters:

  • login_session_token (string) –

Status Codes:

  • 200 OK – Successful response

GET /session/{session_name}/dependency-graph

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /stream/session/{session_name}/pty

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /stream/session/{session_name}/execute

WebSocket-version of gateway.kernel.execute().

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /stream/session/{session_name}/apps

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /stream/session/{session_name}/httpproxy

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • app (string, required) –

  • port (integer) –

  • envs (string) –

  • arguments (string) –

Status Codes:

  • 200 OK – Successful response

GET /stream/session/{session_name}/tcpproxy

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • session_name (string, required) –

Query Parameters:

  • app (string, required) –

  • port (integer) –

  • envs (string) –

  • arguments (string) –

Status Codes:

  • 200 OK – Successful response

GET /manager/status
Status Codes:

  • 200 OK – Successful response

PUT /manager/status

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • status (string:enum, required) –

  • force_kill (boolean, required) –

Status Codes:

  • 200 OK – Successful response

GET /manager/announcement
Status Codes:

  • 200 OK – Successful response

POST /manager/announcement

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • enabled (boolean, required) –

  • message (string) –

Status Codes:

  • 200 OK – Successful response

POST /manager/scheduler/operation

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • op (string:enum, required) –

  • args (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /manager/scheduler/trigger

Preconditions:

  • Superadmin privilege required.

Request JSON Object:

  • event (string:enum, required) –

Status Codes:

  • 200 OK – Successful response

GET /manager/scheduler/status

Preconditions:

  • Superadmin privilege required.

Status Codes:

  • 200 OK – Successful response

GET /resource/presets

Returns the list of all resource presets.

Preconditions:

  • User privilege required.

Status Codes:

  • 200 OK – Successful response

POST /resource/check-presets

Returns the list of all resource presets in the current scaling group, with additional information including allocatability of each preset, amount of total remaining resources, and the current keypair resource limits.

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • scaling_group (string) –

  • group (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /resource/recalculate-usage

Update keypair_resource_usages in redis and agents.c.occupied_slots.

Those two values are sometimes out of sync. In that case, calling this API re-calculates the values for running containers and updates them in DB.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /resource/usage/month

Return usage statistics of terminated containers for a specified month. The date/time comparison is done using the configured timezone.

Parameters:

  • group_ids – If not None, query containers only in those groups.

  • month – The year-month to query usage statistics. ex) “202006” to query for Jun 2020

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group_ids (array) –

  • month (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /resource/usage/period

Return usage statistics of terminated containers belonged to the given group for a specified period in dates. The date/time comparison is done using the configured timezone.

Parameters:

  • group_id – If not None, query containers only in the group.

  • str (end_date) – “yyyymmdd” format.

  • str – “yyyymmdd” format.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group_id (string) –

  • start_date (string, required) –

  • end_date (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /resource/stats/user/month

Return time-binned (15 min) stats for terminated user sessions over last 30 days.

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /resource/stats/admin/month

Return time-binned (15 min) stats for all terminated sessions over last 30 days.

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

GET /resource/watcher

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • agent_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /resource/watcher/agent/start

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • agent_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /resource/watcher/agent/stop

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • agent_id (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /resource/watcher/agent/restart

Preconditions:

  • Superadmin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • agent_id (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /scaling-groups

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group (required) –

Status Codes:

  • 200 OK – Successful response

GET /scaling-groups/{scaling_group}/wsproxy-version

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • scaling_group (string, required) –

Query Parameters:

  • group (required) –

Status Codes:

  • 200 OK – Successful response

POST /template/cluster

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • group (string, required) –

  • domain (string, required) –

  • owner_access_key (string) –

  • payload (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /template/cluster

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • all (boolean, required) –

  • group_id –

Status Codes:

  • 200 OK – Successful response

GET /template/cluster/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Query Parameters:

  • format (string:enum) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

PUT /template/cluster/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Request JSON Object:

  • payload (string, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

DELETE /template/cluster/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Query Parameters:

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /template/session

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • group (string, required) –

  • domain (string, required) –

  • owner_access_key (string) –

  • payload (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /template/session

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • all (boolean, required) –

  • group_id –

Status Codes:

  • 200 OK – Successful response

GET /template/session/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Query Parameters:

  • format (string:enum) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

PUT /template/session/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Request JSON Object:

  • group (string, required) –

  • domain (string, required) –

  • payload (string, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

DELETE /template/session/{template_id}

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • template_id (string, required) –

Query Parameters:

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

GET /image/import

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

POST /image/import

Import a docker image and convert it to a Backend.AI-compatible one, by automatically installing a few packages and adding image labels.

Currently we only support auto-conversion of Python-based kernels (e.g., NGC images) which has its own Python version installed.

Internally, it launches a temporary kernel in an arbitrary agent within the client’s domain, the “default” group, and the “default” scaling group. (The client may change the group and scaling group using launchOptions. If the client is a super-admin, it uses the “default” domain.)

This temporary kernel occupies only 1 CPU core and 1 GiB memory. The kernel concurrency limit is not applied here, but we choose an agent based on their resource availability. The owner of this kernel is always the client that makes the API request.

This API returns immediately after launching the temporary kernel. The client may check the progress of the import task using session logs.

Preconditions:

  • Admin privilege required.

  • Manager status required: RUNNING

Request JSON Object:

  • src (string, required) –

  • target (string, required) –

  • architecture (string, required) –

  • launchOptions (object, required) –

  • launchOptions.scalingGroup (string, required) –

  • launchOptions.group (string, required) –

  • brand (string, required) –

  • baseDistro (string:enum, required) –

  • minCPU (integer, required) –

  • minMemory (string, required) – Size in binary format (e.g. 2KB, 3M, 4GiB)

  • preferredSharedMemory (string, required) – Size in binary format (e.g. 2KB, 3M, 4GiB)

  • supportedAccelerators[] (string) –

  • runtimeType (string:enum, required) –

  • runtimePath (string, required) – POSIX path

  • CPUCountEnvs[] (string) –

  • servicePorts[] (object) –

  • servicePorts[].name (string, required) –

  • servicePorts[].protocol (string:enum, required) –

  • servicePorts[].ports[] (integer) –

Status Codes:

  • 200 OK – Successful response

POST /user-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

GET /user-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • path (string) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

PATCH /user-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

DELETE /user-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • path (string, required) –

  • owner_access_key (string) –

Status Codes:

  • 200 OK – Successful response

POST /user-config/bootstrap-script

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • script (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /user-config/bootstrap-script

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Status Codes:

  • 200 OK – Successful response

POST /domain-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • domain (string, required) –

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /domain-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • domain (string, required) –

  • path (string) –

Status Codes:

  • 200 OK – Successful response

PATCH /domain-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • domain (string, required) –

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /domain-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • domain (string, required) –

  • path (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /group-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • group (string:uuid) –

  • domain (string) –

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

Status Codes:

  • 200 OK – Successful response

GET /group-config/dotfiles

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group (required) –

  • domain (string) –

  • path (string) –

Status Codes:

  • 200 OK – Successful response

PATCH /group-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • group (string:uuid) –

  • domain (string) –

  • data (string, required) –

  • path (string, required) –

  • permission (string, required) –

Status Codes:

  • 200 OK – Successful response

DELETE /group-config/dotfiles

Preconditions:

  • Admin privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • group (required) –

  • domain (string) –

  • path (string, required) –

Status Codes:

  • 200 OK – Successful response

POST /logs/error

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Request JSON Object:

  • severity (string:enum, required) –

  • source (string, required) –

  • message (string, required) –

  • context_lang (string, required) –

  • context_env (string, required) – JSON string

  • request_url (string) –

  • request_status (integer) –

  • traceback (string) –

Status Codes:

  • 200 OK – Successful response

GET /logs/error

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Query Parameters:

  • mark_read (boolean, required) –

  • page_size (integer, required) –

  • page_no (integer, required) –

Status Codes:

  • 200 OK – Successful response

POST /logs/error/{log_id}/clear

Preconditions:

  • User privilege required.

  • Manager status required: FROZEN

Parameters:

  • log_id (string, required) –

Status Codes:

  • 200 OK – Successful response