Wallaroo MLOps API Essentials Guide: Workspace Management

How to use the Wallaroo API for Workspace Management

Workspace Naming Requirements

Workspace names map onto Kubernetes objects, and must be DNS compliant. Workspace names must be ASCII alpha-numeric characters or dash (-) only. . and _ are not allowed.

Workspaces

Workspaces are used to segment groups of models and pipelines into separate environments. This allows different users to either manage or have access to each workspace, controlling the models and pipelines assigned to the workspace.

List User Workspaces

  • Endpoint: /v1/api/workspaces/list

List the workspaces for specified users.

List User Workspaces Parameters

FieldTypeDescription
user_idsList[Keycloak user ids] (Optional)An array of Keycloak user ids, typically in UUID format.

If an empty set {} is submitted as a parameter, then the workspaces for users are returned.

List User Workspaces Returns

Field TypeDescription
workspaces List[workspaces]A List of workspaces for the specified users.
 idIntegerThe numerical ID of the workspace.
 nameStringThe assigned name of the workspace.
 create_atStringThe DateTime the workspace was created.
 create_byStringThe Keycloak ID of the user who created the workspace.
 archivedBooleanWhether the workspace is archived or not.
 modelsList[Integer]The model ids uploaded to the workspace.
 pipelinesList[Integer]The pipeline ids built within the workspace.

List User Workspaces Examples

In these example, the workspaces for all users will be displayed.

List all workspaces via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/list"

data = {
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response

    {'workspaces': [{'id': 1,
       'name': 'john.hummel@wallaroo.ai - Default Workspace',
       'created_at': '2023-11-20T16:05:06.323911+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [],
       'pipelines': []},
      {'id': 5,
       'name': 'mobilenetworkspacetest',
       'created_at': '2023-11-20T16:05:48.271364+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [1, 2],
       'pipelines': [1]},
      {'id': 6,
       'name': 'edge-observability-assaysbaseline-examples',
       'created_at': '2023-11-20T16:09:31.950532+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [3],
       'pipelines': [4]},
      {'id': 7,
       'name': 'edge-observability-houseprice-demo',
       'created_at': '2023-11-20T17:36:07.131292+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [4, 5, 6, 7, 8, 9, 12],
       'pipelines': [7, 14, 16]},
      {'id': 8,
       'name': 'clip-demo',
       'created_at': '2023-11-20T18:57:53.667873+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [10, 11],
       'pipelines': [19]},
      {'id': 9,
       'name': 'onnx-tutorial',
       'created_at': '2023-11-22T16:24:47.786643+00:00',
       'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'archived': False,
       'models': [13],
       'pipelines': [22]}]}

List all workspaces via curl.

curl {wl.api_endpoint}/v1/api/workspaces/list \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{}}'

{
  "workspaces": [
    {
      "id": 1,
      "name": "john.hummel@wallaroo.ai - Default Workspace",
      "created_at": "2023-11-20T16:05:06.323911+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [],
      "pipelines": []
    },
    {
      "id": 5,
      "name": "mobilenetworkspacetest",
      "created_at": "2023-11-20T16:05:48.271364+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [1, 2],
      "pipelines": [1]
    },
    {
      "id": 6,
      "name": "edge-observability-assaysbaseline-examples",
      "created_at": "2023-11-20T16:09:31.950532+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [3],
      "pipelines": [4]
    },
    {
      "id": 7,
      "name": "edge-observability-houseprice-demo",
      "created_at": "2023-11-20T17:36:07.131292+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [4, 5, 6, 7, 8, 9, 12],
      "pipelines": [7, 14, 16]
    },
    {
      "id": 8,
      "name": "clip-demo",
      "created_at": "2023-11-20T18:57:53.667873+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [10, 11],
      "pipelines": [19]
    },
    {
      "id": 9,
      "name": "onnx-tutorial",
      "created_at": "2023-11-22T16:24:47.786643+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [13],
      "pipelines": [22]
    }
  ]
}

Create Workspace

  • Endpoint: /v1/api/workspaces/create

A new workspace will be created in the Wallaroo instance. Upon creating, the workspace owner will be assigned as the user making the MLOps API request.

