Create an environment

POST /v1/environments

Creates a new environment for private data. An environment must be created before collections can be created.

Note: You can create only one environment for private data per service instance. An attempt to create another environment results in an error.

Request

Request Body

CreateEnvironmentRequest

An object that defines an environment name and optional description. The fields in this object are not approved for personal information and cannot be deleted based on customer ID.

name

Required *

string

Name that identifies the environment.

description

string

Description of the environment.

size

string

Size of the environment. In the Lite plan the default and only accepted value is `LT`, in all other plans the default is `S`

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - Environment successfully added.

environment_id

string

Unique identifier for the environment.

name

string

Name that identifies the environment.

description

string

Description of the environment.

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

Current status of the environment. `resizing` is displayed when a request to increase the environment size has been made, but is still in the process of being completed.

read_only

boolean

If `true`, the environment contains read-only collections that are maintained by IBM.

size

string

Current size of the environment.

requested_size

string

The new size requested for this environment. Only returned when the environment status is `resizing`.

Note: Querying and indexing can still be performed during an environment upsize.

index_capacity

IndexCapacity

Details about the resource usage and capacity of the environment.

search_status

SearchStatus

Information about the Continuous Relevancy Training for this environment.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List environments

GET /v1/environments

List existing environments for the service instance.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

name

string

Show only the environment with the given name.

Response

200 - Successful response.

environments

array

An array of [environments] that are available for the service instance.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get environment info

GET /v1/environments/{environment_id}

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Environment fetched.

environment_id

string

Unique identifier for the environment.

name

string

Name that identifies the environment.

description

string

Description of the environment.

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

Current status of the environment. `resizing` is displayed when a request to increase the environment size has been made, but is still in the process of being completed.

read_only

boolean

If `true`, the environment contains read-only collections that are maintained by IBM.

size

string

Current size of the environment.

requested_size

string

The new size requested for this environment. Only returned when the environment status is `resizing`.

Note: Querying and indexing can still be performed during an environment upsize.

index_capacity

IndexCapacity

Details about the resource usage and capacity of the environment.

search_status

SearchStatus

Information about the Continuous Relevancy Training for this environment.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update an environment

PUT /v1/environments/{environment_id}

Updates an environment. The environment's name and description parameters can be changed. You must specify a name for the environment.

Request

Request Body

UpdateEnvironmentRequest

An object that defines the environment's name and, optionally, description.

name

string

Name that identifies the environment.

description

string

Description of the environment.

size

string

Size to change the environment to. Note: Lite plan users cannot change the environment size.

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Environment successfully updated.

environment_id

string

Unique identifier for the environment.

name

string

Name that identifies the environment.

description

string

Description of the environment.

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

Current status of the environment. `resizing` is displayed when a request to increase the environment size has been made, but is still in the process of being completed.

read_only

boolean

If `true`, the environment contains read-only collections that are maintained by IBM.

size

string

Current size of the environment.

requested_size

string

The new size requested for this environment. Only returned when the environment status is `resizing`.

Note: Querying and indexing can still be performed during an environment upsize.

index_capacity

IndexCapacity

Details about the resource usage and capacity of the environment.

search_status

SearchStatus

Information about the Continuous Relevancy Training for this environment.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to update a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete environment

DELETE /v1/environments/{environment_id}

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Environment successfully deleted.

environment_id

string

The unique identifier for the environment.

status

string

Status of the environment.

400 - Bad request.

Example error messages:

  • `Invalid environment id. Please check if the format is correct.`

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to delete a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Returned any time the environment is not found (even immediately after the environment was successfully deleted).

Example error message:

`An environment with ID '2cd8bc72-d737-46e3-b26b-05a585111111' was not found.`

code

integer

The HTTP error status code.

error

string

A message describing the error.

Add configuration

POST /v1/environments/{environment_id}/configurations

Creates a new configuration.

If the input configuration contains the configuration_id, created, or updated properties, then they are ignored and overridden by the system, and an error is not returned so that the overridden fields do not need to be removed when copying a configuration.

The configuration can contain unrecognized JSON fields. Any such fields are ignored and do not generate an error. This makes it easier to use 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.

Request

Request Body

Configuration

Input an object that enables you to customize how your content is ingested and what enrichments are added to your data.

name is required and must be unique within the current environment. All other properties are optional.

If the input configuration contains the configuration_id, created, or updated properties, then they will be ignored and overridden by the system (an error is not returned so that the overridden fields do not need to be removed when copying a configuration).

The configuration can contain unrecognized JSON fields. Any such fields will be ignored and will not generate an error. This makes it easier to use 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.

configuration_id

string

The unique identifier of the configuration

name

Required *

string

The name of the configuration.

created

string

The creation date of the configuration in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

updated

string

The timestamp of when the configuration was last updated in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

description

string

The description of the configuration, if available.

conversions

Conversions

Document conversion settings.

pdf

object

A list of PDF conversion settings.

word

object

A list of Word conversion settings.

html

object

A list of HTML conversion settings.

segment

object

A list of Document Segmentation settings.

json_normalizations

array

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

image_text_recognition

boolean

When `true`, automatic text extraction from images (this includes images embedded in supported document formats, for example PDF, and suppported image formats, for example TIFF) is performed on documents uploaded to the collection. This field is supported on Advanced and higher plans only. Lite plans do not support image text recognition.

enrichments

Enrichments

An array of document enrichment settings for the configuration.

normalizations

Normalizations

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

source

Source

Object containing source parameters for the configuration.

type

string

The type of source to connect to.

  • `box` indicates the configuration is to connect an instance of Enterprise Box.
  • `salesforce` indicates the configuration is to connect to Salesforce.
  • `sharepoint` indicates the configuration is to connect to Microsoft SharePoint Online.
  • `web_crawl` indicates the configuration is to perform a web page crawl.
  • `cloud_object_storage` indicates the configuration is to connect to a cloud object store.
credential_id

string

The credential_id of the credentials to use to connect to the source. Credentials are defined using the credentials method. The source_type of the credentials used must match the type field specified in this object.

schedule

object

Object containing the schedule information for the source.

options

object

The options object defines which items to crawl from the source system.

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - Configuration successfully created.

configuration_id

string

The unique identifier of the configuration

name

string

The name of the configuration.

created

