Using curl with Watson examples

The curl utility lets you make HTTP requests from the command line. The utility provides a simple interface for making requests that use GET, POST, and other HTTP methods. It lets you pass request headers, data, and other input, and it can display all of the response headers and data that a call returns. Because curl eliminates the need to write code to exercise REST APIs, IBM Watson® documentation uses curl to demonstrate example calls.

The curl utility is installed by default with recent versions of Apple® macOS® and Microsoft® Windows®.

For more information about installing or refreshing curl on macOS, Windows, or Linux®, see Install curl.
For more information about using curl and its full range of capabilities, see Everything curl.

curl is not recommended for application development.

Using curl for secure communications

To test whether curl is installed on your system, run the following command at a terminal prompt:

curl -V

If the output lists https among the supported protocols and SSL (Secure Sockets Layer) or TLS (Transport Layer Security) among the supported features, you're all set. All IBM Watson Watson services use these features for secure connections between the client and server. A connection request is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If these protocols are not listed, you can use a self-signed certificate for your requests. But to make a successful connection, you need to disable SSL verification by including the --insecure or -k option with the request.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if necessary and only with data that is not confidential, and take steps to enable SSL as soon as possible.

Example curl requests

The following examples demonstrate the use of curl. The requests use the Speech to Text service to transcribe audio to text with both IBM Cloud® and IBM Cloud Pak® for Data.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary ./audio-file.flac \
"{url}/v1/recognize"

IBM Cloud Pak for Data

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary ./audio-file.flac \
"{url}/v1/recognize"

In both examples, you replace {url} with the URL for your service instance. Authentication differs between IBM Cloud®, where you replace {apikey} with the API key for your service instance, and IBM Cloud Pak® for Data, where you replace {token} with an access token that you generate for your service instance. For more information about authenticating to the service on either platform, see Authenticating to Watson services.

When submitting requests based on examples in the documentation, omit the braces ({ }) from the examples; they indicate variable values that you must replace with actual values. Windows users must replace the backslash (\) at the end of each line with a caret (^). Make sure there are no trailing spaces after a \ or ^.