Create Workspace Parameters

FieldTypeDescription
workspace_nameString (REQUIRED)The name of the new workspace with the following requirements:
  • Must be unique.
    • DNS compliant with only lowercase characters.

Create Workspace Returns

FieldTypeDescription
workspace_idIntegerThe ID of the new workspace.

Create Workspace Examples

In this example, workspaces named testapiworkspace-requests and testapiworkspace-curl will be created.

After the request is complete, the List Workspaces command will be issued to demonstrate the new workspace has been created.

Create workspace via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/create"

data = {
  "workspace_name": "testapiworkspace-requests"
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
display(response)

# Stored for future examples
example_workspace_id = response['workspace_id']

{'workspace_id': 10}

## List workspaces

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/list"

data = {
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response

{'workspaces': [{'id': 1,
   'name': 'john.hummel@wallaroo.ai - Default Workspace',
   'created_at': '2023-11-20T16:05:06.323911+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [],
   'pipelines': []},
  {'id': 5,
   'name': 'mobilenetworkspacetest',
   'created_at': '2023-11-20T16:05:48.271364+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [1, 2],
   'pipelines': [1]},
  {'id': 6,
   'name': 'edge-observability-assaysbaseline-examples',
   'created_at': '2023-11-20T16:09:31.950532+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [3],
   'pipelines': [4]},
  {'id': 7,
   'name': 'edge-observability-houseprice-demo',
   'created_at': '2023-11-20T17:36:07.131292+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [4, 5, 6, 7, 8, 9, 12],
   'pipelines': [7, 14, 16]},
  {'id': 8,
   'name': 'clip-demo',
   'created_at': '2023-11-20T18:57:53.667873+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [10, 11],
   'pipelines': [19]},
  {'id': 9,
   'name': 'onnx-tutorial',
   'created_at': '2023-11-22T16:24:47.786643+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [13],
   'pipelines': [22]},
  {'id': 10,
   'name': 'testapiworkspace-requests',
   'created_at': '2023-11-28T21:16:09.891951+00:00',
   'created_by': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
   'archived': False,
   'models': [],
   'pipelines': []}]}

Create workspace via curl.

curl {wl.api_endpoint}/v1/api/workspaces/create \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"workspace_name": "testapiworkspace-curl"}}'

{"workspace_id":12}

curl {wl.api_endpoint}/v1/api/workspaces/list \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{}}'

{
  "workspaces": [
    {
      "id": 1,
      "name": "john.hummel@wallaroo.ai - Default Workspace",
      "created_at": "2023-11-20T16:05:06.323911+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [],
      "pipelines": []
    },
    {
      "id": 5,
      "name": "mobilenetworkspacetest",
      "created_at": "2023-11-20T16:05:48.271364+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [1, 2],
      "pipelines": [1]
    },
    {
      "id": 6,
      "name": "edge-observability-assaysbaseline-examples",
      "created_at": "2023-11-20T16:09:31.950532+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [3],
      "pipelines": [4]
    },
    {
      "id": 7,
      "name": "edge-observability-houseprice-demo",
      "created_at": "2023-11-20T17:36:07.131292+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [4, 5, 6, 7, 8, 9, 12],
      "pipelines": [7, 14, 16]
    },
    {
      "id": 8,
      "name": "clip-demo",
      "created_at": "2023-11-20T18:57:53.667873+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [10, 11],
      "pipelines": [19]
    },
    {
      "id": 9,
      "name": "onnx-tutorial",
      "created_at": "2023-11-22T16:24:47.786643+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [13],
      "pipelines": [22]
    },
    {
      "id": 10,
      "name": "testapiworkspace-requests",
      "created_at": "2023-11-28T21:16:09.891951+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [],
      "pipelines": []
    },
    {
      "id": 12,
      "name": "testapiworkspace-curl",
      "created_at": "2023-11-28T21:19:46.829351+00:00",
      "created_by": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "archived": false,
      "models": [],
      "pipelines": []
    }
  ]
}

Add User to Workspace

  • Endpoint: /v1/api/workspaces/add_user

