Building OpenAPI specifications for skills

IBM watsonx Orchestrate platform gives you the capability to import skills in the form of OpenAPI specifications (OAS).

You can either use watsonx Orchestrate to create these specifications or any other OAS editors.

To create OAS within watsonx Orchestrate, see:

• Using OpenAPI builder

  With the OpenAPI builder, you can:

  • Use AI to generate an OpenAPI specification from a documentation web page
  • View and edit an existing OpenAPI specification
  • Create an OpenAPI specification from scratch

See the following sections for details on how to create OpenAPI specifications that you can import as skills.

• Creating OpenAPI Specification
  • Configuring the OpenAPI version
  • Configuring the app
  • Configuring the API server
  • Configuring skills
  • Configuring the API security scheme
  • Optional: Configuring callback for asynchronous skills
  • Optional: Configuring reusable objects

Some OpenAPI specification properties can change the method in which the user interact with watsonx Orchestrate. See how to configure these properties to give the best user experience:

• Enhancing skills with OpenAPI specification properties
  • Configuring input and output data types
  • Uploading files as input

You can use IBM properties in your OpenAPI specification to enhance your watsonx Orchestrate skills by adding more details and clarity. See the following sections to learn more:

• Understanding x-ibm properties
  • Configuring an importable OpenAPI specification
  • Configuring OpenAPI specification subtype
  • Configuring app ID
  • Configuring the app name
  • Adding an icon to the app
  • Forcing custom endpoint configuration
  • Configuring headers
  • Hiding skills from the skill catalog
  • Configuring a skill as conversational
  • Training skills with phrases
  • Wrapping schemas to use skills on automations
  • Mapping inputs from phrases
  • Configuring output messages
  • Filling string fields automatically for Assistant skills
  • Disabling inputs
  • Configuring input and output names
  • Configuring the error message response
  • Configuring inputs and outputs as multiline
  • Ordering inputs and outputs
  • Hiding inputs and outputs
  • Promoting fields to the main section
  • Sequencing skills
  • Configuring dynamic values for list of options
  • Showing input fields dynamically
  • Configuring output list pagination