string

The creation date of the configuration in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

updated

string

The timestamp of when the configuration was last updated in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

description

string

The description of the configuration, if available.

conversions

Conversions

Document conversion settings.

enrichments

Enrichments

An array of document enrichment settings for the configuration.

normalizations

Normalizations

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

source

Source

Object containing source parameters for the configuration.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to add a configuration to a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List configurations

GET /v1/environments/{environment_id}/configurations

Lists existing configurations for the service instance.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

name

string

Find configurations with the given name.

Response

200 - Successful response.

configurations

array

An array of configurations that are available for the service instance.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get configuration details

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

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

configuration_id

Required *

string

The ID of the configuration.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Configuration successfully fetched.

configuration_id

string

The unique identifier of the configuration

name

string

The name of the configuration.

created

string

The creation date of the configuration in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

updated

string

The timestamp of when the configuration was last updated in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

description

string

The description of the configuration, if available.

conversions

Conversions

Document conversion settings.

enrichments

Enrichments

An array of document enrichment settings for the configuration.

normalizations

Normalizations

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

source

Source

Object containing source parameters for the configuration.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a configuration

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

Replaces an existing configuration. * Completely replaces the original configuration. * The configuration_id, updated, and created fields are accepted in the request, but they are ignored, and an error is not generated. It is also acceptable for users to submit an updated configuration with none of the three properties. * Documents are processed with a snapshot of the configuration as it was at the time the document was submitted to be ingested. This means that already submitted documents will not see any updates made to the configuration.

Request

Request Body

Configuration

Input an object that enables you to update and customize how your data is ingested and what enrichments are added to your data. The name parameter is required and must be unique within the current environment. All other properties are optional, but if they are omitted the default values replace the current value of each omitted property.

If the input configuration contains the configuration_id, created, or updated properties, they are ignored and overridden by the system, and an error is not returned so that the overridden fields do not need to be removed when updating a configuration.

The configuration can contain unrecognized JSON fields. Any such fields are ignored and do not generate an error. This makes it easier to use 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.

configuration_id

string

The unique identifier of the configuration

name

Required *

string

The name of the configuration.

created

string

The creation date of the configuration in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

updated

string

The timestamp of when the configuration was last updated in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

description

string

The description of the configuration, if available.

conversions

Conversions

Document conversion settings.

pdf

object

A list of PDF conversion settings.

word

object

A list of Word conversion settings.

html

object

A list of HTML conversion settings.

segment

object

A list of Document Segmentation settings.

json_normalizations

array

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

image_text_recognition

boolean

When `true`, automatic text extraction from images (this includes images embedded in supported document formats, for example PDF, and suppported image formats, for example TIFF) is performed on documents uploaded to the collection. This field is supported on Advanced and higher plans only. Lite plans do not support image text recognition.

enrichments

Enrichments

An array of document enrichment settings for the configuration.

normalizations

Normalizations

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

source

Source

Object containing source parameters for the configuration.

type

string

The type of source to connect to.

  • `box` indicates the configuration is to connect an instance of Enterprise Box.
  • `salesforce` indicates the configuration is to connect to Salesforce.
  • `sharepoint` indicates the configuration is to connect to Microsoft SharePoint Online.
  • `web_crawl` indicates the configuration is to perform a web page crawl.
  • `cloud_object_storage` indicates the configuration is to connect to a cloud object store.
credential_id

string

The credential_id of the credentials to use to connect to the source. Credentials are defined using the credentials method. The source_type of the credentials used must match the type field specified in this object.

schedule

object

Object containing the schedule information for the source.

options

object

The options object defines which items to crawl from the source system.

Path Parameters

environment_id

Required *

string

The ID of the environment.

configuration_id

Required *

string

The ID of the configuration.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Configuration successfully updated.

configuration_id

string

The unique identifier of the configuration

name

string

The name of the configuration.

created

string

The creation date of the configuration in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

updated

string

The timestamp of when the configuration was last updated in the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

description

string

The description of the configuration, if available.

conversions

Conversions

Document conversion settings.

enrichments

Enrichments

An array of document enrichment settings for the configuration.

normalizations

Normalizations

Defines operations that can be used to transform the final output JSON into a normalized form. Operations are executed in the order that they appear in the array.

source

Source

Object containing source parameters for the configuration.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to update a read-only configuration or if you attempt to update a configuration in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a configuration

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

The deletion is performed unconditionally. A configuration deletion 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.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

configuration_id

Required *

string

The ID of the configuration.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Configuration successfully deleted.

The response contains a warning if the configuration was referenced by at least one collection.

configuration_id

string

The unique identifier for the configuration.

status

string

Status of the configuration. A deleted configuration has the status deleted.

notices

array

An array of notice messages, if any.

400 - Bad request.

A bad request is returned any time there is a problem with the request itself.

Example error messages:

  • `Invalid Configuration ID` - if the configuration ID is not correctly formatted.
  • `Invalid configurationId: 2c3a981b-dade-488c-b8c6-01ae8d111111` - if the configuration is not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to delete a read-only configuration, or if you attempt to delete a configuration from a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a collection

POST /v1/environments/{environment_id}/collections

Request

Request Body

CreateCollectionRequest

Input an object that allows you to add a collection.

name

Required *

string

The name of the collection to be created.

description

string

A description of the collection.

configuration_id

string

The ID of the configuration in which the collection is to be created.

language

string

The language of the documents stored in the collection, in the form of an ISO 639-1 language code.

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - Collection successfully created.

collection_id

string

The unique identifier of the collection.

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:mmcon:ss.SSS'Z'

updated

string

The timestamp of when the collection was last updated 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 collection's configuration.

language

string

The language of the documents stored in the collection. Permitted values include `en` (English), `de` (German), and `es` (Spanish).

document_counts

DocumentCounts

Object containing collection document count information.

disk_usage

CollectionDiskUsage

Summary of the disk usage statistics for this collection.

training_status

TrainingStatus

Training status details.

crawl_status

object

Object containing information about the crawl status of this collection.

smart_document_understanding

SduStatus

Object containing smart document understanding information for this collection.

400 - Bad request if the collection body does not match the expected format or if the configuration_id references a configuration that does not exist. The error string will describe why the request was rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to add a collection to a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List collections

GET /v1/environments/{environment_id}/collections

