Skill sets

Use skills and projects through the skill sets API endpoints.

Base path: {api_endpoint}/v1

To get the operation endpoint, concatenate the base path with the path that is described in each of the following operations.

GET /skillsets/

Get a list of the skill sets available in your tenant.

Request headers

The following table defines the headers that this method supports.

Header Required Accepted values Description
Authorization Yes Bearer <token> A JSON Web Token (JWT) that authenticates your request. Replace <token> with the JWT you get when following the procedure at Generating a JWT token.

Path Parameters

Configure the following parameters in the path level of the API.

name required data type description
tenant_id yes string The unique identifier for the tenant that has the skill set.

Responses

If the API call is successful, it returns a OK response with the 200 code, and a list of skill sets with the following data in the response body:

Property Description
name The name of the skill set.
skillset_id The unique identifier of the skill set.
url The URL of the skill set. It is also the endpoint for the GET /skillsets/{skillset_id} operation.

Example

Request:

curl -X GET \
  '{api_endpoint}/v1/skillsets' \
  -H 'Authorization: Bearer {token}.'

Response:

{
  "skillsets": [
        {
            "name": "Team Skills4567009",
            "skillset_id": "00000000-0000-0000-0000-000000000000",
            "url": "https://api.example.watson-orchestrate.ibm.com/instances/00000000-0000-0000-0000-000000000000/v1/skillsets/00000000-0000-0000-0000-000000000000"
        },
  ]
}

GET /skillsets/{skillset_id}

Get all the skills that are available in one specific skill set.

Request headers

The following table defines the headers that this method supports.

Header Required Accepted values Description
Authorization Yes Bearer <token> A JSON Web Token (JWT) that authenticates your request. Replace <token> with the JWT you get when following the procedure at Generating a JWT token.

Path Parameters

Configure the following parameters in the path level of the API.

name required data type description
tenant_id yes string The unique identifier for the tenant that has the skill set.
skillset_id yes string The unique identifier for the specific skill set.
You get the skillset_id in the skillset_id property of the /instances/{tenant_id}/v1/skillsets operation response.

Responses

If the API call is successful, it returns a OK response with the 200 code, and a list of skills with the following data in the response body:

Property Description
description The description of the skill.
name The unique identifier of the skill.
openapi The endpoint for the GET /skillsets/{skillset_id}/skills/{skill_id}/openapi operation.

Example

Request:

curl -X GET \
  '{api_endpoint}/v1/skillsets/{skillset_id}' \
  -H 'Authorization: Bearer {token}'

Response:

{
  "skills": [
    {
      "description": "",
      "name": "InvoiceProcessing-submitContractorInvoice__submitContractorInvoice",
      "openapi": "https://api.example.watson-orchestrate.ibm.com/instances/00000000-0000-0000-0000-000000000000/v1/skillsets/00000000-0000-0000-0000-000000000000/skills/InvoiceProcessing-submitContractorInvoice__latest__submitContractorInvoice/openapi"
    }
  ]
}

GET /skillsets/{skillset_id}/skills/{skill_id}/openapi

Get an OpenAPI specification of a skill in JSON format.

Request headers

The following table defines the headers that this method supports.

Header Required Accepted values Description
Authorization Yes Bearer <token> A JSON Web Token (JWT) that authenticates your request. Replace <token> with the JWT you get when following the procedure at Generating a JWT token.

Path Parameters

Configure the following parameters in the path level of the API.

name required data type description
tenant_id yes string The unique identifier for the tenant that has the skill set.
skillset_id yes string The unique identifier for the specific skill set.
You get the skillset_id in the skillset_id property of the /instances/{tenant_id}/v1/skillsets operation response.
skill_id yes string The unique identifier for the specific skill.
You get the skill_id in the name property of the /instances/{tenant_id}/v1/skillsets operation response.

Responses

If the API call occurs successfully, an OK response with the 200 code is returned. It returns the OpenAPI specification with the following data in the response body:

Property Decription
openapi The version of the OpenAPI used to create the skill.
info Your app data on watsonx Orchestrate.
servers The base endpoint for the app on watsonx Orchestrate.
security The security method that you use to authenticate in the skill.
paths Information about the skill. Here you find:
  • The skill operation path
  • The method that must be used to use the skill
  • The skill parameters
  • The skill request body
  • The skill response body
components Used to configure reusable objects such as parameters, requestBody, responses, securitySchemes.

Example

Request:

curl -X GET \
  '{api_endpoint}/v1/skillsets/{skillset_id}/skills/{skill_id}/openapi' \
  -H 'Authorization: Bearer {token}'

Response:

{
    "openapi": "3.0.1",
    "info": {
        "title": "Test130801-WF130801",
        "description": "",
        "version": "latest",
        "x-ibm-application-id": "uab9ca87f8abb0575289d3418af2ef8f512",
        "x-ibm-application-name": "Test130801",
        "x-ibm-skill-type": "imported",
        "x-ibm-skill-subtype": "wo-identity",
        "x-ibm-comm-timeouts": {
            "connectTimeout": 10000,
            "responseTimeout": 30000
        }
    },
    "servers": [
        {
            "url": "https://api.example.watson-orchestrate.ibm.com/instances/00000000-0000-0000-0000-000000000000/v1/skills/00000000-0000-0000-0000-000000000000/Test130801-WF130801__latest__WF130801"
        }
    ],
    "security": [
        {
            "WO-JWT": [
            ]
        }
    ],
    "paths": {
        "/WF130801": {
            "post": {
                "summary": "WF130801",
                "description": "",
                "operationId": "WF130801",
                "parameters": [
                    {
                        "name": "callbackUrl",
                        "in": "header",
                        "description": "The location where the response will be sent",
                        "required": false,
          }
        ]
      }
    }
  }
}

POST/PUT/GET/DELETE/PATCH /skills/{skillset_id}/{skill_id}/{skill_operation_path}

Use your skills and projects.

The method that you use depends on each skill. To know the method to use for your skill, open the openAPI file that was returned for the GET /skillsets/{skillset_id}/skills/{skill_id}/openapi operation, go to the paths property, and see the method used under the skill operation path.

Note: Depending on your skill you might need extra parameter and requestBody settings, you get this information in your skill's OpenAPI. The response of this operation also varies depending on the skill used.

Request headers

The following table defines the headers that this method supports.

Header Required Accepted values Description
Authorization Yes Bearer <token> A JSON Web Token (JWT) that authenticates your request. Replace <token> with the JWT you get when following the procedure at Generating a JWT token.

Path Parameters

name type data type description
skillset_id required string ID of the skillset.
You get the skillset_id in the skillset_id property of the /instances/{tenant_id}/v1/skillsets operation response.
skill_id required string ID of the skill.
You get the skill_id in the name property of the /instances/{tenant_id}/v1/skillsets operation response.
skill_operation_path required string The operation path of the skill. You find it in the path property that was returned by the previous operation.

Error handling

Using the API methods can return one of the following error codes.

http code content-type response
400
Bad request.
404
The requested resources were not found.
500
Unexpected server error.