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