Getting started with the API

Get started with the watsonx Orchestrate API.

Authenticating to the API

To use the watsonx Orchestrate API, you must first authenticate to the server. Each watsonx Orchestrate offering uses a different method to authenticate to the server.

1. Generating an API key

For all the offerings, the first step is to generate an API key:

2. Generating the authentication token

After you get your API key, use it to generate an authentication token.

IBM Cloud
IBM Cloud uses the IAM Access Token to authenticate to watsonx Orchestrate. You must generate it using the API key.
AWS
The AWS offering uses a JSON Web Token(JWT) to authenticate you in the watsonx Orchestrate API. You must generate it using the API key.
On-premises
The on-premises offering uses the Zen API key that you obtained in the previous step. You don't need to obtain another token.

Calling the server's endpoints

After you get the authentication tokens, you can use them to call the API endpoints.

To get the API endpoints, see Getting the API endpoints.

These are a few examples of how to call the API endpoints with the proper authorization tokens:

IBM Cloud

curl

curl -X GET "https://api.REGION_CODE.watson.cloud.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: Bearer MY_IAM_TOKEN" \
     -H "Accept: application/json"

Python

import http.client

region_code = "REGION_CODE"
iam_token = "MY_IAM_TOKEN"
instance_id = "MY_INSTANCE_ID"

conn = http.client.HTTPSConnection(f"api.{region_code}.watson-orchestrate.ibm.com")

headers = {
    'Authorization': f"Bearer {iam_token}",\
    'accept': "application/json"
}

conn.request("GET", f"/instances/{instance_id}/v1/orchestrate/digital-employees/allskills", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

AWS

curl

curl -X GET "https://api.REGION_CODE.watson-orchestrate.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: Bearer MY_JWT_TOKEN" \
     -H "Accept: application/json"

Python

import http.client

region_code = "REGION_CODE"
jwt_token = "MY_JWT_TOKEN"
instance_id = "MY_INSTANCE_ID"

conn = http.client.HTTPSConnection(f"{region_code}.dl.watson-orchestrate.ibm.com")

headers = {
    'Authorization': f"Bearer {jwt_token}",\
    'accept': "application/json"
}

conn.request("GET", f"/instances/{instance_id}/v1/orchestrate/digital-employees/allskills", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

On-premises

curl

curl -X GET "https://MYHOST:PORT//orchestrate/MY_NAMESPACE/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: ZenApiKey MY_ZEN_API_KEY" \
     -H "Accept: application/json"

Python

import http.client
import base64


region_code = f"https://MYHOST:PORT/"
api_key = "MY_API_KEY"
username = "MY_USER_NAME"
api_key_bytes = f"{username}:{api_key}".encode(encoding="utf-8")
zen_api_key = base64.encodebytes(api_key_bytes).decode(encoding="utf-8")
namespace = "MY_NAMESPACE"
instance_id = "MY_INSTANCE_ID"
endpoint = "/orchestrate/{namespace}/instances/{instanceid}/v1/orchestrate/digital-employees/allskills/"

conn = http.client.HTTPSConnection(f"{myhost}")

headers = {
    'Authorization': f"ZenApiKey {zen_api_key}",\
    'accept': "application/json"
}

conn.request("GET", endpoint, headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))