Lists existing collections for the service instance.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

name

string

Find collections with the given name.

Response

200 - Successful response.

collections

array

An array containing information about each collection in the environment.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get collection details

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

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Collection fetched.

collection_id

string

The unique identifier of the collection.

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:mmcon:ss.SSS'Z'

updated

string

The timestamp of when the collection was last updated 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 collection's configuration.

language

string

The language of the documents stored in the collection. Permitted values include `en` (English), `de` (German), and `es` (Spanish).

document_counts

DocumentCounts

Object containing collection document count information.

disk_usage

CollectionDiskUsage

Summary of the disk usage statistics for this collection.

training_status

TrainingStatus

Training status details.

crawl_status

object

Object containing information about the crawl status of this collection.

smart_document_understanding

SduStatus

Object containing smart document understanding information for this collection.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a collection

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

Request

Request Body

UpdateCollectionRequest

Input an object that allows you to update a collection.

name

Required *

string

The name of the collection.

description

string

A description of the collection.

configuration_id

string

The ID of the configuration in which the collection is to be updated.

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - Collection successfully updated.

collection_id

string

The unique identifier of the collection.

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:mmcon:ss.SSS'Z'

updated

string

The timestamp of when the collection was last updated 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 collection's configuration.

language

string

The language of the documents stored in the collection. Permitted values include `en` (English), `de` (German), and `es` (Spanish).

document_counts

DocumentCounts

Object containing collection document count information.

disk_usage

CollectionDiskUsage

Summary of the disk usage statistics for this collection.

training_status

TrainingStatus

Training status details.

crawl_status

object

Object containing information about the crawl status of this collection.

smart_document_understanding

SduStatus

Object containing smart document understanding information for this collection.

400 - Bad request if the collection body does not match the expected format or if the configuration_id references a configuration that does not exist. The error string will describe why the request was rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to update a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a collection

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

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Collection successfully deleted.

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`.

400 - Bad request.

A bad request is returned any time there is a problem with the request itself.

Example error messages:

  • `Could not find listed collection` - if the ID is incorrectly formatted.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to delete a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Returned any time the collection is not found (even immediately after the collection was successfully deleted).

Example error message:

`A collection with ID '2cd8bc72-d737-46e3-b26b-05a585111111' was not found.`

code

integer

The HTTP error status code.

error

string

A message describing the error.

Add a document

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

Add a document to a collection with optional metadata.

* The **version** query parameter is still required.

* Returns immediately after the system has accepted the document for processing.

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

* The user can set the **Content-Type** parameter on the **file** part to indicate the media type of the document. If the **Content-Type** parameter is missing or is one of the generic media types (for example, `application/octet-stream`), then the service attempts to automatically detect the document's media type.

* The following field names are reserved and will be filtered out if present after normalization: `id`, `score`, `highlight`, and any field with the prefix of: `_`, `+`, or `-`

* Fields with empty name values after normalization are filtered out before indexing.

* Fields containing the following characters after normalization are filtered out before indexing: `#` and `,`

Note: Documents can be added with a specific document_id by using the /v1/environments/{environment_id}/collections/{collection_id}/documents method.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

202 - The document has been accepted and will be processed.

document_id

string

The unique identifier of the ingested document.

status

string

Status of the document in the ingestion process. A status of `processing` is returned for documents that are ingested with a version date before `2019-01-01`. The `pending` status is returned for all others.

notices

array

Array of notices produced by the document-ingestion process.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to add a document to a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get document details

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

Fetch status details about a submitted document. Note: this operation does not return the document itself. Instead, it returns only the document's processing status and any notices (warnings or errors) that were generated when the document was ingested. Use the query API to retrieve the actual document content.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

document_id

Required *

string

The ID of the document.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Successfully fetched document details.

document_id

string

The unique identifier of the document.

configuration_id

string

The unique identifier for the configuration.

status

string

Status of the document in the ingestion process.

status_description

string

Description of the document status.

filename

string

Name of the original source file (if available).

file_type

string

The type of the original source file.

sha1

string

The SHA-1 hash of the original source file (formatted as a hexadecimal string).

notices

array

Array of notices produced by the document-ingestion process.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to get the status of a document in a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a document

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

Replace an existing document or add a document with a specified document_id. Starts ingesting a document with optional metadata.

Note: When uploading a new document with this method it automatically replaces any document stored with the same document_id if it exists.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

document_id

Required *

string

The ID of the document.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

202 - The document has been accepted and it will be processed.

document_id

string

The unique identifier of the ingested document.

status

string

Status of the document in the ingestion process. A status of `processing` is returned for documents that are ingested with a version date before `2019-01-01`. The `pending` status is returned for all others.

notices

array

Array of notices produced by the document-ingestion process.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to add or update a document in a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a document

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

If the given document ID is invalid, or if the document is not found, then the a success response is returned (HTTP status code `200`) with the status set to 'deleted'.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

document_id

Required *

string

The ID of the document.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The document was successfully deleted.

document_id

string

The unique identifier of the document.

status

string

Status of the document. A deleted document has the status deleted.

400 - Bad request.

A bad request is returned any time there is a problem with the request itself.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Forbidden. Returned if you attempt to delete a document in a collection in a read-only environment.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List collection fields

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

Gets a list of the unique fields (and their types) stored in the index.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The list of fetched fields.

The fields are returned using a fully qualified name format, however, the format differs slightly from that used by the query operations:

* Fields which contain nested JSON objects are assigned a type of "nested".

* Fields which belong to a nested object are prefixed with `.properties` (for example, `warnings.properties.severity` means that the `warnings` object has a property called `severity`).

* Fields returned from the News collection are prefixed with `v{N}-fullnews-t3-{YEAR}.mappings` (for example, `v5-fullnews-t3-2016.mappings.text.properties.author`).

fields

array

An array containing information about each field in the collections.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query a collection (GET)

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

After your content is uploaded and enriched by Discovery, you can build queries to search your content. For details, see the Discovery documentation.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

filter

string

A cacheable query that excludes documents that don't mention the query content. Filter searches are better for metadata-type searches and for assessing the concepts in the data set.

query

string

A query search returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first.

natural_language_query

string

A natural language query that returns relevant documents by utilizing training data and natural language understanding.

passages

boolean

