Use the SDK

Use the CloudSigma AI Studio SDK to manage workspace resources from Go or Python applications. After completing this page, you will use a personal access token to list visible workspaces and obtain the workspace ID required for later tasks.

For all scenarios and task guides, see AI Studio SDK.

Prerequisites: Get the SDK

Before starting, go to Download AI Studio SDK to obtain the offline distribution package for your language (Python wheel or Go source module), then install and verify dependencies locally.

1. Configure the regional endpoint and credentials

Select the API endpoint for the region containing your workspace. The endpoint passed to the SDK must include /v5.

Region

API base URL

Manila 2, Philippines (mnl2)

https://genai.mnl2.cloudsigma.com/v5

Johannesburg, South Africa (jhb)

https://genai.jhb.cloudsigma.com/v5

Create a personal access token in Access credentials in the same regional console. The endpoint, token, workspace ID, and resource IDs must belong to the same region. See Endpoints & Authentication for details.

The following example uses Manila 2. The packaged examples and SDK task guides read PRODUCT_API_BASE_URL and PRODUCT_API_KEY:

Shell
export PRODUCT_API_BASE_URL='https://genai.mnl2.cloudsigma.com/v5'
export PRODUCT_API_KEY='<personal-access-token-from-this-region>'

If you already configured CLOUDSIGMA_API_BASE and CLOUDSIGMA_API_KEY using the endpoint guide, reuse them:

Shell
export PRODUCT_API_BASE_URL="$CLOUDSIGMA_API_BASE"
export PRODUCT_API_KEY="$CLOUDSIGMA_API_KEY"

The SDK sends the token in X-API-Key. Pass its original value without a Bearer prefix. When switching regions, switch the endpoint, token, and workspace ID together.

2. List visible workspaces

AI Studio SDK features must be used in a workspace. Before using workflows, knowledge bases, data, agents, or other features, select the target workspace and get its workspace ID.

Python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
result = client.workspaces().list()
for workspace in result.workspaces:
    print(workspace.id, workspace.name)
go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	result, err := client.Workspaces().List(ctx)
	if err != nil {
		panic(err)
	}
	for _, workspace := range result.GetWorkspaces() {
		fmt.Printf("%s\t%s\n", workspace.GetId(), workspace.GetName())
	}
}

Select a target workspace ID from the output and save it as an environment variable:

Shell
export WORKSPACE_ID='<workspace-id>'

3. Call example

This example calls the List workflows feature. Use the connection details and workspace ID from the previous steps to create a workspace client and list the workflows that the current identity can read:

Python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
result = workspace.workflows().list()

print(result.total)
for workflow in result.workflows:
    print(workflow.id, workflow.name, workflow.status)
go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	result, err := workspace.Workflows().List(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(result.GetTotal())
	for _, workflow := range result.GetWorkflows() {
		fmt.Printf("%s\t%s\t%s\n", workflow.GetId(), workflow.GetName(), workflow.GetStatus())
	}
}

On success, the program prints the workflow total followed by each workflow’s ID, name, and status.

If you receive 401, check that the token is complete and has no Bearer prefix. If you receive 404 or HTML content, check that the endpoint matches the workspace region and includes /v5. If the list is empty or you receive 403, confirm that the current account has the required workspace member or role permissions.

Next steps

Last updated on