Curl Java Node Python

Discovery

API Reference
The IBM Watson Discovery Service API Reference page

Introduction

The IBM Watson™ Discovery Service uses data analysis combined with cognitive intuition in order to take your unstructured data and enrich it so that you can query it to return the information that you need from it.

API Endpoint

https://gateway.watsonplatform.net/discovery/api/v1

npm

npm install watson-developer-cloud

Maven

<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.8.0</version>
</dependency>

Gradle

compile 'com.ibm.watson.developer_cloud:java-sdk:3.8.0'

pip

pip install --upgrade watson-developer-cloud

API explorer

To interact with this REST API, use the Discovery Service API explorer. Use the explorer to test your calls to the API and to view live responses from the server.

Authentication

You authenticate to the Discovery API by providing the user name and password provided in the service credentials for the service instance that you want to use. The API uses Basic Authentication.

After creating an instance of the Discovery service, select Service Credentials from the left navigation for its dashboard to see the username and password that are associated with that instance. For more information, see Service credentials for Watson services.

Applications can also use tokens to establish authenticated communications with Watson services without embedding their service credentials in every call. You write an authentication proxy in Bluemix to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Tokens for authentication.

In these methods, replace {username} and {password} with your credentials.

var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version: 'v1',
  version_date: '2017-07-19'
});
Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username='{username}',
  password='{password}',
  version='2017-07-19'
)

Versioning

API requests require a version parameter that takes the a date in the format version=YYYY-MM-DD. Send the version parameter with every API request. When we change the API in a backwards-incompatible way, we release a new version date. To take advantage of the changes in a new version, change the value of the version parameter to the new date. If you're not ready to update to that version, don’t change your version date.

The current version is 2017-07-19.

Environments

Manage an environment to store your documents.

Create an environment

Creates an environment for the service instance.

Note: You can create only one environment per service instance. Attempting to create another environment for the same service instance results in an error.

POST /v1/environments

Request

Name Description
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
body body string A JSON object that defines a name, description, and size for the new environment.

The following table shows the available values for size. See the Discovery service home page for additional information about sizing and pricing. To create a free trial environment, specify the value of size as 0 (zero).

Sizing
Size Attributes
0 (free)
  • 2 GB disk space

  • 1 GB RAM

  • Unlimited enrichments

  • Single search node, therefore no high availability

  • 30-day trial only

1
  • 48 GB disk space

  • 2 GB RAM

  • 4,000 enrichments

2
  • 192 GB disk space

  • 8 GB RAM

  • 16,000 enrichments

3
  • 384 GB disk space

  • 16 GB RAM

  • 32,000 enrichments

Name Description
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
environmentName string The name for the new environment.
size enum string The size for the new environment, as described in the following table. Possible values are FREE (0), ONE (1), TWO (2), and THREE (3).

The following table shows the available values for size. See the Discovery service home page for additional information about sizing and pricing. To create a free trial environment, specify the value of size as 0 (zero).

Sizing
Size Attributes
FREE (0)
  • 2 GB disk space

  • 1 GB RAM

  • Unlimited enrichments

  • Single search node, therefore no high availability

  • 30-day trial only

ONE (1)
  • 48 GB disk space

  • 2 GB RAM

  • 4,000 enrichments

TWO (2)
  • 192 GB disk space

  • 8 GB RAM

  • 16,000 enrichments

THREE (3)
  • 384 GB disk space

  • 16 GB RAM

  • 32,000 enrichments

Name Description
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
name string The name for the new environment.
description string The description for the new environment.
size integer The size for the new environment, as described in the following table.

The following table shows the available values for size. See the Discovery service home page for additional information about sizing and pricing. To create a free trial environment, specify the value of size as 0 (zero).

Sizing
Size Attributes
0 (free)
  • 2 GB disk space

  • 1 GB RAM

  • Unlimited enrichments

  • Single search node, therefore no high availability

  • 30-day trial only

1
  • 48 GB disk space

  • 2 GB RAM

  • 4,000 enrichments

2
  • 192 GB disk space

  • 8 GB RAM

  • 16,000 enrichments

3
  • 384 GB disk space

  • 16 GB RAM

  • 32,000 enrichments

Example request


curl -X POST -u "{username}":"{password}" -H "Content-Type: application/json" -d '{
  "name": "my_environment",
  "description": "My environment",
  "size": 1
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments?version=2017-07-19"

Example body