A passages query that returns the most relevant passages from the results.

aggregation

string

An aggregation search that returns an exact answer by combining query search with filters. Useful for applications to build lists, tables, and time series. For a full list of possible aggregations, see the Query reference.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

return

array

A comma-separated list of the portion of the document hierarchy to return.

offset

integer

The number of query results to skip at the beginning. For example, if the total number of results that are returned is 10 and the offset is 8, it returns the last two results. The maximum for the count and offset values together in any one query is 10000

sort

array

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 or `+` for ascending. Ascending is the default sort direction if no prefix is specified.

highlight

boolean

When true, a highlight field is returned for each result which contains the fields which match the query with `<em></em>` tags around the matching query terms.

passages.fields

array

A comma-separated list of fields that passages are drawn from. If this parameter not specified, then all top-level fields are included.

passages.count

integer

The maximum number of passages to return. The search returns fewer passages if the requested total is not found.

passages.characters

integer

The approximate number of characters that any one passage will have.

deduplicate

boolean

When `true` and used with a Watson Discovery News collection, duplicate results (based on the contents of the title field) are removed. Duplicate comparison is limited to the current query only; offset is not considered. This parameter is currently Beta functionality.

deduplicate.field

string

When specified, duplicate results based on the field specified are removed from the returned results. Duplicate comparison is limited to the current query only, offset is not considered. This parameter is currently Beta functionality.

similar

boolean

When `true`, results are returned based on their similarity to the document IDs specified in the similar.document_ids parameter.

similar.document_ids

array

A comma-separated list of document IDs to find similar documents.

Tip: Include the natural_language_query parameter to expand the scope of the document similarity search with the natural language query. Other query parameters, such as filter and query, are subsequently applied and reduce the scope.

similar.fields

array

A comma-separated list of field names that are used as a basis for comparison to identify similar documents. If not specified, the entire document is used for comparison.

bias

string

Field which the returned results will be biased against. The specified field must be either a date or number format. When a date type field is specified returned results are biased towards field values closer to the current date. When a number type field is specified, returned results are biased towards higher field values. This parameter cannot be used in the same query as the sort parameter.

Response

200 - Query executed successfully.

matching_results

integer

The number of matching results for the query.

results

array

Array of document results for the query.

aggregations

array

Array of aggregation results for the query.

passages

array

Array of passage results for the query.

duplicates_removed

integer

The number of duplicate results removed.

session_token

string

The session token for this query. The session token can be used to add events associated with this query to the query and event log.

Important: Session tokens are case sensitive.

retrieval_details

RetrievalDetails

An object contain retrieval type information.

suggested_query

string

The suggestions for a misspelled natural language query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

409 - query and natural_language_query can be used in the same request only if training is complete.

code

integer

The HTTP error status code.

error

string

A message describing the error.

503 - Query timed out.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query a collection

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

By using this method, you can construct long queries. For details, see the Discovery documentation.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Query executed successfully.

matching_results

integer

The number of matching results for the query.

results

array

Array of document results for the query.

aggregations

array

Array of aggregation results for the query.

passages

array

Array of passage results for the query.

duplicates_removed

integer

The number of duplicate results removed.

session_token

string

The session token for this query. The session token can be used to add events associated with this query to the query and event log.

Important: Session tokens are case sensitive.

retrieval_details

RetrievalDetails

An object contain retrieval type information.

suggested_query

string

The suggestions for a misspelled natural language query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

409 - query and natural_language_query can be used in the same request only if training is complete.

code

integer

The HTTP error status code.

error

string

A message describing the error.

503 - Query timed out.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query system notices

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

Queries for notices (errors or warnings) that might have been generated by the system. Notices are generated when ingesting documents and performing relevance training. See the Discovery documentation for more details on the query language.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

filter

string

A cacheable query that excludes documents that don't mention the query content. Filter searches are better for metadata-type searches and for assessing the concepts in the data set.

query

string

A query search returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first.

natural_language_query

string

A natural language query that returns relevant documents by utilizing training data and natural language understanding.

passages

boolean

A passages query that returns the most relevant passages from the results.

aggregation

string

An aggregation search that returns an exact answer by combining query search with filters. Useful for applications to build lists, tables, and time series. For a full list of possible aggregations, see the Query reference.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

return

array

A comma-separated list of the portion of the document hierarchy to return.

offset

integer

The number of query results to skip at the beginning. For example, if the total number of results that are returned is 10 and the offset is 8, it returns the last two results. The maximum for the count and offset values together in any one query is 10000

sort

array

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 or `+` for ascending. Ascending is the default sort direction if no prefix is specified.

highlight

boolean

When true, a highlight field is returned for each result which contains the fields which match the query with `<em></em>` tags around the matching query terms.

passages.fields

array

A comma-separated list of fields that passages are drawn from. If this parameter not specified, then all top-level fields are included.

passages.count

integer

The maximum number of passages to return. The search returns fewer passages if the requested total is not found.

passages.characters

integer

The approximate number of characters that any one passage will have.

deduplicate.field

string

When specified, duplicate results based on the field specified are removed from the returned results. Duplicate comparison is limited to the current query only, offset is not considered. This parameter is currently Beta functionality.

similar

boolean

When `true`, results are returned based on their similarity to the document IDs specified in the similar.document_ids parameter.

similar.document_ids

array

A comma-separated list of document IDs to find similar documents.

Tip: Include the natural_language_query parameter to expand the scope of the document similarity search with the natural language query. Other query parameters, such as filter and query, are subsequently applied and reduce the scope.

similar.fields

array

A comma-separated list of field names that are used as a basis for comparison to identify similar documents. If not specified, the entire document is used for comparison.

Response

200 - Query for notices executed successfully.

matching_results

integer

The number of matching results

results

array

Array of document results that match the query.

aggregations

array

Array of aggregation results that match the query.

passages

array

Array of passage results that match the query.

duplicates_removed

integer

The number of duplicates removed from this notices query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List training data

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

Lists the training data for the specified collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Training data for this collection found and returned.

environment_id

string

The environment id associated with this training data set.

collection_id

string

The collection id associated with this training data set.

queries

array

Array of training queries. At least 50 queries are required for training to begin. A maximum of 10,000 queries are returned.

Add query to training data

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

Adds a query to the training data for this collection. The query can contain a filter and natural language query.

Request

Request Body

NewTrainingQuery

The body of the training data query that is to be added to the collection's training data.

natural_language_query

string

The natural text query for the new training query.

filter

string

The filter used on the collection before the natural_language_query is applied.

examples

array

Array of training examples.

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The query was successfully added.

query_id

string

The query ID associated with the training query.

natural_language_query

string

The natural text query for the training query.

filter

string

The filter used on the collection before the natural_language_query is applied.

examples

array

Array of training examples.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete all training data

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

Deletes all training data from a collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

204 - All training data removed.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get details about a query

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

Gets details for a specific training data query, including the query string and all examples.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Details for this training query found and returned.

query_id

string

The query ID associated with the training query.

natural_language_query

string

The natural text query for the training query.

filter

string

The filter used on the collection before the natural_language_query is applied.

examples

array

Array of training examples.

404 - The query does not exist.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a training data query

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

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

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

204 - Query and all example document references successfully removed from the training set for this collection.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List examples for a training data query

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

List all examples for this training data query.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - A list of all training examples added for this query.

examples

array

Array of training examples.

404 - Query not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Add example to training data query

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

Adds a example to this training data query.

Request

Request Body

TrainingExample

The body of the example that is to be added to the specified query.

document_id

string

The document ID associated with this training example.

cross_reference

string

The cross reference associated with this training example.

relevance

integer

The relevance of the training example

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - The example was successfully added to the query.

document_id

string

The document ID associated with this training example.

cross_reference

string

The cross reference associated with this training example.

relevance

integer

The relevance of the training example

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete example for training data query

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

Deletes the example document with the given ID from the training data query.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

example_id

Required *

string

The ID of the document as it is indexed.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

204 - The example document reference was removed from the query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Change label or cross reference for example

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

Changes the label or cross reference query for this training data example.

Request

Request Body

TrainingExamplePatch

The body of the example that is to be added to the specified query.

cross_reference

string

The example to add.

relevance

integer

The relevance value for this example.

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

example_id

Required *

string

The ID of the document as it is indexed.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The label or cross reference query were successfully applied.

document_id

string

The document ID associated with this training example.

cross_reference

string

The cross reference associated with this training example.

relevance

integer

The relevance of the training example

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get details for training data example

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

Gets the details for this training example.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

query_id

Required *

string

The ID of the query used for training.

example_id

Required *

string

The ID of the document as it is indexed.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Details for this example successfully found and returned.

document_id

string

The document ID associated with this training example.

cross_reference

string

The cross reference associated with this training example.

relevance

integer

The relevance of the training example

404 - The query or the example does not exist.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List fields across collections

GET /v1/environments/{environment_id}/fields

Gets a list of the unique fields (and their types) stored in the indexes of the specified collections.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

collection_ids

Required *

array

A comma-separated list of collection IDs to be queried against.

Response

200 - The list of fetched fields.

The fields are returned using a fully qualified name format, however, the format differs slightly from that used by the query operations:

* Fields which contain nested JSON objects are assigned a type of &quot;nested&quot;.

* Fields which belong to a nested object are prefixed with &#x60;.properties&#x60; (for example, &#x60;warnings.properties.severity&#x60; means that the &#x60;warnings&#x60; object has a property called &#x60;severity&#x60;).

* Fields returned from the News collection are prefixed with &#x60;v{N}-fullnews-t3-{YEAR}.mappings&#x60; (for example, &#x60;v5-fullnews-t3-2016.mappings.text.properties.author&#x60;).

fields

array

An array containing information about each field in the collections.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query multiple collections (GET)

GET /v1/environments/{environment_id}/query

See the Discovery documentation for more details.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

collection_ids

Required *

array

A comma-separated list of collection IDs to be queried against.

filter

string

A cacheable query that excludes documents that don't mention the query content. Filter searches are better for metadata-type searches and for assessing the concepts in the data set.

query

string

A query search returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first.

natural_language_query

string

A natural language query that returns relevant documents by utilizing training data and natural language understanding.

aggregation

string

An aggregation search that returns an exact answer by combining query search with filters. Useful for applications to build lists, tables, and time series. For a full list of possible aggregations, see the Query reference.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

return

array

A comma-separated list of the portion of the document hierarchy to return.

offset

integer

The number of query results to skip at the beginning. For example, if the total number of results that are returned is 10 and the offset is 8, it returns the last two results. The maximum for the count and offset values together in any one query is 10000

sort

array

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 or `+` for ascending. Ascending is the default sort direction if no prefix is specified.

highlight

boolean

When true, a highlight field is returned for each result which contains the fields which match the query with `<em></em>` tags around the matching query terms.

deduplicate

boolean

When `true` and used with a Watson Discovery News collection, duplicate results (based on the contents of the title field) are removed. Duplicate comparison is limited to the current query only; offset is not considered. This parameter is currently Beta functionality.

deduplicate.field

string

When specified, duplicate results based on the field specified are removed from the returned results. Duplicate comparison is limited to the current query only, offset is not considered. This parameter is currently Beta functionality.

similar

boolean

When `true`, results are returned based on their similarity to the document IDs specified in the similar.document_ids parameter.

similar.document_ids

array

A comma-separated list of document IDs to find similar documents.

Tip: Include the natural_language_query parameter to expand the scope of the document similarity search with the natural language query. Other query parameters, such as filter and query, are subsequently applied and reduce the scope.

similar.fields

array

A comma-separated list of field names that are used as a basis for comparison to identify similar documents. If not specified, the entire document is used for comparison.

passages

boolean

A passages query that returns the most relevant passages from the results.

passages.fields

array

A comma-separated list of fields that passages are drawn from. If this parameter not specified, then all top-level fields are included.

passages.count

integer

The maximum number of passages to return. The search returns fewer passages if the requested total is not found.

passages.characters

integer

The approximate number of characters that any one passage will have.

bias

string

Field which the returned results will be biased against. The specified field must be either a date or number format. When a date type field is specified returned results are biased towards field values closer to the current date. When a number type field is specified, returned results are biased towards higher field values. This parameter cannot be used in the same query as the sort parameter.

Response

200 - Query executed successfully.

matching_results

integer

The number of matching results for the query.

results

array

Array of document results for the query.

aggregations

array

Array of aggregation results for the query.

passages

array

Array of passage results for the query.

duplicates_removed

integer

The number of duplicate results removed.

session_token

string

The session token for this query. The session token can be used to add events associated with this query to the query and event log.

Important: Session tokens are case sensitive.

retrieval_details

RetrievalDetails

An object contain retrieval type information.

suggested_query

string

The suggestions for a misspelled natural language query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

409 - query and natural_language_query can be used in the same request only if training is complete.

code

integer

The HTTP error status code.

error

string

A message describing the error.

503 - Query timed out.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query multiple collections

POST /v1/environments/{environment_id}/query

By using this method, you can construct long queries that search multiple collection. For details, see the Discovery documentation.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Query executed successfully.

matching_results

integer

The number of matching results for the query.

results

array

Array of document results for the query.

aggregations

array

Array of aggregation results for the query.

passages

array

Array of passage results for the query.

duplicates_removed

integer

The number of duplicate results removed.

session_token

string

The session token for this query. The session token can be used to add events associated with this query to the query and event log.

Important: Session tokens are case sensitive.

retrieval_details

RetrievalDetails

An object contain retrieval type information.

suggested_query

string

The suggestions for a misspelled natural language query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

409 - query and natural_language_query can be used in the same request only if training is complete.

code

integer

The HTTP error status code.

error

string

A message describing the error.

503 - Query timed out.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query multiple collection system notices

GET /v1/environments/{environment_id}/notices

Queries for notices (errors or warnings) that might have been generated by the system. Notices are generated when ingesting documents and performing relevance training. See the Discovery documentation for more details on the query language.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

collection_ids

Required *

array

A comma-separated list of collection IDs to be queried against.

filter

string

A cacheable query that excludes documents that don't mention the query content. Filter searches are better for metadata-type searches and for assessing the concepts in the data set.

query

string

A query search returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first.

natural_language_query

string

A natural language query that returns relevant documents by utilizing training data and natural language understanding.

aggregation

string

An aggregation search that returns an exact answer by combining query search with filters. Useful for applications to build lists, tables, and time series. For a full list of possible aggregations, see the Query reference.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

return

array

A comma-separated list of the portion of the document hierarchy to return.

offset

integer

The number of query results to skip at the beginning. For example, if the total number of results that are returned is 10 and the offset is 8, it returns the last two results. The maximum for the count and offset values together in any one query is 10000

sort

array

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 or `+` for ascending. Ascending is the default sort direction if no prefix is specified.

highlight

boolean

When true, a highlight field is returned for each result which contains the fields which match the query with `<em></em>` tags around the matching query terms.

deduplicate.field

string

When specified, duplicate results based on the field specified are removed from the returned results. Duplicate comparison is limited to the current query only, offset is not considered. This parameter is currently Beta functionality.

similar

boolean

When `true`, results are returned based on their similarity to the document IDs specified in the similar.document_ids parameter.

similar.document_ids

array

A comma-separated list of document IDs to find similar documents.

Tip: Include the natural_language_query parameter to expand the scope of the document similarity search with the natural language query. Other query parameters, such as filter and query, are subsequently applied and reduce the scope.

similar.fields

array

A comma-separated list of field names that are used as a basis for comparison to identify similar documents. If not specified, the entire document is used for comparison.

Response

200 - Query for notices executed successfully.

matching_results

integer

The number of matching results

results

array

Array of document results that match the query.

aggregations

array

Array of aggregation results that match the query.

passages

array

Array of passage results that match the query.

duplicates_removed

integer

The number of duplicates removed from this notices query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get the expansion list

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

Returns the current expansion list for the specified collection. If an expansion list is not specified, an object with empty expansion arrays is returned.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Successfully fetched expansions details.

expansions

array

An array of query expansion definitions.

Each object in the expansions array represents a term or set of terms that will be expanded into other terms. Each expansion object can be configured as bidirectional or unidirectional. Bidirectional means that all terms are expanded to all other terms in the object. Unidirectional means that a set list of terms can be expanded into a second list of terms.

To create a bi-directional expansion specify an expanded_terms array. When found in a query, all items in the expanded_terms array are then expanded to the other items in the same array.

To create a uni-directional expansion, specify both an array of input_terms and an array of expanded_terms. When items in the input_terms array are present in a query, they are expanded using the items listed in the expanded_terms array.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create or update expansion list

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

Create or replace the Expansion list for this collection. The maximum number of expanded terms per collection is `500`. The current expansion list is replaced with the uploaded content.

Request

Request Body

Expansions

An object that defines the expansion list.

expansions

Required *

array

An array of query expansion definitions.

Each object in the expansions array represents a term or set of terms that will be expanded into other terms. Each expansion object can be configured as bidirectional or unidirectional. Bidirectional means that all terms are expanded to all other terms in the object. Unidirectional means that a set list of terms can be expanded into a second list of terms.

To create a bi-directional expansion specify an expanded_terms array. When found in a query, all items in the expanded_terms array are then expanded to the other items in the same array.

To create a uni-directional expansion, specify both an array of input_terms and an array of expanded_terms. When items in the input_terms array are present in a query, they are expanded using the items listed in the expanded_terms array.

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The expansion list has been accepted and it will used for all future queries

expansions

array

An array of query expansion definitions.

Each object in the expansions array represents a term or set of terms that will be expanded into other terms. Each expansion object can be configured as bidirectional or unidirectional. Bidirectional means that all terms are expanded to all other terms in the object. Unidirectional means that a set list of terms can be expanded into a second list of terms.

To create a bi-directional expansion specify an expanded_terms array. When found in a query, all items in the expanded_terms array are then expanded to the other items in the same array.

To create a uni-directional expansion, specify both an array of input_terms and an array of expanded_terms. When items in the input_terms array are present in a query, they are expanded using the items listed in the expanded_terms array.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

500 - Timeout when uploading the expansion list.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete the expansion list

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

Remove the expansion information for this collection. The expansion list must be deleted to disable query expansion for a collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

204 - The expansion list was successfully deleted.

400 - Bad request.

A bad request is returned any time there is a problem with the request itself.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Information security.">

Delete labeled data

DELETE /v1/user_data

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

customer_id

Required *

string

The customer ID for which all data is to be deleted.

Response

200 - OK. The delete request was successfully submitted.

400 - Bad Request. The request did not pass a customer ID:

  • `No customer ID found in the request`

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create event

POST /v1/events

The Events API can be used to create log entries that are associated with specific queries. For example, you can record which documents in the results set were "clicked" by a user and when that click occurred.

Request

Request Body

CreateEventObject

An object that defines a query event to be added to the log.

type

Required *

string

The event type to be created.

data

Required *

EventData

Query event data object.

environment_id

Required *

string

The environment_id associated with the query that the event is associated with.

session_token

Required *

string

The session token that was returned as part of the query results that this event is associated with.

client_timestamp

string

The optional timestamp for the event that was created. If not provided, the time that the event was created in the log was used.

display_rank

integer

The rank of the result item which the event is associated with.

collection_id

Required *

string

The collection_id of the document that this event is associated with.

document_id

Required *

string

The document_id of the document that this event is associated with.

query_id

string

The query identifier stored in the log. The query and any events associated with that query are stored with the same query_id.

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

201 - The event object was successfully accepted.

type

string

The event type that was created.

data

EventData

Query event data object.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

401 - Request contains invalid content and cannot be added.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Search the query and event log

GET /v1/logs

Searches the query and event log to find query sessions that match the specified criteria. Searching the logs endpoint uses the standard Discovery query syntax for the parameters that are supported.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

filter

string

A cacheable query that excludes documents that don't mention the query content. Filter searches are better for metadata-type searches and for assessing the concepts in the data set.

query

string

A query search returns all documents in your data set with full enrichments and full text, but with the most relevant documents listed first.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

offset

integer

The number of query results to skip at the beginning. For example, if the total number of results that are returned is 10 and the offset is 8, it returns the last two results. The maximum for the count and offset values together in any one query is 10000

sort

array

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 or `+` for ascending. Ascending is the default sort direction if no prefix is specified.

Response

200 - Log query executed successfully.

matching_results

integer

Number of matching results.

results

array

Array of log query response results.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Number of queries over time

GET /v1/metrics/number_of_queries

Total number of queries using the natural_language_query parameter over a specific time window.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

start_time

string

Metric is computed from data recorded after this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

end_time

string

Metric is computed from data recorded before this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

result_type

string

The type of result to consider when calculating the metric.

Response

200 - Metric calculation executed successfully.

aggregations

array

Array of metric aggregations.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Number of queries with an event over time

GET /v1/metrics/number_of_queries_with_event

Total number of queries using the natural_language_query parameter that have a corresponding "click" event over a specified time window. This metric requires having integrated event tracking in your application using the Events API.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

start_time

string

Metric is computed from data recorded after this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

end_time

string

Metric is computed from data recorded before this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

result_type

string

The type of result to consider when calculating the metric.

Response

200 - Metric calculation executed successfully.

aggregations

array

Array of metric aggregations.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Number of queries with no search results over time

GET /v1/metrics/number_of_queries_with_no_search_results

Total number of queries using the natural_language_query parameter that have no results returned over a specified time window.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

start_time

string

Metric is computed from data recorded after this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

end_time

string

Metric is computed from data recorded before this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

result_type

string

The type of result to consider when calculating the metric.

Response

200 - Metric calculation executed successfully.

aggregations

array

Array of metric aggregations.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Percentage of queries with an associated event

GET /v1/metrics/event_rate

The percentage of queries using the natural_language_query parameter that have a corresponding "click" event over a specified time window. This metric requires having integrated event tracking in your application using the Events API.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

start_time

string

Metric is computed from data recorded after this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

end_time

string

Metric is computed from data recorded before this timestamp; must be in `YYYY-MM-DDThh:mm:ssZ` format.

result_type

string

The type of result to consider when calculating the metric.

Response

200 - Metric calculation executed successfully.

aggregations

array

Array of metric aggregations.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List credentials

GET /v1/environments/{environment_id}/credentials

List all the source credentials that have been created for this service instance.

Note: All credentials are sent over an encrypted connection and encrypted at rest.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The request to list all credentials completed successfully.

credentials

array

An array of credential definitions that were created for this instance.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create credentials

POST /v1/environments/{environment_id}/credentials

Creates a set of credentials to connect to a remote source. Created credentials are used in a configuration to associate a collection with the remote source.

Note: All credentials are sent over an encrypted connection and encrypted at rest.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Credentials successfully created.

credential_id

string

Unique identifier for this set of credentials.

source_type

string

The source that this credentials object connects to.

  • `box` indicates the credentials are used to connect an instance of Enterprise Box.
  • `salesforce` indicates the credentials are used to connect to Salesforce.
  • `sharepoint` indicates the credentials are used to connect to Microsoft SharePoint Online.
  • `web_crawl` indicates the credentials are used to perform a web crawl. = `cloud_object_storage` indicates the credentials are used to connect to an IBM Cloud Object Store.

credential_details

CredentialDetails

Object containing details of the stored credentials.

Obtain credentials for your source from the administrator of the source.

status

StatusDetails

Object that contains details about the status of the authentication process.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

View Credentials

GET /v1/environments/{environment_id}/credentials/{credential_id}

Returns details about the specified credentials.

Note: Secure credential information such as a password or SSH key is never returned and must be obtained from the source system.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

credential_id

Required *

string

The unique identifier for a set of source credentials.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - The requested credentials object was successfully returned.

credential_id

string

Unique identifier for this set of credentials.

source_type

string

The source that this credentials object connects to.

  • `box` indicates the credentials are used to connect an instance of Enterprise Box.
  • `salesforce` indicates the credentials are used to connect to Salesforce.
  • `sharepoint` indicates the credentials are used to connect to Microsoft SharePoint Online.
  • `web_crawl` indicates the credentials are used to perform a web crawl. = `cloud_object_storage` indicates the credentials are used to connect to an IBM Cloud Object Store.

credential_details

CredentialDetails

Object containing details of the stored credentials.

Obtain credentials for your source from the administrator of the source.

status

StatusDetails

Object that contains details about the status of the authentication process.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update credentials

PUT /v1/environments/{environment_id}/credentials/{credential_id}

Updates an existing set of source credentials.

Note: All credentials are sent over an encrypted connection and encrypted at rest.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

credential_id

Required *

string

The unique identifier for a set of source credentials.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Credentials successfully updated.

credential_id

string

Unique identifier for this set of credentials.

source_type

string

The source that this credentials object connects to.

  • `box` indicates the credentials are used to connect an instance of Enterprise Box.
  • `salesforce` indicates the credentials are used to connect to Salesforce.
  • `sharepoint` indicates the credentials are used to connect to Microsoft SharePoint Online.
  • `web_crawl` indicates the credentials are used to perform a web crawl. = `cloud_object_storage` indicates the credentials are used to connect to an IBM Cloud Object Store.

credential_details

CredentialDetails

Object containing details of the stored credentials.

Obtain credentials for your source from the administrator of the source.

status

StatusDetails

Object that contains details about the status of the authentication process.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

401 - Authentication to source failed.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Not found.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete credentials

DELETE /v1/environments/{environment_id}/credentials/{credential_id}

Deletes a set of stored credentials from your Discovery instance.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

credential_id

Required *

string

The unique identifier for a set of source credentials.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Credentials successfully deleted.

credential_id

string

The unique identifier of the credentials that have been deleted.

status

string

The status of the deletion request.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Most frequent query tokens with an event

GET /v1/metrics/top_query_tokens_with_event_rate

The most frequent query tokens parsed from the natural_language_query parameter and their corresponding "click" event rate within the recording period (queries and events are stored for 30 days). A query token is an individual word or unigram within the query string.

Request

Path Parameters

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

count

integer

Number of results to return. The maximum for the count and offset values together in any one query is 10000

Response

200 - Metric calculation executed successfully.

aggregations

array

Array of metric token aggregations.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get tokenization dictionary status

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

Returns the current status of the tokenization dictionary for the specified collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Tokenization dictionary found and is pending or active.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

404 - Tokenization dictionary for this collection not found.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create tokenization dictionary

POST /v1/environments/{environment_id}/collections/{collection_id}/word_lists/tokenization_dictionary

Upload a custom tokenization dictionary to use with the specified collection.

Request

Request Body

TokenDict

An object that represents the tokenization dictionary to be uploaded.

tokenization_rules

array

An array of tokenization rules. Each rule contains, the original `text` string, component `tokens`, any alternate character set `readings`, and which `part_of_speech` the text is from.

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

202 - Uploaded successfully, pending update to the collection.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Word list too large

code

integer

The HTTP error status code.

error

string

A message describing the error.

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete tokenization dictionary

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

Delete the tokenization dictionary from the collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get stopword list status

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

Returns the current status of the stopword list for the specified collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Stopword list found and is pending or active.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

404 - Stopword list for this collection not found.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create stopword list

POST /v1/environments/{environment_id}/collections/{collection_id}/word_lists/stopwords

Upload a custom stopword list to use with the specified collection.

Request

Request Body

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Stopword list uploaded successfully, pending update to the collection.

status

string

Current wordlist status for the specified collection.

type

string

The type for this wordlist. Can be `tokenization_dictionary` or `stopwords`.

400 - Bad request if the request is incorrectly formatted.

The error message contains details about what caused the request to be rejected.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Word list too large

code

integer

The HTTP error status code.

error

string

A message describing the error.

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a custom stopword list

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

Delete a custom stopword list from the collection. After a custom stopword list is deleted, the default list is used for the collection.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

400 - Unsupported word list

404 - No word list for type

500 - Unexpected error, try again.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List Gateways

GET /v1/environments/{environment_id}/gateways

List the currently configured gateways.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

gateways

array

Array of configured gateway connections.

400 - Invalid Environment ID

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Unknown Environment ID

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create Gateway

POST /v1/environments/{environment_id}/gateways

Create a gateway configuration to use with a remotely installed gateway.

Request

Request Body

GatewayName

The name of the gateway to created

name

string

User-defined name.

Path Parameters

environment_id

Required *

string

The ID of the environment.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

gateway_id

string

The gateway ID of the gateway.

name

string

The user defined name of the gateway.

status

string

The current status of the gateway. `connected` means the gateway is connected to the remotly installed gateway. `idle` means this gateway is not currently in use.

token

string

The generated token for this gateway. The value of this field is used when configuring the remotly installed gateway.

token_id

string

The generated token_id for this gateway. The value of this field is used when configuring the remotly installed gateway.

400 - Invalid Environment ID

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Unknown Environment ID

code

integer

The HTTP error status code.

error

string

A message describing the error.

List Gateway Details

GET /v1/environments/{environment_id}/gateways/{gateway_id}

List information about the specified gateway.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

gateway_id

Required *

string

The requested gateway ID.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

gateway_id

string

The gateway ID of the gateway.

name

string

The user defined name of the gateway.

status

string

The current status of the gateway. `connected` means the gateway is connected to the remotly installed gateway. `idle` means this gateway is not currently in use.

token

string

The generated token for this gateway. The value of this field is used when configuring the remotly installed gateway.

token_id

string

The generated token_id for this gateway. The value of this field is used when configuring the remotly installed gateway.

400 - Invalid or Unknown Environment ID

Delete Gateway

DELETE /v1/environments/{environment_id}/gateways/{gateway_id}

Delete the specified gateway configuration.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

gateway_id

Required *

string

The requested gateway ID.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

Response

200 - Success

gateway_id

string

The gateway ID of the deleted gateway.

status

string

The status of the request.

400 - Invalid or Unknown request parameters

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Invalid or Unknown Environment ID

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get Autocomplete Suggestions

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

Returns completion query suggestions for the specified prefix. /n/n Important: this method is only valid when using the Cloud Pak version of Discovery.

Request

Path Parameters

environment_id

Required *

string

The ID of the environment.

collection_id

Required *

string

The ID of the collection.

Query Parameters

version

Required *

string

Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is `2019-04-30`.

field

string

The field in the result documents that autocompletion suggestions are identified from.

prefix

Required *

string

The prefix to use for autocompletion. For example, the prefix `Ho` could autocomplete to `hot`, `housing`, or `how`.

count

integer

The number of autocompletion suggestions to return.

Response

200 - Object containing array of possible completions.

completions

array

Array of autcomplete suggestion based on the provided prefix.

400 - The specified field does not exist.

code

integer

The HTTP error status code.

error

string

A message describing the error.