Existing users of the Wallaroo instance can be added to an existing workspace.

Add User to Workspace Parameters

FieldTypeDescription
emailString (REQUIRED)The email address of the user to add to the workspace. This user must already exist in the Wallaroo instance.
workspace_idInteger (REQUIRED): The numerical id of the workspace.

Add User to Workspace Returns

Returns {} on a successful request.

Add User to Workspace Examples

The following example adds the user “john.hansarick@wallaroo.ai” to the workspace created in the previous step.

Add existing user to existing workspace via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/add_user"

data = {
  "email": "john.hansarick@wallaroo.ai",
  "workspace_id": example_workspace_id
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response

{}

Add existing user to existing workspace via curl.

curl {wl.api_endpoint}/v1/api/workspaces/add_user \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"email": "john.hansarick@wallaroo.ai","workspace_id": {example_workspace_id}}}'

{}

List Users in a Workspace

  • Endpoint: /v1/api/workspaces/list_users

Lists the users who are either owners or collaborators of a workspace.

List Users in a Workspace Parameters

FieldTypeDescription
workspace_id*Integer (REQUIRED)The id of the workspace.

List Users in a Workspace Returns

Field TypeDescription
users List[users]The list of users and attributes in the workspace.
 user_idStringThe user’s Keycloak id.
 user_typeStringThe user’s workspace type of OWNER or COLLABORATOR.

List Users in a Workspace Examples

The following examples list all users part a workspace created in a previous request.

List users in a workspace via Requests.

# Retrieve the token 

headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/list_users"

data = {
  "workspace_id": example_workspace_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
response

{
  "users": [
    { "user_id": "12ea09d1-0f49-405e-bed1-27eb6d10fde4", "user_type": "OWNER" },
    {
      "user_id": "57d61aed-3058-4327-9e65-a5d39a9718c0",
      "user_type": "COLLABORATOR"
    }
  ]
}

List users in a workspace via curl.

curl {wl.api_endpoint}/v1/api/workspaces/list_users \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"workspace_id": {example_workspace_id}}}'

{
  "users": [
    { "user_id": "12ea09d1-0f49-405e-bed1-27eb6d10fde4", "user_type": "OWNER" },
    {
      "user_id": "57d61aed-3058-4327-9e65-a5d39a9718c0",
      "user_type": "COLLABORATOR"
    }
  ]
}

Remove User from a Workspace

Removes the user from the given workspace. In this request, either the user’s Keycloak ID is required OR the user’s email address is required.

Remove User from a Workspace Parameters

FieldTypeDescription
workspace_idInteger (Required)The id of the workspace.
user_idString (Optional)The Keycloak ID of the user. If email is not provided, then this parameter is REQUIRED.
emailString (Optional)The user’s email address. If user_id is not provided, then this parameter is REQUIRED.

Remove User from a Workspace Returns

FieldTypeDescription
affected_rowsIntegerThe number of workspaces effected by the change.

Remove User from a Workspace Examples

The following example will remove the user john.hansarick@wallaroo.ai from a workspace created the previous steps. Then the list of users for the workspace is retrieved to verify the change.

Remove existing user from an existing workspace via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/remove_user"

data = {
  "email": "john.hansarick@wallaroo.ai",
  "workspace_id": example_workspace_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
response

{'affected_rows': 1}

# Retrieve the token 

headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/workspaces/list_users"

data = {
  "workspace_id": example_workspace_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
response

{
  "users": [
    { "user_id": "12ea09d1-0f49-405e-bed1-27eb6d10fde4", "user_type": "OWNER" }
  ]
}

Remove existing user from an existing workspace via curl.

curl {wl.api_endpoint}/v1/api/workspaces/remove_user \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"email": "john.hansarick@wallaroo.ai","workspace_id": {example_workspace_id}}}'

{"affected_rows":0}

curl {wl.api_endpoint}/v1/api/workspaces/list_users \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"workspace_id": {example_workspace_id}}}'

{
  "users": [
    { "user_id": "12ea09d1-0f49-405e-bed1-27eb6d10fde4", "user_type": "OWNER" }
  ]
}