{
  "name": "my_environment",
  "description": "My environment",
  "size": 1
}
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.createEnvironment({
  name: 'my_environment',
  description: 'My environment',
  size: 1
},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

response = discovery.create_environment(
  name="my_environment",
  description="My environment",
  size=1
)

print(json.dumps(response, indent=2))

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentName = "my_environment";
String environmentDesc = "My environment";

CreateEnvironmentRequest.Builder createRequestBuilder = new CreateEnvironmentRequest.Builder(environmentName, CreateEnvironmentRequest.Size.ONE);
createRequestBuilder.description(environmentDesc);
CreateEnvironmentResponse createResponse = discovery.createEnvironment(createRequestBuilder.build()).execute();

Response

Returns a JSON string that lists information about the environment.

Name Description
environment_id string The unique identifier for this environment.
name string Name that identifies the environment.
description string Description of the environment, if available.
created string Creation date of the environment, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent environment update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string Status of the environment.
read_only Boolean Boolean. If the value is true, the environment contains read-only collections such as News that are provided and maintained by IBM.

You cannot perform the following operations in a read-only environment:

  • Add new collections or configurations

  • Delete collections or configurations

  • Add documents to a collection

  • Update a configuration

index_capacity string JSON string listing the disk and memory capacities and usage of the new environment.
disk_usage string Summary of disk-usage statistics for the environment.
used_bytes integer Number of bytes used on the environment's disk capacity.
total_bytes integer Total number of bytes available in the environment's disk capacity.
used string Amount of disk capacity used, in kB or GB format.
total string Total amount of the environment's disk capacity, in kB or GB format.
percent_used number Percentage of the environment's disk capacity that is being used.
memory_usage string Summary of memory-usage statistics for the environment.
used_bytes integer Number of bytes used in the environment's memory capacity.
total_bytes integer Total number of bytes available in the environment's memory capacity.
used string Amount of memory capacity used, in KB or GB format.
total string Total amount of the environment's memory capacity, in KB or GB format.
percent_used number Percentage of the environment's memory capacity that is being used.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
403 Forbidden The request attempted to update a read-only environment

Example response

{
  "environment_id": "6d6e9e64-4fca-4fb2-871d-561d731c34d7",
  "name": "my_environment",
  "description": "My environment",
  "created": "2017-01-16T17:20:09.802Z",
  "updated": "2017-01-16T17:20:09.802Z",
  "status": "pending",
  "read_only": false,
  "index_capacity": {
    "disk_usage": {
      "used_bytes": 0,
      "total_bytes": 2147483648,
      "used": "0 KB",
      "total": "2 GB",
      "percent_used": 0
    },
    "memory_usage": {
      "used_bytes": 0,
      "total_bytes": 0,
      "used": "0 KB",
      "total": "0 KB",
      "percent_used": 0
    }
  }
}

List environments

List existing environments for the service instance.

GET /v1/environments

Request

Name Description
name path string Show only the environment with the given name.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");

GetEnvironmentsRequest getRequest = new GetEnvironmentsRequest.Builder().build();
GetEnvironmentsResponse getResponse = discovery.getEnvironments(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

environments = discovery.get_environments()
print(json.dumps(environments, indent=2))

news_environments = [x for x in environments['environments'] if x['name'] == 'Watson Discovery News Environment']
news_environment_id = news_environments[0]['environment_id']
print(json.dumps(news_environment_id, indent=2))

collections = discovery.list_collections(news_environment_id)
news_collections = [x for x in collections['collections']]
print(json.dumps(collections, indent=2))

print(discovery.list_configurations(environment_id=news_environment_id))
default_config_id = discovery.get_default_configuration_id(environment_id=news_environment_id)
print(json.dumps(default_config_id, indent=2))

default_config = discovery.get_configuration(environment_id=news_environment_id, configuration_id=default_config_id)
print(json.dumps(default_config, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getEnvironments((), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns an array that lists information about each environment.

Name Description
environments string[ ] An array of [environments] that are available for the service instance.
environments
Name Description
environment_id string The unique identifier for this environment.
name string Name that identifies the environment.
description string Description of the environment, if available.
created string Creation date of the environment, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent environment update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string Status of the environment.
read_only boolean Specifies whether the environment is read-only. Watson Discovery News environments are read-only.
disk_usage string[ ] Summary of disk-usage statistics for the environment.
used_bytes integer Number of bytes used on the environment's disk capacity.
total_bytes integer Total number of bytes available in the environment's disk capacity.
used string Amount of disk capacity used, in KB or GB format.
total string Total amount of the environment's disk capacity, in KB or GB format.
percent_used number Percentage of the environment's disk capacity that is being used.
memory_usage string[ ] Summary of memory-usage statistics for the environment.
used_bytes integer Number of bytes used in the environment's memory capacity.
total_bytes integer Total number of bytes available in the environment's memory capacity.
used string Amount of memory capacity used, in KB or GB format.
total string Total amount of the environment's memory capacity, in KB or GB format.
percent_used number Percentage of the environment's memory capacity that is being used.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
  "environments": [
    {
      "environment_id": "29cfa16a-3161-47b7-829a-42b1e559e7e4",
      "name": "Watson Discovery News Environment",
      "description": "Watson Discovery News cluster environment",
      "created": "2017-01-16T16:04:15.183Z",
      "updated": "2017-01-16T16:04:15.183Z",
      "status": "active",
      "read_only": true
    },
    {
      "environment_id": "3efa9d8a-c81f-4c93-a64d-5d280a85b589",
      "name": "new_env",
      "description": "new environment",
      "created": "2017-01-17T14:04:11.263Z",
      "updated": "2017-01-17T14:04:11.263Z",
      "status": "active",
      "read_only": false,
      "index_capacity": {
        "disk_usage": {
          "used_bytes": 704476,
          "total_bytes": 2147483648,
          "used": "687.96 KB",
          "total": "2 GB",
          "percent_used": 0.03
        },
        "memory_usage": {
          "used_bytes": 577985152,
          "total_bytes": 1664352256,
          "used": "551.21 MB",
          "total": "1.55 GB",
          "percent_used": 34.73
        }
      }
    }
  ]
}

List environment details

Gets detailed information about the specified environment.

GET /v1/environments/{environment_id}

Request

Name Description
environment_id path string The ID of the environment whose information you want to display.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";

GetEnvironmentRequest getRequest = new GetEnvironmentRequest.Builder(environmentId).build();
GetEnvironmentResponse getResponse = discovery.getEnvironment(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

environment_info = discovery.get_environment('{environment_id}')
print(json.dumps(environment_info, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getEnvironment(('{environment_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns an array that lists information about the environment.

environment_id string The unique identifier for this environment.
name string Name that identifies the environment.
description string Description of the environment, if available.
created string Creation date of the environment, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent environment update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string Status of the environment.
read_only boolean Specifies whether the environment is read-only. Watson Discovery News environments are read-only.
disk_usage string[ ] Summary of disk-usage statistics for the environment.
used_bytes integer Number of bytes used on the environment's disk capacity.
total_bytes integer Total number of bytes available in the environment's disk capacity.
used string Amount of disk capacity used, in KB or GB format.
total string Total amount of the environment's disk capacity, in KB or GB format.
percent_used number Percentage of the environment's disk capacity that is being used.
memory_usage string[ ] Summary of memory-usage statistics for the environment.
used_bytes integer Number of bytes used in the environment's memory capacity.
total_bytes integer Total number of bytes available in the environment's memory capacity.
used string Amount of memory capacity used, in KB or GB format.
total string Total amount of the environment's memory capacity, in KB or GB format.
percent_used number Percentage of the environment's memory capacity that is being used.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
  "environment_id": "3efa9d8a-c81f-4c93-a64d-5d280a85b589",
  "name": "new_env",
  "description": "new environment",
  "created": "2017-01-17T14:04:11.263Z",
  "updated": "2017-01-17T14:04:11.263Z",
  "status": "active",
  "read_only": false,
  "index_capacity": {
    "disk_usage": {
      "used_bytes": 704476,
      "total_bytes": 2147483648,
      "used": "687.96 KB",
      "total": "2 GB",
      "percent_used": 0.03
    },
    "memory_usage": {
      "used_bytes": 561291112,
      "total_bytes": 1664352256,
      "used": "535.29 MB",
      "total": "1.55 GB",
      "percent_used": 33.72
    }
  }
}

Update an environment

Updates an existing environment.

PUT /v1/environments/{environment_id}

Request

Name Description
environment_id path string The ID of the environment you want to update.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
body query string The name of the updated environment.
Name Description
environmentId path string The ID of the environment you want to update.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
environmentName string The new name for the environment.
envDescription string The new description for the environment.
size integer The new size for the environment. See Create an environment for information about environment sizes.
Name Description
environment_id path string The ID of the environment you want to update.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
name path string The name of the updated environment.
description path string The description of the updated environment.
size integer The new size for the environment. See Create an environment for information about environment sizes.

Node method not currently available.

Example request


curl -X PUT -u "{username}":"{password}" -H "Content-Type: application/json" -d '{
   "name": "Andrea_environment",
   "description": "Dev environment for Andrea",
   "size": 2
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}?version=2017-07-19"

Example body

{
   "name": "Andrea_environment",
   "description": "Dev environment for Andrea",
   "size": 2
}

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String environmentName = "Andrea_environment";
String envDescription = "Dev environment for Andrea";

UpdateEnvironmentRequest.Builder updateBuilder = new UpdateEnvironmentRequest.Builder(environmentId, environmentName);
updateBuilder.description(envDescription);
UpdateEnvironmentResponse updateResponse = discovery.updateEnvironment(updateBuilder.build()).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

new_name = discovery.update_environment('{environment_id}', 'Andrea_environment', 'Dev environment for Andrea', 2)

print(json.dumps(new_name, indent=2))
Node method not currently available.

Response

Returns a list of information about the environment.

Name Description
environment_id string The unique identifier for this environment.
name string Name that identifies the environment.
description string Description of the environment, if available.
created string Creation date of the environment, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent environment update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string Status of the environment.
disk_usage string[ ] Summary of disk-usage statistics for the environment.
used_bytes integer Number of bytes used on the environment's disk capacity.
total_bytes integer Total number of bytes available in the environment's disk capacity.
used string Amount of disk capacity used, in KB or GB format.
total string Total amount of the environment's disk capacity, in KB or GB format.
percent_used number Percentage of the environment's disk capacity that is being used.
memory_usage string[ ] Summary of memory-usage statistics for the environment.
used_bytes integer Number of bytes used in the environment's memory capacity.
total_bytes integer Total number of bytes available in the environment's memory capacity.
used string Amount of memory capacity used, in KB or GB format.
total string Total amount of the environment's memory capacity, in KB or GB format.
percent_used number Percentage of the environment's memory capacity that is being used.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
403 Forbidden The request attempted to update a read-only environment

Node method not currently available.

Example response

{
  "environment_id": "9e21069a-8bc1-475e-a1d3-2121c49ef060",
  "name": "Andrea_environment",
  "description": "Dev environment for Andrea",
  "created": "2016-12-13T17:42:23.067Z",
  "updated": "2016-12-14T08:22:05.231Z",
  "status": "available",
  "index_capacity": {
    "disk_usage": {
      "used_bytes": 0,
      "total_bytes": 1073741824,
      "used": "0 KB",
      "total": "1024 MB",
      "percent_used": 0
    },
    "memory_usage": {
      "used_bytes": 139035968,
      "total_bytes": 518979584,
      "used": "132.6 MB",
      "total": "494.94 MB",
      "percent_used": 26.79
    }
  }
}

Node response not currently available.

Delete an environment

Deletes an existing environment.

DELETE /v1/environments/{environment_id}

Request

Name Description
environment_id path string The ID of the environment you want to delete.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -u "{username}":"{password}" -X DELETE "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";

DeleteEnvironmentRequest deleteRequest = new DeleteEnvironmentRequest.Builder(environmentId).build();
DeleteEnvironmentResponse deleteResponse = discovery.deleteEnvironment(deleteRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

del_env = discovery.delete_environment('{environment_id}')
print(json.dumps(del_env, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.deleteEnvironment(('{environment_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns the environment's unique identifier and its status. A status of deleted indicates that the environment has been successfully deleted.

Name Description
environment_id string The unique identifier for this environment.
status string Status of the environment.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
403 Forbidden The request attempted to update a read-only environment

Example response

{
  "environment_id": "{environment_id}",
  "status": "deleted"
}

Configurations

Manage custom configurations for your environment.

See Configuring your service in the main documentation set for information about default and custom configurations.

Add a configuration

Adds a configuration to the service instance.

If the input configuration contains the configuration_id, created, or updated properties, the system ignores and overwrites them. However, the properties do not return an error; this enables you to copy an existing configuration and paste it as the basis of a new configuration.

The configuration can contain unrecognized JSON fields. Any such fields are ignored, but do not generate an error. This makes it easier to user newer configuration files with older versions of the API and the service. It also makes it possible for the tooling to add additional metadata and information to the configuration.

POST /v1/environments/{environment_id}/configurations

Request

Name Description
environment_id path string The unique identifier for the environment in which you want to create a configuration.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
configuration body string (JSON object) A JSON string or file detailing the configuration you want to create.

Node method not currently available.

Name Description
environment_id path string The unique identifier for the environment in which you want to create a configuration.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
configurationName string The name for the new configuration.
configuration body string (JSON object) A JSON string or file detailing the configuration you want to create.
configFilePath path string The path to the configuration file.

Example request


curl -X POST -u "{username}":"{password}" -H "Content-Type: application/json" -d @config.json "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/configurations?version=2017-07-19"

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id"};
String configurationName = "doc-config";

CreateConfigurationRequest.Builder createBuilder = new CreateConfigurationRequest.Builder(environmentId);
Configuration configuration = GsonSingleton.getGson().fromJson(
    new FileReader("./config.json"),
    com.ibm.watson.internal.discovery.model.configuration.Configuration.class);
configuration.setName(configurationName);
createBuilder.configuration(configuration);
CreateConfigurationResponse createResponse = discovery.createConfiguration(createBuilder.build()).execute();

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

with open(os.path.join(os.getcwd(), 'config.json')) as config_data:
  data = json.load(config_data)
  new_config = discovery.create_configuration('{environment_id},' data)
print(json.dumps(new_config, indent=2))

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }
Node example not currently available.

Response

Node response codes not currently available.

Returns a JSON object that details the new configuration.

configuration_id string The unique identifier for this configuration.
name string Name that identifies the configuration.
created string Creation date of the configuration, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent configuration update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
description string Description of the configuration, if available.
conversions string[ ] An array of document conversion settings for the configuration.
enrichments string[ ] An array of document enrichment settings for the configuration.

The default configuration includes the following enrichments:

  • Entities (Entity Extraction)

  • Sentiment (Sentiment Analysis)

  • Categories (Category Classification)

  • Concepts (Concept Tagging)

For more information about enrichments, see "Adding enrichments" in the main documentation set.

normalizations string[ ] An array of document normalization settings for the configuration.
fields string[ ] An array of document field-type mappings for the configuration.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Node response codes not currently available.

Example response

{
  "configuration_id": "2e079259-7dd2-40a9-998f-3e716f5a7b88",
  "name": "doc-config",
  "description": "this is a demo configuration",
  "created": "2016-12-14T02:33:34.396Z",
  "updated": "2016-12-14T02:33:34.396Z",
  "conversions": {
    "word": {
      "heading": {
        "fonts": [
          {
            "level": 1,
            "min_size": 24,
            "bold": false,
            "italic": false
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 23,
            "bold": true,
            "italic": false
          },
          {
            "level": 3,
            "min_size": 14,
            "max_size": 17,
            "bold": false,
            "italic": false
          },
          {
            "level": 4,
            "min_size": 13,
            "max_size": 13,
            "bold": true,
            "italic": false
          }
        ],
        "styles": [
          {
            "level": 1,
            "names": [
              "pullout heading",
              "pulloutheading",
              "header"
            ]
          },
          {
            "level": 2,
            "names": [
              "subtitle"
            ]
          }
        ]
      }
    },
    "pdf": {
      "heading": {
        "fonts": [
          {
            "level": 1,
            "min_size": 24,
            "max_size": 80
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 24,
            "bold": false,
            "italic": false
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 24,
            "bold": true
          },
          {
            "level": 3,
            "min_size": 13,
            "max_size": 18,
            "bold": false,
            "italic": false
          },
          {
            "level": 3,
            "min_size": 13,
            "max_size": 18,
            "bold": true
          },
          {
            "level": 4,
            "min_size": 11,
            "max_size": 13,
            "bold": false,
            "italic": false
          }
        ]
      }
    },
    "html": {
      "exclude_tags_completely": [
        "script",
        "sup"
      ],
      "exclude_tags_keep_content": [
        "font",
        "em",
        "span"
      ],
      "exclude_content": {
        "xpaths": []
      },
      "keep_content": {
        "xpaths": []
      },
      "exclude_tag_attributes": [
        "EVENT_ACTIONS"
      ]
    },
    "json_normalizations": []
  },
  "enrichments": [
    {
      "source_field": "text",
      "destination_field": "enriched_text",
      "enrichment": "natural_language_understanding",
      "options": {
        "features": {
          "entities": {
            "sentiment": true,
            "emotion": false,
            "limit": 50
          },
          "sentiment": {
            "document": true
          },
          "categories": {},
          "concepts": {
            "limit": 8
          }
        }
      }
    }
  ]
}

Node response not currently available.

List configurations

Lists existing configurations for the service instance.

GET /v1/environments/{environment_id}/configurations

Request

Name Description
environment_id path string The unique identifier for the environment in which the configuration is located.
name path string Show only the configuration with the given name.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/configurations?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";

GetConfigurationsRequest getRequest = new GetConfigurationsRequest.Builder(environmentId).build();
GetConfigurationsResponse getResponse = discovery.getConfigurations(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

configs = discovery.list_configurations({'environment_id'})
print(json.dumps(configs, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getConfigurations(('{environment_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns an array that lists each configuration's ID, name, description, creation date, and date of last update.

Name Description
configurations string[ ] An array of [configurations] that are available for the service instance.
configurations
Name Description
configuration_id string The unique identifier for this configuration.
name string Name that identifies the configuration.
description string Description of the configuration, if available.
created string Creation date of the configuration, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent configuration update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
  "configurations": [
    {
      "updated": "2017-01-17T14:04:11.270Z",
      "created": "2017-01-17T14:04:11.270Z",
      "name": "Default Configuration",
      "configuration_id": "6f45a3b2-b02a-472c-a385-28498e7bb77e",
      "description": "The configuration used by default when creating a new collection without specifying a configuration_id."
    },
    {
      "updated": "2017-01-17T15:51:00.665Z",
      "created": "2017-01-17T15:51:00.665Z",
      "name": "doc-config",
      "configuration_id": "6b2af929-dd2b-4bc0-9f3f-5ce9ef1b78d8",
      "description": "this is a demo configuration"
    }
  ]
}

List configuration details

Get information about the specified configuration.

GET /v1/environments/{environment_id}/configurations/{configuration_id}

Request

Name Description
environment_id path string The ID of the environment in which the specified configuration is located.
configuration_id path string The ID of the configuration whose information you want to display.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/configurations/{configuration_id}?version=2017-07-19"
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getConfiguration(('{environment_id}', '{configuration_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String configurationId = "{configuration_id}";

GetConfigurationRequest getRequest = new GetConfigurationRequest.Builder(environmentId, configurationId).build();
GetConfigurationResponse getResponse = discovery.getConfiguration(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

config = discovery.get_configuration({'environment_id'}, {'configuration_id'})
print(json.dumps(config, indent=2))

Response

Returns a list of information about the configuration.

configuration_id string The unique identifier for this configuration.
name string Name that identifies the configuration.
description string Description of the configuration, if available.
created string Creation date of the configuration, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent configuration update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
conversions string A list of the configuration's document conversion settings.
enrichments string[ ] An array describing the configuration's document enrichment settings.
normalizations string[ ] An array describing the configuration's document normalization settings.
conversions
word string A list of Word conversion settings, including the conversions applied to different types of headings as defined by font attributes and to different formatting styles of text.
pdf string A list of PDF conversion settings, including the conversions applied to different types of headings as defined by font attributes.
html string A list of HTML conversion settings, including tags that are to be excluded completely; tags that are to be discarded but their content kept; content that is to be excluded as defined by xpaths; content that is to be kept as defined by xpaths; and tag attributes that are to be excluded.
json_normalizations string[ ] An array of JSON normalization operations, including one or more of the following:
  • copy—Copies the value of the source_field to the destination_field. If the destination_field already exists, the value of the source_field overwrites the original value of the destination_field.

  • move—Renames (moves) the source_field to the destination_field. If the destination_field already exists, the value of the source_field overwrites the original value of the destination_field. Rename is identical to copy, except that the source_field is removed after the value has been copied to the destination_field. It is the same as a copy followed by a remove.

  • merge—Merges the value of the source_field with the value of the destination_field. The destination_field is converted into an array if it is not already an array, and the value of the source_field is appended to the array. This operation removes the source_field after the merge. If the source_field does not exist in the current document, the destination_field is converted into an array if it is not already an array. This is ensures the type for destination_field is consistent across all documents.

  • remove—Deletes the source_field. The destination_field is ignored for this operation.

  • remove_nulls—Removes all nested null (blank) leaf values from the JSON tree. The source_field and destination_field are ignored by this operation because remove_nulls operates on the entire JSON tree. Typically, remove_nulls is invoked as the last normalization operation; if it is invoked, it can be time-expensive.

The array also lists the source_field and destination_field for each operation.

If no JSON normalization operations are specified, the method returns an empty array.

enrichments
enrichments string[ ] An array of strings detailing each of the configuration's enrichments, including the following items:
  • destination_field—The field into which the service writes the enriched material; for example, enriched_text.

  • source_field—The field that contains the material that is to be enriched; for example, text.

  • enrichment—The type of enrichment being applied; for example, natural_language_understanding.

  • options—A list of options specific to the enrichment.

normalizations
normalizations string[ ] An array listing the configuration's normalizations, identical to those described in json_normalizations.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
  "configuration_id": "2e079259-7dd2-40a9-998f-3e716f5a7b88",
  "name": "doc-config",
  "description": "this is a demo configuration",
  "created": "2016-11-03T02:33:34.396Z",
  "updated": "2016-11-03T02:33:34.396Z",
  "conversions": {
    "word": {
      "heading": {
        "fonts": [
          {
            "level": 1,
            "min_size": 24,
            "bold": false,
            "italic": false
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 23,
            "bold": true,
            "italic": false
          },
          {
            "level": 3,
            "min_size": 14,
            "max_size": 17,
            "bold": false,
            "italic": false
          },
          {
            "level": 4,
            "min_size": 13,
            "max_size": 13,
            "bold": true,
            "italic": false
          }
        ],
        "styles": [
          {
            "level": 1,
            "names": [
              "pullout heading",
              "pulloutheading",
              "header"
            ]
          },
          {
            "level": 2,
            "names": [
              "subtitle"
            ]
          }
        ]
      }
    },
    "pdf": {
      "heading": {
        "fonts": [
          {
            "level": 1,
            "min_size": 24,
            "max_size": 80
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 24,
            "bold": false,
            "italic": false
          },
          {
            "level": 2,
            "min_size": 18,
            "max_size": 24,
            "bold": true
          },
          {
            "level": 3,
            "min_size": 13,
            "max_size": 18,
            "bold": false,
            "italic": false
          },
          {
            "level": 3,
            "min_size": 13,
            "max_size": 18,
            "bold": true
          },
          {
            "level": 4,
            "min_size": 11,
            "max_size": 13,
            "bold": false,
            "italic": false
          }
        ]
      }
    },
    "html": {
      "exclude_tags_completely": [
        "script",
        "sup"
      ],
      "exclude_tags_keep_content": [
        "font",
        "em",
        "span"
      ],
      "exclude_content": {
        "xpaths": []
      },
      "keep_content": {
        "xpaths": []
      },
      "exclude_tag_attributes": [
        "EVENT_ACTIONS"
      ]
    },
    "json_normalizations": []
  },
  "enrichments": [
    {
      "source_field": "text",
      "destination_field": "enriched_text",
      "enrichment": "natural_language_understanding",
      "options": {
        "features": {
          "entities": {
            "sentiment": true,
            "emotion": false,
            "limit": 50
          },
          "sentiment": {
            "document": true
          },
          "categories": {},
          "concepts": {
            "limit": 8
          }
        }
      }
    }
  ]
}

Update a configuration

Replaces an existing configuration.

This operation completely replaces the previous configuration.

Important: Do not attempt to replace the default configuration.

The new configuration can contain one or more of the configuration_id, updated, or created elements, but the elements are ignored and do not generate errors to enable pasting in another existing configuration. You can also provide a new configuration with none of the three elements.

Documents are processed with a snapshot of the configuration that was in place at the time the document was submitted for ingestion. This means documents that were already submitted are not processed with the new configuration.

PUT /v1/environments/{environment_id}/configurations/{configuration_id}

Request

Name Description
environment_id path string The ID of the environment in which the specified configuration is located.
configuration_id path string The ID of the configuration you want to replace.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
configuration body string (JSON object) A JSON string or file detailing the new configuration.
Name Description
environment_id path string The unique identifier for the environment in which you want to create a configuration.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
updatedConfigurationName string The name for the updated configuration.
updatedConfiguration string (JSON object) A JSON string or file detailing the configuration you want to update.
updatedConfigFilePath path string The path to the updated configuration file.
Name Description
environment_id path string The ID of the environment in which the specified configuration is located.
configuration_id path string The ID of the configuration you want to replace.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
config_data body string (JSON object) A JSON string or file detailing the new configuration.

Example request


curl -X PUT -u "{username}":"{password}" -H "Content-Type: application/json" -d @new_config.json "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/configurations/{configuration_id}?version=2017-07-19"

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String configurationId = "{configuration_id}";
String updatedConfigurationName = "new-config";
Configuration updatedConfiguration = GsonSingleton.getGson().fromJson(
    new FileReader("{updatedConfigFilePath}"),
        com.ibm.watson.internal.discovery.model.configuration.Configuration.class);

UpdateConfigurationRequest.Builder updateBuilder = new UpdateConfigurationRequest.Builder(environmentId, configurationId);
createResponse.setName(updatedConfigurationName);
updateBuilder.configuration(updatedConfiguration);
UpdateConfigurationResponse updateResponse = discovery.updateConfiguration(updateBuilder.build()).execute();

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

with open(os.path.join(os.getcwd(), 'config_update.json')) as config_data:
  data = json.load(config_data)
  updated_config = discovery.update_configuration('{environment_id}', '{environment_id},' data)
print(json.dumps(updated_config, indent=2))

Example JSON configuration file

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }

Response

Returns a list of detailed information about the configuration.

configuration_id string The unique identifier for the configuration.
name string Name that identifies the configuration.
created string Creation date of the configuration, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string Date of most recent configuration update, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
description string Description of the configuration, if available.
conversions string[ ] An array of document conversion settings for the configuration.
enrichments string[ ] An array of document enrichment settings for the configuration.
normalizations string[ ] An array of document normalization settings for the configuration.
fields string[ ] An array of document field-type mappings for the configuration.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
    "name": "Demonstration configuration",
    "description": "A demonstration configuration that has the same contents as the default configuration.",
    "workflow": {
      "conversions": {
        "word": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 23,
                "bold": true,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 14,
                "max_size": 17,
                "bold": false,
                "italic": false
              },
              {
                "level": 4,
                "min_size": 13,
                "max_size": 13,
                "bold": true,
                "italic": false
              }
            ],
            "styles": [
              {
                "level": 1,
                "names": [
                  "pullout heading",
                  "pulloutheading",
                  "header"
                ]
              },
              {
                "level": 2,
                "names": [
                  "subtitle"
                ]
              }
            ]
          }
        },
        "pdf": {
          "heading": {
            "fonts": [
              {
                "level": 1,
                "min_size": 24,
                "max_size": 80
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": false,
                "italic": false
              },
              {
                "level": 2,
                "min_size": 18,
                "max_size": 24,
                "bold": true
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": false,
                "italic": false
              },
              {
                "level": 3,
                "min_size": 13,
                "max_size": 18,
                "bold": true
              },
              {
                "level": 4,
                "min_size": 11,
                "max_size": 13,
                "bold": false,
                "italic": false
              }
            ]
          }
        },
        "html": {
          "exclude_tags_completely": [
            "script",
            "sup"
          ],
          "exclude_tags_keep_content": [
            "font",
            "em",
            "span"
          ],
          "exclude_content": {
            "xpaths": []
          },
          "keep_content": {
            "xpaths": []
          },
          "exclude_tag_attributes": [
            "EVENT_ACTIONS"
          ]
        },
        "json_normalizations": []
      },
      "enrichments": [
        {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
            "features": {
              "entities": {
                "sentiment": true,
                "emotion": false,
                "limit": 50
              },
              "sentiment": {
                "document": true
              },
              "categories": {},
              "concepts": {
                "limit": 8
              }
            }
          }
        }
      ],
      "normalizations": []
    },
    "environment_id": null
  },
  "watsonnews": {
    "name": "Default Configuration",
    "description": "Default configuration for Watson Discovery News cluster",
    "workflow": {},
    "environment_id": null
  }

Delete a configuration

Deletes an existing configuration from the service instance.

The delete operation is performed unconditionally. A delete request succeeds even if the configuration is referenced by a collection or document ingestion. However, documents that have already been submitted for processing continue to use the deleted configuration; documents are always processed with a snapshot of the configuration as it existed at the time the document was submitted.

DELETE /v1/environments/{environment_id}/configurations/{configuration_id}

Request

Name Description
environment_id path string The ID of the environment in which the specified configuration is located.
configuration_id path string The ID of the configuration that you want to delete.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Node method not currently available.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/configurations/{configuration_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String configurationId = "{configuration_id}";

DeleteConfigurationRequest deleteRequest = new DeleteConfigurationRequest.Builder(environmentId, configurationId).build();
DeleteConfigurationResponse deleteResponse = discovery.deleteConfiguration(deleteRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

config_delete = discovery.delete_configuration('{environment_id}', '{configuration_id}')
print(json.dumps(config_delete, indent=2))
Node example not currently available.

Response

Node response not currently available.

Returns the configuration ID and the status of the delete operation, and a warning if the configuration was referenced by any collections or documents.

Name Description
configuration_id string The unique identifier for the configuration.
status string Status of the configuration. A deleted configuration has the status deleted.
notices string[ ] An array of notice messages, if any.
notices
Name Description
notice_id string Text ID of the notice.
created string Creation date of the configuration, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
severity string Severity of the notice. Possible values include warning and error.
description string Description of the notice.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes for Node not currently available.

Example response

{
  "configuration_id": "448e3545-51ca-4530-a03b-6ff282ceac2e",
  "status": "deleted",
  "notices": [
    {
      "notice_id": "configuration_in_use",
      "created": "2016-09-28T12:34:00.000Z",
      "severity": "warning",
      "description": "The configuration was deleted, but it is referenced by one or more collections."
    }
  ]
}

Node response not currently available.

Test your configuration on a document

Test a configuration by running a sample document through the ingestion process.

Test your configuration

Run a sample document against your configuration or the default configuration and return diagnostic information designed to help you understand how the document was processed. The document is not added to a collection. To add a document to your collection, use the POST /v1/environments/{environment_id}/collections/{collection_id}/documents method.

POST /v1/environments/{environment_id}/preview

Request

Name Description
environment_id path string The ID of the environment in which the configuration for testing is located.
configuration formData undefined The configuration to use to process the document. If this part is provided, then the provided configuration is used to process the document. If the configuration_id field is also provided (that is, if both are present at the same time), the request is rejected. The maximum supported configuration size is 1 MB. Configuration parts larger than 1 MB are rejected. See the POST /v1/environments/{environment_id}/configurations operation for an example configuration.
configuration_id query string The ID of the configuration to use to process the document. To specify the default configuration, use the GET /v1/environments/{environment_id}/configurations method to find the configuration_id of the default configuration. If both this parameter and the configuration parameter are specified in the same request, the request is rejected.
file formData undefined The content of the document to ingest. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/html, and application/xhtml+xml. Specify content type in the multipart form as type=.
metadata formData string If you're using the Data Crawler to upload your documents, you can test a document against the type of metadata that the Data Crawler might send. The maximum supported metadata file size is 1 MB. Metadata parts larger than 1 MB are rejected.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Java method not currently available.

Node method not currently available.

Name Description
configuration_id query string The ID of the configuration to use to process the document. To specify the default configuration, use the GET /v1/environments/{environment_id}/configurations method to find the configuration_id of the default configuration. If both this parameter and the configuration parameter are specified in the same request, the request is rejected.
file formData undefined The content of the document to ingest. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/html, and application/xhtml+xml. Specify content type in the multipart form as type=.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


curl -X POST -u "{username}":"{password}" -F "file=@sample1.html;type=text/html" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/preview?version=2017-07-19&configuration_id={configuration_id}"

Example metadata

{
  "Creator": "Johnny Appleseed",
  "Subject": "Apples"
}
Java example not currently available.
Node example not currently available.
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

with open(os.path.join(os.getcwd(), 'resources', 'simple.html')) as fileinfo:
   print(json.dumps(discovery.test_document('{environment_id}', fileinfo=fileinfo), indent=2))

Response

Response information not currently available.

Returns detailed information about the preview run.

Name Description
configuration_id string The unique identifier for the configuration.
status string Status of the preview operation.
enriched_field_units number Number of 10-kB units of field data enrichments that were enriched. This can be used to estimate the cost of ingesting the document.
original_media_type string Format of the test document; for example, text/html.
snapshots string[ ] An array of JSON strings that describe each step in the preview process.
notices string[ ] An array of notice messages about the preview operation.
Name Description
snapshot string[ ] An array of arbitrary JSON strings that describe the step and its results.
notices
Name Description
notice_id string Text ID of the event notice.
created string Creation timestamp of the notice, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
document_id string ID of the document in which the event notice occurred.
severity string Severity of the notice. Possible values are warning and error.
step string Step in the preview operation in which the event occurred.
description string Description of the notice.
details string[ ] An arbitrary JSON object that provides details that can help you identify and resolve errors.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response

{
  "status": "completed",
  "enriched_field_units": 0,
  "original_media_type": "text/html",
  "snapshots": [
    {
      "step": "html_input",
      "snapshot": {
        "html": "<!DOCTYPE html>\n<html>\n<body>\n\n<title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title>\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n</body>\n</html>"
      }
    },
    {
      "step": "html_output",
      "snapshot": {
        "html": "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><html>\n<head>\n    <meta content=\"text/html; charset=UTF-8\" http-equiv=\"Content-Type\"/><title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title></head>\n<body>\n\n\n\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n\n</body></html>"
      }
    },
    {
      "step": "json_output",
      "snapshot": {
        "extracted_metadata": {
          "title": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring"
        },
        "html": "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><html>\n<head>\n    <meta content=\"text/html; charset=UTF-8\" http-equiv=\"Content-Type\"/>\n    <title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title>\n</head>\n<body>\n\n\n\n\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n\n</body></html>",
        "text": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring\n\nPublished: Tue, 01 Nov 2016 08:32:23 GMT\n\nCelgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.\n\nURL: http://www.ibm.com/press/us/en/pressrelease/50927.wss"
      }
    },
    {
      "step": "json_normalizations_output",
      "snapshot": {
        "extracted_metadata": {
          "title": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring"
        },
        "html": "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><html>\n<head>\n    <meta content=\"text/html; charset=UTF-8\" http-equiv=\"Content-Type\"/>\n    <title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title>\n</head>\n<body>\n\n\n\n\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n\n</body></html>",
        "text": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring\n\nPublished: Tue, 01 Nov 2016 08:32:23 GMT\n\nCelgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.\n\nURL: http://www.ibm.com/press/us/en/pressrelease/50927.wss"
      }
    },
    {
      "step": "enrichments_output",
      "snapshot": {
        "extracted_metadata": {
          "title": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring"
        },
        "html": "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><html>\n<head>\n    <meta content=\"text/html; charset=UTF-8\" http-equiv=\"Content-Type\"/>\n    <title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title>\n</head>\n<body>\n\n\n\n\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n\n</body></html>",
        "text": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring\n\nPublished: Tue, 01 Nov 2016 08:32:23 GMT\n\nCelgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.\n\nURL: http://www.ibm.com/press/us/en/pressrelease/50927.wss",
        "enriched_text": {
          "sentiment": {
            "document": {
              "score": 0.260014,
              "label": "positive"
            }
          },
          "entities": [
            {
              "type": "Company",
              "text": "IBM Watson Health",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.939431,
              "count": 1
            },
            {
              "type": "Facility",
              "text": "Watson Health Forge",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.936844,
              "count": 1
            },
            {
              "type": "Facility",
              "text": "Watson Health Cloud",
              "sentiment": {
                "score": 0.487441
              },
              "relevance": 0.900379,
              "count": 1
            },
            {
              "type": "Company",
              "text": "IBM Watson",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.847945,
              "count": 1
            },
            {
              "type": "JobTitle",
              "text": "Transform Patient Safety Monitoring",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.688245,
              "count": 1
            },
            {
              "type": "Company",
              "text": "IBM",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.514877,
              "disambiguation": {
                "subtype": [
                  "SoftwareLicense",
                  "OperatingSystemDeveloper",
                  "ProcessorManufacturer",
                  "SoftwareDeveloper",
                  "CompanyFounder",
                  "ProgrammingLanguageDesigner",
                  "ProgrammingLanguageDeveloper"
                ],
                "name": "IBM",
                "dbpedia_resource": "http://dbpedia.org/resource/IBM"
              },
              "count": 1
            },
            {
              "type": "Company",
              "text": "Celgene Corporation",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.332536,
              "disambiguation": {
                "subtype": [
                  "VentureFundedCompany"
                ],
                "name": "Celgene",
                "dbpedia_resource": "http://dbpedia.org/resource/Celgene"
              },
              "count": 1
            },
            {
              "type": "Person",
              "text": "Celgene",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.307186,
              "count": 1
            }
          ],
          "concepts": [
            {
              "text": "Adverse drug reaction",
              "relevance": 0.97198,
              "dbpedia_resource": "http://dbpedia.org/resource/Adverse_drug_reaction"
            },
            {
              "text": "Pharmacovigilance",
              "relevance": 0.57362,
              "dbpedia_resource": "http://dbpedia.org/resource/Pharmacovigilance"
            },
            {
              "text": "Thomas J. Watson",
              "relevance": 0.507165,
              "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
            },
            {
              "text": "Illness",
              "relevance": 0.497042,
              "dbpedia_resource": "http://dbpedia.org/resource/Illness"
            },
            {
              "text": "Lotus Software",
              "relevance": 0.482834,
              "dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
            },
            {
              "text": "Pharmacology",
              "relevance": 0.441008,
              "dbpedia_resource": "http://dbpedia.org/resource/Pharmacology"
            },
            {
              "text": "Thomas J. Watson Research Center",
              "relevance": 0.4094,
              "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson_Research_Center"
            }
          ],
          "categories": [
            {
              "score": 0.613225,
              "label": "/health and fitness"
            },
            {
              "score": 0.413686,
              "label": "/business and industrial/company/bankruptcy"
            },
            {
              "score": 0.325571,
              "label": "/technology and computing"
            }
          ]
        }
      }
    },
    {
      "step": "normalizations_output",
      "snapshot": {
        "extracted_metadata": {
          "title": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring"
        },
        "html": "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><html>\n<head>\n    <meta content=\"text/html; charset=UTF-8\" http-equiv=\"Content-Type\"/>\n    <title>Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring</title>\n</head>\n<body>\n\n\n\n\n<p>Published: Tue, 01 Nov 2016 08:32:23 GMT</p>\n<p>Celgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50927.wss</p>\n\n\n</body></html>",
        "text": "Celgene and IBM Watson Health Forge Collaboration Designed to Transform Patient Safety Monitoring\n\nPublished: Tue, 01 Nov 2016 08:32:23 GMT\n\nCelgene Corporation and IBM Watson Health today announced a collaboration to co-develop IBM Watson for Patient Safety, a new offering that aims to enhance pharmacovigilance methods used to collect, assess, monitor, and report adverse drug reactions. The new offering will run on the Watson Health Cloud.\n\nURL: http://www.ibm.com/press/us/en/pressrelease/50927.wss",
        "enriched_text": {
          "sentiment": {
            "document": {
              "score": 0.260014,
              "label": "positive"
            }
          },
          "entities": [
            {
              "type": "Company",
              "text": "IBM Watson Health",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.939431,
              "count": 1
            },
            {
              "type": "Facility",
              "text": "Watson Health Forge",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.936844,
              "count": 1
            },
            {
              "type": "Facility",
              "text": "Watson Health Cloud",
              "sentiment": {
                "score": 0.487441
              },
              "relevance": 0.900379,
              "count": 1
            },
            {
              "type": "Company",
              "text": "IBM Watson",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.847945,
              "count": 1
            },
            {
              "type": "JobTitle",
              "text": "Transform Patient Safety Monitoring",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.688245,
              "count": 1
            },
            {
              "type": "Company",
              "text": "IBM",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.514877,
              "disambiguation": {
                "subtype": [
                  "SoftwareLicense",
                  "OperatingSystemDeveloper",
                  "ProcessorManufacturer",
                  "SoftwareDeveloper",
                  "CompanyFounder",
                  "ProgrammingLanguageDesigner",
                  "ProgrammingLanguageDeveloper"
                ],
                "name": "IBM",
                "dbpedia_resource": "http://dbpedia.org/resource/IBM"
              },
              "count": 1
            },
            {
              "type": "Company",
              "text": "Celgene Corporation",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.332536,
              "disambiguation": {
                "subtype": [
                  "VentureFundedCompany"
                ],
                "name": "Celgene",
                "dbpedia_resource": "http://dbpedia.org/resource/Celgene"
              },
              "count": 1
            },
            {
              "type": "Person",
              "text": "Celgene",
              "sentiment": {
                "score": 0
              },
              "relevance": 0.307186,
              "count": 1
            }
          ],
          "concepts": [
            {
              "text": "Adverse drug reaction",
              "relevance": 0.97198,
              "dbpedia_resource": "http://dbpedia.org/resource/Adverse_drug_reaction"
            },
            {
              "text": "Pharmacovigilance",
              "relevance": 0.57362,
              "dbpedia_resource": "http://dbpedia.org/resource/Pharmacovigilance"
            },
            {
              "text": "Thomas J. Watson",
              "relevance": 0.507165,
              "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
            },
            {
              "text": "Illness",
              "relevance": 0.497042,
              "dbpedia_resource": "http://dbpedia.org/resource/Illness"
            },
            {
              "text": "Lotus Software",
              "relevance": 0.482834,
              "dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
            },
            {
              "text": "Pharmacology",
              "relevance": 0.441008,
              "dbpedia_resource": "http://dbpedia.org/resource/Pharmacology"
            },
            {
              "text": "Thomas J. Watson Research Center",
              "relevance": 0.4094,
              "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson_Research_Center"
            }
          ],
          "categories": [
            {
              "score": 0.613225,
              "label": "/health and fitness"
            },
            {
              "score": 0.413686,
              "label": "/business and industrial/company/bankruptcy"
            },
            {
              "score": 0.325571,
              "label": "/technology and computing"
            }
          ]
        }
      }
    }
  ],
  "notices": []
}

Collections

Create a collection for your documents. Each environment can have multiple collections.

Create a collection

Creates a new collection for storing documents.

POST /v1/environments/{environment_id}/collections

Request

Name Description
environment_id path string The unique identifier of the environment in which you want to create the collection.
body body json A JSON object (string or file) that defines the new collection.

where:

  • {collection_name} specifies the name of the collection to be created.

  • {description} specifies a description of the collection.

  • {configuration_id} specifies the ID of the configuration in which the collection is to be created. To specify the default configuration, use the GET /v1/environments/{environment_id}/configurations method to find the configuration_id of the default configuration.

  • {language_code} specifies the language of the documents that will be stored in the collection. You can specify only one language per collection, and the language cannot be changed. Supported values are English (en), German (de), and Spanish (es). The default is English (en).

    Note: To use a language_code other than en (English), you must use the API version string 2017-07-19 or later.

version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environment_id path string The unique identifier of the environment in which you want to create the collection.
configuration_id path string Specifies the ID of the configuration in which the collection is to be created. To specify the default configuration, use the GET /v1/environments/{environment_id}/configurations method to find the configuration_id of the default configuration.
collection_name path string Specifies the name of the collection to be created.
language_code path string Specifies the language of the documents that will be stored in the collection. You can specify only one language per collection, and the language cannot be changed. Supported values are English (en), German (de), and Spanish (es). The default is English (en).
Note: To use a language_code other than en (English), you must use the API version string 2017-07-19 or later.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environment_id path string The unique identifier of the environment in which you want to create the collection.
configuration_id path string Specifies the ID of the configuration that the collection is to use. If this parameter is not specified, the method uses the default configuration.
collection_name path string Specifies the name of the collection to be created.
description path string Optionally specifies the description of the collection.
language_code path string Specifies the language of the documents that will be stored in the collection. You can specify only one language per collection, and the language cannot be changed. Supported values are English (en), German (de), and Spanish (es). The default is English (en).
Note: To use a language_code other than en (English), you must use the API version string 2017-07-19 or later.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environment_id path string The unique identifier of the environment in which you want to create the collection.
configuration_id path string Specifies the ID of the configuration that the collection is to use. If this parameter is not specified, the method uses the default configuration.
collection_name path string Specifies the name of the collection to be created.
description path string Optionally specifies the description of the collection.
language_code query string Specifies the language of the documents that will be stored in the collection. You can specify only one language per collection, and the language cannot be changed. Supported values are English (en), German (de), and Spanish (es). The default is English (en).
Note: To use a language_code other than en (English), you must use the API version string 2017-07-19 or later.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request


      curl -X POST -u "{username}":"{password}" -H "Content-Type: application/json" -d '{
  "name": "test_collection",
  "description": "My test collection",
  "configuration_id": "{configuration_id}",
  "language_code": "en"
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections?version=2017-07-19"
      

Example JSON body

{
  "name": "{collection_name}",
  "description": "{description}",
  "configuration_id": "{configuration_id}",
  "language_code": "en"
}

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String configurationId = "{configuration_id}";
String collectionName = "{collection_name}";
String languageCode = "{language_code}";

CreateCollectionRequest.Builder createCollectionBuilder = new CreateCollectionRequest.Builder(environmentId, configurationId, collectionName, languageCode);
CreateCollectionResponse createResponse = discovery.createCollection(createCollectionBuilder.build()).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

new_collection = discovery.create_collection('{environment_id}', '{collection_name}', description='{description}', configuration_id='{configuration_id}', language_code='{language_code}')
print(json.dumps(new_collection, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.createCollection(('{environment_id}', '{collection_name}', '{description}', '{configuration_id}', '{language_code}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns a JSON object that describes the new collection.

Name Description
name string The name of the collection.
collection_id string The unique identifier of the collection.
description string The description of the collection, if available.
status string The status of the collection.
created string The creation date of the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string The timestamp of the most recent update to the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
configuration_id string The unique identifier of the configuration in which the collection is located.
language string The language of the documents stored in the collection. Possible values include en (U.S. English), de (German), and es (Spanish).
status string The current status of the collection.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

{
  "name": "new_collection",
  "collection_id": "0c08b701-9499-4a9f-9517-e0851635a59c",
  "description": "New collection",
  "created": "2017-02-08T14:18:22.786Z",
  "updated": "2017-02-08T14:18:22.786Z",
  "configuration_id": "654573b2-b02a-472c-a345-28498eb0b77e",
  "language": "en",
  "status": "active"
}

List collections

Display a list of existing collections.

GET /v1/environments/{environment_id}/collections

Request

Name Description
environment_id path string The unique identifier of the environment in which the collections are located.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
name query string Show only the collection with the given name.
Name Description
environment_id path string The unique identifier of the environment in which the collections are located.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";

GetCollectionsRequest getRequest = new GetCollectionsRequest.Builder(environmentId).build();
GetCollectionsResponse getResponse = discovery.getCollections(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

collections = discovery.list_collections('{environment_id}')
print(json.dumps(collections, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getCollections(('{environment_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns an array that lists each collection's ID, name, configuration ID, language, status, creation date, and date of last update.

Name Description
collections string[ ] An array containing information about each collection in the environment.
collection_id string The unique identifier of the collection.
name string The name of the collection.
created string The creation date of the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string The timestamp of the most recent update to the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string The status of the collection.
language string The language of the documents stored in the collection. Possible values include en (U.S. English), de (German), and es (Spanish).
configuration_id string The unique identifier of the configuration in which the collection is located.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

{
  "collections": [
    {
      "collection_id": "44e29a9a-47e3-4acd-874b-c7cbe04043f1",
      "description": null,
      "name": "test_collection",
      "configuration_id": "e8b9d793-b163-452a-9373-bce07efb510b",
      "language": "en",
      "status": "active",
      "created": "2016-12-14T18:42:25.324Z",
      "updated": "2016-12-14T18:42:25.324Z"
    },
    {
      "collection_id": "0c08b701-9499-4a9f-9517-e0851635a59c",
      "description": "New collection",
      "name": "new_collection",
      "configuration_id": "654573b2-b02a-472c-a345-28498eb0b77e",
      "language": "en",
      "status": "active",
      "created": "2017-02-08T14:18:22.786Z",
      "updated": "2017-02-08T14:18:22.786Z"
    }
  ]
}

List collection details

Show detailed information about an existing collection.

GET /v1/environments/{environment_id}/collections/{collection_id}

Request

Name Description
environment_id path string The unique identifier of the environment in which the collection is located.
collection_id path string The unique identifier of the collection about which to display detailed information.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";

GetCollectionRequest getRequest = new GetCollectionRequest.Builder(environmentId, collectionId).build();
GetCollectionResponse getResponse = discovery.getCollection(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

collection = discovery.get_collection('{environment_id}', '{collection_id}')
print(json.dumps(collection, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.getCollection(('{environment_id}', '{collection_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns details about the specified collection.

Name Description
collection_id string The unique identifier of the collection.
name string The name of the collection.
configuration_id string The unique identifier of the configuration.
language string The language of the documents stored in the collection. Possible values include en (U.S. English), de (German), and es (Spanish).
status string The current status of the collection.
description string The description of the collection.
created string The creation date of the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string The timestamp of the most recent update to the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
document_counts JSON object Object providing information about the documents in the collection.
training JSON object Object providing information about the training data available for the collection.
document_counts
Name Description
available number The total number of available documents in the collection.
processing number The number of documents in the collection that are currently being processed.
failed int The number of documents in the collection that failed to be ingested.
training
Name Description
total_examples int The total number of training-data examples in the collection.
available boolean Specifies whether the collection has enough valid training data to provide the most relevant query results.
processing boolean Specifies whether the service is processing training data.
minimum_queries_added boolean Specifies whether the collection has enough training-data queries to provide the most relevant query results. The number of required queries depends on the size of your collection.
minimum_examples_added boolean Specifies whether the collection has enough training-data examples to provide the most relevant query results. The number of required examples depends on the size of your collection.
sufficient_label_diversity boolean Specifies whether the collection's training data includes an adequate number of relevance scores to provide the most relevant query results. The number of required relevance labels depends on the size of your collection.
notices int The number of notices (errors and warnings) associated with training data. Use the Query ingestion notices method to examine the notices.
successfully_trained date Timestamp indicating when the collection processed enough training data to enable returning the most relevant query results.
data_updated date Timestamp of the last training-data update.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

{
  "collection_id": "f1360220-ea2d-4271-9d62-89a910b13c37",
  "name": "democollection",
  "description": "this is a demo collection",
  "created": "2015-08-24T18:42:25.324Z",
  "updated": "2015-08-24T18:42:25.324Z",
  "status": "available",
  "configuration_id": "6963be41-2dea-4f79-8f52-127c63c479b0",
  "language": "en",
  "document_counts": {
    "available": 1000,
    "processing": 20,
    "failed": 180
  },
  "training": {
    "total_examples": 54,
    "available": true,
    "processing": false,
    "minimum_queries_added": true,
    "minimum_examples_added": true,
    "sufficient_label_diversity": false,
    "notices": 13,
    "successfully_trained": "2017-02-08T14:18:22.786Z",
    "data_updated": "2017-02-10T14:18:22.786Z"
  }
}

Update a collection

Replaces an existing collection.

PUT /v1/environments/{environment_id}/collections/{collection_id}

Request

Name Description
environment_id path string The unique identifier of the environment in which you want to update the collection.
body body json A JSON object (string or file) that defines the updated collection.

where:

  • {collection_name} specifies the name of the collection.

  • {description} specifies a description of the collection.

  • {configuration_id} specifies the ID of the configuration in which the collection is to be updated. To specify the default configuration, use the GET /v1/environments/{environment_id}/configurations method to find the configuration_id of the default configuration.

  • {language_code} specifies the language of the documents that will be stored in the collection. Possible values include en (U.S. English), de (German), and es (Spanish).

    Note: You cannot change the language of an existing collection. The language specified by the POST /v1/environments/{environment_id}/collections method to create the collection is persistent and immutable.

version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Java method not currently available.

Python method not currently available.

Node method not currently available.

Example request


      curl -X PUT -u "{username}":"{password}" -H "Content-Type: application/json" -d '{
  "name": "test_collection",
  "description": "My test collection",
  "configuration_id": "{configuration_id}"
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}?version=2017-07-19"
      

Example JSON body

{
  "name": "{collection_name}",
  "description": "{description}",
  "configuration_id": "{configuration_id}"
}
Java example not currently available.
Python example not currently available.
Node example not currently available.

Response

Response information not currently available.

Returns a JSON object that describes the updated collection.

Name Description
name string The name of the collection.
description string The description of the collection.
created string The creation date of the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
updated string The timestamp of the most recent update to the collection, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
status string The status of the collection.
configuration_id string The unique identifier of the configuration used in the collection.
language string The language of the documents stored in the collection.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Response codes

Response codes not currently available.

Response information not currently available.

Example response

{
  "name": "test_collection",
  "description": "My test collection for doc",
  "created": "2016-11-02T03:20:28.739Z",
  "updated": "2016-11-02T03:20:28.739Z",
  "configuration_id": "c84c21d0-ac94-42bf-b619-7d277f325fdc",
  "language": "en",
  "status": "available"
}

Example response

Example response not currently available.

List collection fields

Gets a list of the unique fields, and each field's type, that are stored in a collection's index.

GET /v1/environments/{environment_id}/collections/{collection_id}/fields

Request

Node information not currently available.

Name Description
environment_id path string The unique identifier of the environment in which the collection is located.
collection_id path string The unique identifier of the collection whose fields you want to display.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/fields?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";

GetCollectionFieldsRequest getRequest = new GetCollectionFieldsRequest.Builder(environmentId, collectionId).build();
GetCollectionFieldsResponse getResponse = discovery.getCollectionFields(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

collection_fields = discovery.list_collection_fields('{environment_id}', '{collection_id}')
print(json.dumps(collection_fields, indent=2))
Node example not currently available.

Response

Node information not currently available.

Returns an array that lists each the field and type of each field in the specified collection's index.

Name Description
fields string[ ] An array containing information about each field in the collection.
field string The name of the field.
type string The type of the field.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

Node response not currently available.

Example response

{
  "fields": [ {
  "type" : "english",
  "field" : "b8ff3c68-591c-4abc-b6ba-3975c233cecc.mappings.document._all.analyzer"
}, {
  "type" : "nested",
  "field" : "extracted_metadata"
}, {
  "type" : "string",
  "field" : "html"
}, {
  "type" : "english",
  "field" : "html.analyzer"
}, {
  "type" : "string",
  "field" : "text"
}, {
  "type" : "english",
  "field" : "text.analyzer"
}, {
  "type" : "string",
  "field" : "extracted_metadata.properties.file_type"
}, {
  "type" : "english",
  "field" : "extracted_metadata.properties.file_type.analyzer"
}, {
  "type" : "string",
  "field" : "extracted_metadata.properties.filename"
}, {
  "type" : "english",
  "field" : "extracted_metadata.properties.filename.analyzer"
}, {
  "type" : "string",
  "field" : "extracted_metadata.properties.sha1"
}, {
  "type" : "english",
  "field" : "extracted_metadata.properties.sha1.analyzer"
}, {
  "type" : "string",
  "field" : "extracted_metadata.properties.title"
}, {
  "type" : "english",
  "field" : "extracted_metadata.properties.title.analyzer"
} ]
}

Delete a collection

Deletes an existing collection.

DELETE /v1/environments/{environment_id}/collections/{collection_id}

Request

Name Description
environment_id path string The unique identifier of the environment in which the collection is located.
collection_id path string The unique identifier of the collection you want to delete.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -u "{username}":"{password}" -X DELETE  "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";

DeleteCollectionRequest deleteRequest = new DeleteCollectionRequest.Builder(environmentId, collectionId).build();
DeleteCollectionResponse deleteResponse = discovery.deleteCollection(deleteRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

delete_collection = discovery.delete_collection('{environment_id}', '{collection_id}')
print(json.dumps(delete_collection, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.deleteCollection(('{environment_id}', '{collection_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns the collection ID and the status of the deletion process.

Name Description
collection_id string The unique identifier of the collection that is being deleted.
status string The status of the collection. The status of a successful deletion operation is deleted.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

{
  "collection_id": "44e29a9a-47e3-4acd-874b-c7cbe04043f1",
  "status": "deleted"
}

Documents

Add and update documents in your collection.

Add a document

Add a document to your collection.

Note: When you add a document, you can do one and only one of the following:

  • Specify a configuration by using the configuration parameter with the appropriate formData (configuration=)

  • Specify a configuration ID by using the configuration_id parameter with the unique ID of an existing configuration (configuration_id=)

  • Specify neither the configuration nor the configuration_id parameter. When neither parameter is specified, the service uses the collection's assigned default configuration.

If you specify both the configuration and the configuration_id parameter, the service rejects the request.

POST /v1/environments/{environment_id}/collections/{collection_id}/documents

Request

Name Description
environment_id path string The unique identifier of the environment into which to ingest the document.
collection_id path string The unique identifier of the collection into which to ingest the document.
configuration_id query string The unique identifier of the configuration used to process the document. See the note at the top of this method's reference page for more information.
configuration formData file The name of the configuration used to process the document. See the note at the top of this method's reference page for more information. See Add a configuration for an example configuration JSON file.
file formData file The document to ingest. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/html, and application/xhtml+xml. Specify content type in the multipart form as type=.
metadata formData file JSON object specifying metadata related to the document. If this parameter is not specified, you must specify the file parameter.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environmentId path string The unique identifier of the environment into which to ingest the document.
collectionId path string The unique identifier of the collection into which to ingest the document.
configurationId query string The unique identifier of the configuration you want to use on the document.
documentJson JsonObject string JSON object specifying metadata related to the document.
documentStream InputStream file The document to ingest specified as an InputStream. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are APPLICATION_JSON, APPLICATION_MS_WORD, APPLICATION_MS_WORD_DOCX, APPLICATION_VXML, APPLICATION_PDF, TEXT_HTML, and APPLICATION_XHTML_XML. Specify content type in the Java call as HttpMediaType.

You can specify the document by using either this parameter or the fileName parameter. Do not specify both parameters in the same call.

fileName query string The filename of the document to ingest specified as a string. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are APPLICATION_JSON, APPLICATION_MS_WORD, APPLICATION_MS_WORD_DOCX, APPLICATION_VXML, APPLICATION_PDF, TEXT_HTML, and APPLICATION_XHTML_XML. Specify content type in the Java call as HttpMediaType.

You can specify the document by using either this parameter or the documentStream parameter. Do not specify both parameters in the same call.

documentId query string A unique identifier for the document that is to be added. You can reference this ID for the specific document in other document-related API calls.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environment_id path string The unique identifier of the environment into which to ingest the document.
collection_id path string The unique identifier of the collection into which to ingest the document.
file_info filepath string Filepath to the document that is to be ingested. You must specify either this parameter or the file_data parameter.

The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify with the mime_type parameter if the type is incorrect.

file_data formData string The document to ingest. You must specify either this parameter or the file_info parameter.

The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify with the mime_type parameter if the type is incorrect.

mime_type query string Optional MIME type of the document to be ingested. Acceptable MIME type values are APPLICATION_JSON, APPLICATION_MS_WORD, APPLICATION_MS_WORD_DOCX, APPLICATION_VXML, APPLICATION_PDF, TEXT_HTML, and APPLICATION_XHTML_XML.

If the MIME type is not specified, the method uses the Python mimetypes.guess_type() function to determine the document type based on the extension of the filename.

metadata JsonObject string Optional JSON object specifying metadata related to the document.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
Name Description
environment_id path string The unique identifier of the environment into which to ingest the document.
collection_id path string The unique identifier of the collection into which to ingest the document.
configuration_id query string The unique identifier of the configuration you want to use on the document.
file path file The document to ingest, represented as a path to a JavaScript ReadableStream or Object. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if the detection is incorrect. Accepted MIME type values are application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/html, and application/xhtml+xml.
metadata string file JSON object specifying metadata related to the document. If this parameter is not specified, you must specify the file parameter; additionally, the method detects the metadata (document type) of the file being ingested.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -X POST -u "{username}":"{password}" -F file=@sample1.html "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/documents?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";
String configurationId = "{configuration_id}";
String documentId = "{document_id}";
String documentJson = "{\"field\":\"value\"}";
InputStream documentStream = new ByteArrayInputStream(documentJson.getBytes());

CreateDocumentRequest.Builder builder = new CreateDocumentRequest.Builder(environmentId, collectionId, configurationId);
builder.inputStream(documentStream, HttpMediaType.APPLICATION_JSON);
CreateDocumentResponse createResponse = discovery.createDocument(builder.build()).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

with open((os.path.join(os.getcwd(), '{path_element}', '{filename}' as fileinfo:
  add_doc = discovery.add_document('{environment_id}', '{collection_id}', file_info=fileinfo)
print(json.dumps(add_doc, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');
var fs = require('fs');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

var file = fs.readFileSync('{/path/to/file}');

discovery.addDocument(('{environment_id}', '{collection_id}', file),
function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Download sample1.html

Response

Returns the document ID and ingestion status.

Name Description
status string Status of the document in the ingestion process.
document_id string The unique identifier of the ingested document.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request if the request is incorrectly formatted. The error message provides information about the reason for the rejection of the request.
404 Not Found The request specified a resource that was not found

Example response

{
  "status": "processing",
  "document_id": "45556e23-f2b1-449d-8f27-489b514000ff"
}

Update a document

Update or partially update a document to create or replace an existing document.

This is a POST operation instead of a PUT operation because an existing document can be partially updated, depending on whether or not the new document is successfully ingested, as described in the following list.

Assuming a document with the specified document_id already exists, the original document is processed as follows:

  • If ingestion of the new document fails, the original document is retained without alterations in the collection's index. However, any notices (warnings or errors) that were stored upon the ingestion of the original document are replaced with notices generated by the attempted ingestion of the new document.

  • If the new document is successfully ingested, the original document and all of its notices are replaced in the collection's index.

Only the document_id from the API request is used. If you provide a document_id as part of a submitted JSON input document, it is ignored.

You must provide document content, metadata, or both. If the request is missing both document content and metadata, it is rejected.

The method returns immediately after the service has accepted the document for processing.

You can optionally set the Content-Type parameter on the file input to indicate the media type of the document. If the Content-Type parameter is not specified or if the document is a generic media type (for example, application/octet-stream), the service attempts to detect the document's media type automatically.

The method is overloaded. The documentation for the method is for the full-featured version of the operation. The simpler version of the operation works as follows:

  • You can provide the content of the document in the body of the request instead of specifying a multipart/form-data field (that is, the file or metadata parameter).

  • You can optionally set the Content-Type parameter to indicate the media type of the document. If the Content-Type parameter is not specified or if the document is a generic media type (for example, application/octet-stream), the service attempts to detect the document's media type automatically.

  • The version parameter is still required.

POST /v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}

Request

Name Description
environment_id path string The unique identifier of the environment into which to ingest the document.
collection_id path string The unique identifier of the collection into which to ingest the document.
document_id path string The unique identifier of the document that is to be replaced.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
file formData file The content of the document to ingest. If this parameter is not specified, you must specify the metadata parameter.
metadata formData string JSON object specifying metadata related to the document. If this parameter is not specified, you must specify the file parameter.
Name Description
environmentId path string The unique identifier of the environment into which to ingest the document.
collectionId path string The unique identifier of the collection into which to ingest the document.
documentId path string The unique identifier of the document that is to be replaced.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
documentStream InputStream file The document to ingest specified as an InputStream. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are APPLICATION_JSON, APPLICATION_MS_WORD, APPLICATION_MS_WORD_DOCX, APPLICATION_VXML, APPLICATION_PDF, TEXT_HTML, and APPLICATION_XHTML_XML. Specify content type in the Java call as HttpMediaType.

You can specify the document by using either this parameter or the fileName parameter. Do not specify both parameters in the same call.

fileName query string The filename of the document to ingest specified as a string. The maximum supported file size is 50 megabytes. Files larger than 50 megabytes are rejected. The API detects the document type, but you can specify it if incorrect. Acceptable MIME type values are APPLICATION_JSON, APPLICATION_MS_WORD, APPLICATION_MS_WORD_DOCX, APPLICATION_VXML, APPLICATION_PDF, TEXT_HTML, and APPLICATION_XHTML_XML. Specify content type in the Java call as HttpMediaType.

You can specify the document by using either this parameter or the documentStream parameter. Do not specify both parameters in the same call.

documentJson JsonObject string JSON object specifying metadata related to the document. If this parameter is not specified, you must specify the documentStream parameter.

Python method not currently available.

Node method not currently available.

Example request

curl -X POST -u "{username}":"{password}" -F "file=@1.html;type=text/html" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";
String documentId = "{document_id}";
String updatedDocumentJson = "{\"field\":\"value2\"}";
InputStream updatedDocumentStream = new ByteArrayInputStream(updatedDocumentJson.getBytes());

UpdateDocumentRequest.Builder updateBuilder = new UpdateDocumentRequest.Builder(environmentId, collectionId, documentId);
updateBuilder.inputStream(updatedDocumentStream, HttpMediaType.APPLICATION_JSON);
UpdateDocumentResponse updateResponse = discovery.updateDocument(updateBuilder.build()).execute();
Python example not currently available.
Node example not currently available.

Response

Response not currently available.

Returns the document ID and processing status.

Name Description
document_id string The unique identifier of the ingested document.
notices string[ ] Array of notices produced by the document-ingestion process.
status string Status of the document in the ingestion process.
status_description string Description of the document status.
notices
Name Description
notice_id string Identifier of the notice.
created string The creation date of the notice, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
document_id string The unique identifier of the document associated with the notice.
severity string Severity level of the notice.
step string Ingestion step in which the notice occurred.
description string Description of the notice.
details object Arbitrary JSON with details that might help you troubleshoot the notice.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request if the request is incorrectly formatted. The error message provides information about the reason for the rejection of the request.
404 Not Found The request specified a resource that was not found

Example response

{
  "notices": [],
  "status": "active",
  "status_description": "Document is successfully ingested and indexed with no warnings",
  "document_id": "45556e23-f2b1-449d-8f27-489b514000ff"
}

List document details

Display status information about a submitted document.

GET /v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}

Request

Node request not currently available.

Name Description
environment_id path string The unique identifier of the environment where the document is located.
collection_id path string The unique identifier of the collection where the document is located.
document_id path string The unique identifier of the document.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";
String documentId = "{document_id}";

GetDocumentRequest getRequest = new GetDocumentRequest.Builder(environmentId, collectionId, documentId).build();
GetDocumentResponse getResponse = discovery.getDocument(getRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

doc_info = discovery.get_document('{environment_id}', '{collection_id}', '{document_id}')
print(json.dumps(doc_info, indent=2))
Node method not currently available.

Response

Node response not currently available.

Returns the document ID, configuration ID, document creation date, date of last document update, submission status, and notices associated with the document's submission.

Name Description
notices string[ ] Array of notices produced by the document-ingestion process.
status string Status of the document in the ingestion process.
status_description string Description of the document status.
document_id string The unique identifier of the ingested document.
notices
Name Description
notice_id string Identifier of the notice.
created string The creation date of the notice, in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
document_id string The unique identifier of the document associated with the notice.
severity string Severity level of the notice.
step string Ingestion step in which the notice occurred.
description string Description of the notice.
details object Arbitrary JSON with details that can help you troubleshoot the notice.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

{
  "notices": [],
  "status": "available",
  "status_description": "Document is successfully ingested and indexed with no warnings",
  "document_id": "45556e23-f2b1-449d-8f27-489b514000ff"
}

Delete a document

Delete a document from a collection.

DELETE /v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}

Request

Name Description
environment_id path string The unique identifier of the environment where the document is located.
collection_id path string The unique identifier of the collection where the document is located.
document_id path string The unique identifier of the document.
version query date The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/documents/{document_id}?version=2017-07-19"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";
String documentId = "{document_id}";

DeleteDocumentRequest deleteRequest = new DeleteDocumentRequest.Builder(environmentId, collectionId, documentId).build();
DeleteDocumentResponse deleteResponse = discovery.deleteDocument(deleteRequest).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

delete_doc = discovery.delete_document('{environment_id}', '{collection_id}', '{document_id}')
print(json.dumps(delete_doc, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.deleteDocument(('{environment_id}', '{collection_id}', '{document_id}'), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns the document ID, configuration ID, document creation date, date of last document update, submission status, and notices associated with the document's submission.

Name Description
document_id string The unique identifier of the document.
status string Status of the document. A deleted document has the status deleted.

Response codes

Status Description
200 OK Successful request or The request specified a resource that was not found
400 Bad Request Invalid request

Example response

{
  "document_id": "8691f0dd-7181-45b7-81de-5cb16206b3a1",
  "status": "deleted",
}

Queries

Query the documents in your collection.

Query your collection

After your content is uploaded and enriched by the Discovery service, you can build queries to search your content. For a deep dive into queries, see Building queries and delivering content.

GET /v1/environments/{environment_id}/collections/{collection_id}/query

Request

Name Description
environment_id query string The unique identifier for this environment.
collection_id query string The unique identifier for this collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
filter query string A cacheable query that limits the documents returned to exclude any documents that do not mention the query content. Filter searches are better for metadata searches and when you are trying to get a sense of concepts in the data set.
query query string Returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first. Use a query search when you want to find the most relevant search results. You cannot use this parameter and the natural_language_query parameter in the same query.
natural_language_query query string A natural language query that returns relevant documents by using training data and natural language understanding. You cannot use this parameter and the query parameter in the same query.
aggregation query string A search that uses a combination of query, natural language query, and filter searches to return an exact answer. Aggregations can be used to build structures such as lists, tables, and time series, and are therefore useful for building applications. For more information about aggregations, see Building aggregations.
count query integer Sets the number of documents that you want returned in the response.
return query string A comma-separated list of the portion of the document hierarchy to return. Any of the document hierarchy are valid values.
offset query string The number of query results to omit from the start of the output. For example, if the count parameter is set to 10 and the offset parameter is set to 8, the query returns only the last two results. Do not use this parameter for deep pagination, as it impedes performance.

Note: Watson Discovery News returns results in batches of 50. Use the offset parameter to page through results.

sort query string A comma-separated list of fields in the document to sort on. You can optionally specify a sort direction by prefixing the field with - for descending order or + for ascending order. Ascending order is the default sort direction if you do not specify a prefix.
passages query boolean A boolean that specifies whether the service returns a set of the most relevant passages from the documents returned by a query. The default is false.
Note: The passages parameter is supported only on private collections. It is not supported in the Watson Discovery News collection.
highlight query boolean A boolean that specifies whether the output includes a highlight object in which the keys are field names and the values are arrays that contain segments of query-matching text highlighted by the HTML <em> tag. The default is false.
Name Description
environment_id query string The unique identifier for this environment.
collection_id query string The unique identifier for this collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
query_options query string | dictionary Specifies the parameters of the query.

In Java and Node, specify this as a query string. In Python, specify this as a Python dictionary.

See the query options table for information about the contents of the string or dictionary.

Query options
Name Description
query query string Returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first. Use a query search when you want to find the most relevant search results. You cannot use this parameter and the natural_language_query parameter in the same query.
natural_language_query query string A natural language query that returns relevant documents by using training data and natural language understanding. You cannot use this parameter and the query parameter in the same query.
filter query string A cacheable query that can exclude information that is unrelated to your search terms. Filter searches are better than query searches for metadata type searches and for getting a sense of concepts in the collection's documents.
aggregation query string A search that uses a combination of query and filter searches to return an exact answer. Aggregations can be used to build structures such as lists, tables, and time series, and are therefore useful for building applications. For more information about aggregations, see Building aggregations.
count query integer The number of documents to return. The default is 10.
return query string A comma-separated list of the portion of the document hierarchy to return.
offset query integer The number of query results to omit from the start of the output. For example, if the count parameter is set to 10 and the offset parameter is set to 8, the query returns only the last two results. Do not use this parameter for deep pagination, as it impedes performance.

Note: Watson Discovery News returns results in batches of 50. Use the offset parameter to page through results.

return query string A comma-separated list of the portion of the document hierarchy to return.
sort query string A comma-separated list of fields in the document to sort on. You can optionally specify a sort direction by prefixing the field with - for descending order or + for ascending order. Ascending order is the default sort direction if you do not specify a prefix.
passages query boolean A boolean that specifies whether the service returns a set of the most relevant passages from the documents returned by a query. The default is false.
Note: The passages parameter is supported only on private collections. It is not supported in the Watson Discovery News collection.
highlight query boolean A boolean that specifies whether the output includes a highlight object in which the keys are field names and the values are arrays that contain segments of query-matching text highlighted by the HTML <em> tag. The default is false.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/query?version=2017-07-19&query=relations.action.lemmatized:acquire&count=15&filter=entities.text:IBM&return=text"

Discovery discovery = new Discovery("2017-07-19");
discovery.setEndPoint("https://gateway.watsonplatform.net/discovery/api/v1");
discovery.setUsernameAndPassword("{username}", "{password}");
String environmentId = "{environment_id}";
String collectionId = "{collection_id}";

QueryRequest.Builder queryBuilder = new QueryRequest.Builder(environmentId, collectionId);
queryBuilder.query("{field}:{value}");
QueryResponse queryResponse = discovery.query(queryBuilder.build()).execute();
import sys
import os
import json
from watson_developer_cloud import DiscoveryV1

discovery = DiscoveryV1(
  username="{username}",
  password="{password}",
  version="2017-07-19"
)

qopts = {'query': '{query_string}', 'filter': '{filter_string}', ...}
my_query = discovery.query('{environment_id}', '{collection_id}', qopts)
print(json.dumps(my_query, indent=2))
var DiscoveryV1 = require('watson-developer-cloud/discovery/v1');

var discovery = new DiscoveryV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-07-19'
});

discovery.query({'{environment_id}', '{collection_id}', '{query_string}'}), function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Response

Returns the content requested in the query.

Output
Name Description
text string[ ] An array of responses to the user that follows the format {"text":["{response_1}","{response_2}","{response_n}"]}. Returns an empty array if no responses are returned.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response

Download a full example response

Query ingestion notices

After your content is uploaded and enriched by the Discovery service, you can build queries to search any notices (warnings and errors) generated by the ingestion process. For a deep dive into queries, see Building Queries and Delivering Content.

GET /v1/environments/{environment_id}/collections/{collection_id}/notices

Request

Request parameters not currently available.

Name Description
environment_id query string The unique identifier for this environment.
collection_id query string The unique identifier for this collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
filter query string A cacheable query that limits the notices returned to exclude any notices that do not mention the query content. Filter searches are better for metadata searches.
query query string Returns all notices in your data set with full text, but with the most relevant documents listed first. Use a query search when you want to find the most relevant search results. You cannot use this parameter and the natural_language_query parameter in the same query.
natural_language_query query string A natural language query that returns relevant notices by using training data and natural language understanding. You cannot use this parameter and the query parameter in the same query.
aggregation query string A search that uses a combination of query, natural language query, and filter searches to return an exact answer. Aggregations can be used to build structures such as lists, tables, and time series, and are therefore useful for building applications. For more information about aggregations, see Building aggregations.
count query integer Sets the number of notices that you want to have returned in the response.
return query string A comma-separated list of the portion of the document hierarchy to return.
offset query string The number of query results to omit from the start of the output. For example, if the count parameter is set to 10 and the offset parameter is set to 8, the query returns only the last two results. Do not use this parameter for deep pagination, as it impedes performance.
sort query string A comma-separated list of fields in the notices to sort on. You can optionally specify a sort direction by prefixing the field with - for descending order or + for ascending order. Ascending order is the default sort direction if you do not specify a prefix.
passages query boolean A boolean that specifies whether the service returns a set of the most relevant passages from the documents returned by a query. The default is false.
Note: The passages parameter is supported only on private collections. It is not supported in the Watson Discovery News collection.
highlight query boolean A boolean that specifies whether the output includes a highlight object in which the keys are field names and the values are arrays that contain segments of query-matching text highlighted by the HTML <em> tag. The default is false.

Response

Example response not currently available.

Returns the content requested in the query.

Output
Name Description
text string[ ] An array of responses to the user that follows the format {"text":["{response_1}","{response_2}","{response_n}"]}. Returns an empty array if no responses are returned.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Response codes not currently available.

Example response

Example response not currently available.

{
  "matching_results": 24,
  "results": [
    {
      "id": "030ba125-29db-43f2-8552-f941ae30a7a8",
      "code": 200,
      "score": 1,
      "filename": "instructions.html",
      "file_type": "html",
      "sha1": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
      "notices": [
        {
          "notice_id": "xpath_not_found",
          "created": "2016-09-20T17:26:17.000Z",
          "document_id": "030ba125-29db-43f2-8552-f941ae30a7a8",
          "severity": "warning",
          "step": "html-to-html",
          "description": "The xpath expression \"boom\" was not found."
        }
      ]
    }
  ],
  "aggregations": {
    "term": {
      "results": [
        {
          "key": "warning",
          "matching_results": 34
        }
      ]
    }
  }
}

Training data

Add training data to your collection to improve the relevance of query results.

Note: When working with training data, use the training array returned by the list collection details method to check the status of training, including the number of training-data examples, whether the service has enough valid training data to provide improved relevance of returned results, and other relevance-training details. See Improving the relevance of your query results with the API for procedural information on using relevance training.

Add a query to the training data for a collection

Adds a query to the training data for a collection. The query can be any Discovery query that is valid for the collection.

POST /v1/environments/{environment_id}/collections/{collection_id}/training_data

Request

Name Description
environment_id query string The unique identifier for the environment.
collection_id query string The unique identifier for the collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
body body string (JSON) The body of the training-data query that is to be added to the collection's training data, as described in the following table.
body
Name Description
natural_language_query query string The natural language query to use as training data.
example query string [ ] (JSON object) The defintion of the training example to use for the natural language query, as described in the following table.
filter string Optional filter for the training-data query.
example
Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label, typically consisting of a field in the referenced document, that "pins" the document and the field's information in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID. Specifying a value for cross-reference does not link one document to another; rather, it ensures that the service retains the document's pertinent information in case the document gets renamed or overwritten.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Request not currently available.

curl -X POST -u "{username}":"{password}" -d
'{
  "natural_language_query": "who is keyser soze",
  "filter": "text:criminology",
  "examples": [
    {
      "document_id": "adaf50f1-2526-4fad-b670-7d6e8a42e6e6",
      "relevance": 2
    },
    {
      "document_id": "63919442-7d5b-4cae-ab7e-56f58b1390fe",
      "cross_reference": "my_id_field:14",
      "relevance": 4
    }
  ]
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data?version=2017-07-19"

Example training-data query file

{
  "natural_language_query": "{natural_language_query}",
  "filter": "{filter_definition}"
  "examples": [
    {
      "document_id": "{document_id_1}",
      "cross_reference": "{cross_reference_1}",
      "relevance": 0
    },
    {
      "document_id": "{document_id_2}",
      "cross_reference": "{cross_reference_2}",
      "relevance": 0
    }
  ]
}

Request not currently available.

Response

Returns the following information about the training-data query: its unique ID, its natural-language query, its filter if any, and the examples it contains. Examples are contained in an array. Each object in the array lists the contents of the example, including the document ID, the cross reference if any, and the relevance score.

Name Description
query_id string Unique ID of the training-data query. This ID is assigned by the service when the query is created.
natural_language_query string Natural-language query used by the training-data query.
filter string Filter for the training-data query.
examples string[ ] An array containing objects; each object describes a training-data query example.
examples
Name Description
document_id string The unique ID of the document to which the training-data example applies.
cross_reference string An optional label that "pins" the document in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Response not currently available.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

{
  "query_id": "string",
  "natural_language_query": "string",
  "filter": "string",
  "examples": [
    {
      "document_id": "string",
      "cross_reference": "string",
      "relevance": 0
    }
  ]
}

Example response not currently available.

List the training data for a collection

Lists the training data for the specified collection.

GET /v1/environments/{environment_id}/collections/{collection_id}/training_data

Request

Name Description
environment_id query string The unique identifier for the environment.
collection_id query string The unique identifier for the collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Request not currently available.

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data?version=2017-07-19"

Request not currently available.

Response

Returns the environment ID, collection ID, and an array that lists the training-data query definitions for the collection.

Name Description
environment_id string Unique ID of the environment.
collection_id string Unique ID of the collection.
queries string[ ] An array containing objects; each object describes a training-data query.
queries
Name Description
query_id string Unique ID of the query.
natural_language_query string The natural language query string.
filter string Filter for the training-data query.
examples string[ ] An array containing objects; each object describes a training-data example.
examples
Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label that "pins" the document in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Response not currently available.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

{
  "environment_id": "string",
  "collection_id": "string",
  "queries": [
    {
      "query_id": "string",
      "natural_language_query": "string",
      "filter": "string",
      "examples": [
        {
          "document_id": "string",
          "cross_reference": "string",
          "relevance": 0
        }
      ]
    }
  ]
}

Example response not currently available.

Delete all training data from a collection

Deletes all training data from a collection.

DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data

Request

Name Description
environment_id query string The unique identifier for the environment.
collection_id query string The unique identifier for the collection.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Request not currently available.

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data?version=2017-07-19"

Request not currently available.

Response

If the method does not return a response, all training data was successfully removed from the collection. You can verify a successful call by checking the HTTP status code; the code 204 indicates success.

Response not currently available.

Response codes

Status Description
204 OK All training data removed
400 Bad Request Invalid request

Response codes not currently available.

Example response

No response; check the HTTP response code.

Example response not currently available.

Add an example to a training-data query

Adds an example to an existing training-data query for a collection.

POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples

Request

Name Description
environment_id path string The unique identifier for the environment.
collection_id path string The unique identifier for the collection.
query_id path string The unique identifier of the query to which the example is to be added.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
body body string (JSON) The body of the example that is to be added to the specified query, as described in the following table.
Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label, typically consisting of a field in the referenced document, that "pins" the document and the field's information in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID. Specifying a value for cross-reference does not link one document to another; rather, it ensures that the service retains the document's pertinent information in case the document gets renamed or overwritten.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Request not currently available.

curl -X POST -u "{username}":"{password}" -d
'{
  "document_id": "{document_id}",
  "cross_reference": "{cross_reference}",
  "relevance": 0
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples?version=2017-07-19"

Model of example for training-data query

{
  "document_id": "{document_id}",
  "cross_reference": "{cross_reference}",
  "relevance": 0
}

Request not currently available.

Response

Returns the new example's document ID, cross reference, and relevance score.

Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label, typically consisting of a field in the referenced document, that "pins" the document and the field's information in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID. Specifying a value for cross-reference does not link one document to another; rather, it ensures that the service retains the document's pertinent information in case the document gets renamed or overwritten.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Response not currently available.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

{
  "document_id": "string",
  "cross_reference": "string",
  "relevance": 0
}

Example response not currently available.

Display details about a specified query

Display details about a specific query, including the query string and all examples

GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}

Request

Name Description
environment_id path string The unique identifier for the environment.
collection_id path string The unique identifier for the collection.
query_id path string The unique identifier of the query.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Request not currently available.

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}?version=2017-07-19"

Request not currently available.

Response

Returns detailed information about the specified query.

Name Description
query_id string Unique ID of the query.
natural_language_query string The natural language query string.
filter string Filter for the training-data query.
examples string[ ] An array containing objects; each object describes a training-data example.
created date Creation date of the example.
examples
Name Description
document_id string The unique ID of the document to which the query applies.
cross_reference string An optional label that "pins" the document in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID.
relevance integer The relevance score of the query example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.

Response not currently available.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

{
  "query_id": "string",
  "natural_language_query": "string",
  "filter": "string",
  "examples": [
    {
      "document_id": "string",
      "cross_reference": "string",
      "relevance": 0
    },
    {
      "document_id": "string",
      "cross_reference": "string",
      "relevance": 3
    },
    {
      "document_id": "string",
      "cross_reference": "string",
      "relevance": 4
    }
  ]
}

Example response not currently available.

Delete a training-data query

Removes the query and all of its associated examples from the training-data set.

DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}

Request

Name Description
environment_id path string The unique identifier for the environment.
collection_id path string The unique identifier for the collection.
query_id path string The unique identifier of the query that is to be deleted.
version date string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Request not currently available.

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}?version=2017-07-19"

Request not currently available.

Response

If the method does not return a response, the query and all example document references were successfully removed from the training set. You can verify a successful call by checking the HTTP status code; the code 204 indicates success.

Response not currently available.

Response codes

Status Description
204 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

No response; check the HTTP response code.

Example response not currently available.

Change an example's label or cross reference

Change the label or cross-reference query for the specified example.

PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}

Request

Name Description
environment_id path string The unique identifier for the environment.
collection_id path string The unique identifier for the collection.
query_id path string The unique identifier of the query whose example is to be changed.
example_id path string The unique identifier of the indexed document that is to be updated.
version date string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.
body body string (JSON) The body of the example that is to be added to the specified query, as described in the following table.
body
Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label, typically consisting of a field in the referenced document, that "pins" the document and the field's information in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID. Specifying a value for cross-reference does not link one document to another; rather, it ensures that the service retains the document's pertinent information in case the document gets renamed or overwritten.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.
Note: Although the range of the relevance parameter is 0 to 100 for maximum flexibility, we recommend that you start with a smaller range to simplify scoring examples. A standard range might be 0 to 4.

Request not currently available.

curl -X PUT -u "{username}":"{password}" -d
'{
  "document_id": "string",
  "cross_reference": "{new_cross_reference}",
  "relevance": 3
}' "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}?version=2017-07-19"

Model of example for training-data query

{
  "document_id": "{document_id}",
  "cross_reference": "{cross_reference}",
  "relevance": 0
}

Request not currently available.

Response

Returns the document ID, cross reference ID, and relevance score of the updated example.

examples
Name Description
document_id string The unique ID of the document to which the training example applies.
cross_reference string An optional label that "pins" the document in place in the event the document's ID changes, for example if a newly ingested document is assigned the same ID.
relevance integer The relevance score of the training example in the referenced document, expressed as a value between 0 and 100, with 0 meaning completely irrelevant and 100 meaning completely relevant.

Response not currently available.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

{
  "document_id": "string",
  "cross_reference": "string",
  "relevance": 0
}

Example response not currently available.

Delete an example document

Delete the example document with the specified ID from the query.

DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}

Request

Name Description
environment_id path string The unique identifier for the environment.
collection_id path string The unique identifier for the collection.
query_id path string The unique identifier of the query whose example is to be deleted.
example_id path string The unique identifier of the indexed document that is to be deleted.
version date string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-07-19.

Request not currently available.

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/discovery/api/v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}?version=2017-07-19"

Request not currently available.

Response

If the method does not return a response, the example document was successfully removed from the training set. You can verify a successful call by checking the HTTP status code; the code 204 indicates success.

Response not currently available.

Response codes

Status Description
204 OK Successful request
400 Bad Request Invalid request

Response codes not currently available.

Example response

No response; check the HTTP response code.

Example response not currently available.

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out header parameter to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access. set the X-Watson-Learning-Opt-Out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access. set the x-watson-learning-opt-out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access. For more information, see Controlling request logging for Watson services.

Error handling

The Discovery service uses standard HTTP response codes to display whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Common exceptions thrown

The WatsonException exception catches the error message from the API response.

Exception Description
IllegalArgumentException An illegal or null argument was passed to a method.
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)

Error format

Name Description
code Error code.
error Error description.

Example error

{
  "code": 404,
  "error": "Resource not found"
}