IBM Cloud Docs
Building custom applications with the API

Building custom applications with the API

Use the Discovery API to build a custom application or component that searches your data.

Service API Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. Whenever a backwards-incompatible API change occurs, a new minor version of the API is released.

Send the version parameter with every API request. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

The current version is 2023-03-31.

Getting your project ID IBM Cloud

This information applies to IBM Cloud only.

To use the API, you must construct the URL to use in your requests. Many of the API methods require the project ID.

  1. From the IBM Cloud Resource list, expand AI/Machine Learning, and then find the service page for your Discovery service instance.

  2. From the Credentials section, copy the URL. You specify this value as the {url} in your API requests.

  3. While you're on this page, copy the API key. You specify this value as the {apikey}.

  4. Open your project in Discovery, and then go to the Integrate and deploy > API Information page.

  5. Copy the project ID. You specify this value as the {project_id}.

    If you're using a Content Mining project, stay on the Share Link page. From the web browser's location field, copy the URL starting with /projects. For example, projects/a8ce5fed-7f33-4405-aa4b-88ffba322712/deploy/beta. The ID that is specified after the /projects/ segment of the URL is your project ID.

  6. Construct a request URL by using the IDs you copied.

    For example, the following request lists the collections in the project:

    curl -X {request_method} -u "apikey:{apikey}" \
"{url}/v2/projects/{project_id}/collections?version=2019-11-29 -k"

To get the {collection_id}, you can use the List collections API method. Alternatively, open the collection in the product user interface, and then copy the collection ID, which is displayed after the /collections/ segment of the page URL, from the web browser location field.

Using the API from Cloud Pak for Data IBM Cloud Pak for Data

This information applies to Discovery for Cloud Pak for Data only.

To use the API, you must construct the URL to use in your requests.

  1. From the IBM Cloud Pak for Data web client main menu, expand Services, and then click Instances.

  2. Find your instance, and then click it to open its summary page.

  3. Scroll to the Access information section of the page, and then copy the URL. You will specify this value as the {url}.

  4. Copy the bearer token also. You will need to pass the token when you make an API call.

  5. From the launched application instance, go to the Integrate and Deploy > API Information page.

  6. Copy the project ID. You will specify this value as the {project_id}.

    If you're using a Content Mining project, stay on the Share Link page. From the web browser's location field, copy the URL starting with /projects. For example, projects/a8ce5fed-7f33-4405-aa4b-88ffba322712/deploy/beta. The ID that is specified after the /projects/ segment of the URL is your project ID.

  7. Construct a request URL by using the IDs you copied.

    For example, the following request lists the collections in the project:

    curl -H "Authorization: Bearer {token}" \
"{url}/v2/projects/{project_id}/collections?version=2019-11-29 -k"

The bearer token that is generated for an administrator can access any instance regardless of the access settings that are configured for the instance.

The bearer token expires after 12 hours. For more information about customizing the length of a session, see Setting the idle session timeout.

Next steps

A developer can make the following enhancements: