List collections

GET /v2/projects/{project_id}/collections

Lists existing collections for the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Successful response.

collections

array

An array that contains information about each collection in the project.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a collection

POST /v2/projects/{project_id}/collections

Create a new collection in the specified project.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - The collection has been successfully created

collection_id

string

The Universally Unique Identifier (UUID) of the collection.

name

string

The name of the collection.

description

string

A description of the collection.

created

string

The date that the collection was created.

language

string

The language of the collection. For a list of supported languages, see the product documentation.

ocr_enabled

boolean

If set to `true`, optical character recognition (OCR) is enabled. For more information, see Optical character recognition.

enrichments

array

An array of enrichments that are applied to this collection. To get a list of enrichments that are available for a project, use the List enrichments method.

If no enrichments are specified when the collection is created, the default enrichments for the project type are applied. For more information about project default settings, see the product documentation.

webhooks

Webhooks

An object with webhook information. For more information, see Document status webhook API.

conversions

Conversions

Document processing operations that occur during the document conversion phase of ingestion.

Note: Available only from service instances that are managed by IBM Cloud.

normalizations

Normalizations

Defines operations that normalize the JSON representation of data after enrichments are applied. Operations run in the order that is specified in this array.

New fields that are added with a post-enrichment normalization are displayed in the JSON representation of query results, but are not available from product user interface pages, such as Manage fields.

Note: Available only from service instances that are managed by IBM Cloud.

smart_document_understanding

object

An object that describes the Smart Document Understanding model for a collection.

source_document_counts

object

Object that describes the status of documents that are uploaded to a collection or that are added from a crawled external data source. To get the total number of documents, sum the values of the status types.

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

document_counts

object

Object with counts of documents in the collection grouped by document status.

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

400 - Bad request.

No request body.
Missing rquired request parameter or its value.
Missing project.
Too many collections in project.
Too many total collections.
Unsupported language is requested.
Invalid normalization operation is requested.
Missing normalization source.
Missing normalization destination.
Invalid normalization destination.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query a project

POST /v2/projects/{project_id}/query

Search your data by submitting queries that are written in natural language or formatted in the Discovery Query Language. For more information, see the Discovery documentation. The default query parameters differ by project type. For more information about the project default settings, see the Discovery documentation. See the Projects API documentation for details about how to set custom default query settings.

The length of the UTF-8 encoding of the POST body cannot exceed 10,000 bytes, which is roughly equivalent to 10,000 characters in English.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Query executed successfully.

matching_results

integer

The number of matching results for the query. Results that match due to a curation only are not counted in the total.

results

array

Array of document results for the query.

aggregations

array

Array of aggregations for the query.

retrieval_details

RetrievalDetails

An object contain retrieval type information.

suggested_query

string

Suggested correction to the submitted natural_language_query value.

suggested_refinements

array

Array of suggested refinements. Note: The `suggested_refinements` parameter that identified dynamic facets from the data is deprecated.

table_results

array

Array of table results.

passages

array

Passages that best match the query from across all of the collections in the project. Returned if passages.per_document is `false`.

400 - Bad request.

Project has no collections.
A list of document ids is required in similar.document_ids when similar.enabled is `true`.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get Autocomplete Suggestions

GET /v2/projects/{project_id}/autocompletion

Returns completion query suggestions for the specified prefix.

Suggested words are based on terms from the project documents. Suggestions are not based on terms from the project's search history, and the project does not learn from previous user choices.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

collection_ids

array

Comma separated list of the collection IDs. If this parameter is not specified, all collections in the project are used.

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 that contains an array of possible completions.

completions

array

Array of autocomplete 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.

List component settings

GET /v2/projects/{project_id}/component_settings

Returns default configuration settings for components.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Successful response.

fields_shown

ComponentSettingsFieldsShown

Fields shown in the results section of the UI

autocomplete

boolean

Whether or not autocomplete is enabled.

structured_search

boolean

Whether or not structured search is enabled.

results_per_page

integer

Number or results shown per page.

aggregations

array

a list of component setting aggregations

List documents

GET /v2/projects/{project_id}/collections/{collection_id}/documents

Lists the documents in the specified collection. The list includes only the document ID of each document and returns information for up to 10,000 documents.

Note: This method is available only from Cloud Pak for Data version 4.0.9 and later installed instances, and from IBM Cloud-managed instances.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

count

integer

The maximum number of documents to return. Up to 1,000 documents are returned by default. The maximum number allowed is 10,000.

status

string

Filters the documents to include only documents with the specified ingestion status. The options include:

`available`: Ingestion is finished and the document is indexed.
`failed`: Ingestion is finished, but the document is not indexed because of an error.
`pending`: The document is uploaded, but the ingestion process is not started.
`processing`: Ingestion is in progress.

You can specify one status value or add a comma-separated list of more than one status value. For example, `available,failed`.

has_notices

boolean

If set to `true`, only documents that have notices, meaning documents for which warnings or errors were generated during the ingestion, are returned. If set to `false`, only documents that don't have notices are returned. If unspecified, no filter based on notices is applied.

Notice details are not available in the result, but you can use the Query collection notices method to find details by adding the parameter `query=notices.document_id:{document-id}`.

is_parent

boolean

If set to `true`, only parent documents, meaning documents that were split during the ingestion process and resulted in two or more child documents, are returned. If set to `false`, only child documents are returned. If unspecified, no filter based on the parent or child relationship is applied.

CSV files, for example, are split into separate documents per line and JSON files are split into separate documents per object.

parent_document_id

string

Filters the documents to include only child documents that were generated when the specified parent document was processed.

sha256

string

Filters the documents to include only documents with the specified SHA-256 hash. Format the hash as a hexadecimal string.

Response

200 - Successful response.

matching_results

integer

The number of matching results for the document query.

documents

array

An array that lists the documents in a collection. Only the document ID of each document is returned in the list. You can use the Get document method to get more information about an individual document.

404 - Missing project or collection.

code

integer

The HTTP error status code.

error

string

A message describing the error.

product documentation.

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

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

If the document is uploaded to a collection that shares its data with another collection, the X-Watson-Discovery-Force header must be set to `true`.

In curl requests only, you can assign an ID to a document that you add by appending the ID to the endpoint (`/v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}`). If a document already exists with the specified ID, it is replaced.

For more information about how certain file types and field names are handled when a file is added to a collection, see the product documentation.">

Add a document

POST /v2/projects/{project_id}/collections/{collection_id}/documents

Add a document to a collection with optional metadata.

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

Use this method to upload a file to the collection. You cannot use this method to crawl an external data source.

For a list of supported file types, see the product documentation.
You must provide document content, metadata, or both. If the request is missing both document content and metadata, it is rejected.
- You 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.
If the document is uploaded to a collection that shares its data with another collection, the X-Watson-Discovery-Force header must be set to `true`.
In curl requests only, you can assign an ID to a document that you add by appending the ID to the endpoint (`/v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}`). If a document already exists with the specified ID, it is replaced.

For more information about how certain file types and field names are handled when a file is added to a collection, see the product documentation.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

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.

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

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Not found. Returned if you attempt to add a document to a project that doesn't exist or if the collection specified isn't part of the specified project.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Too large. Returned if you attempt to add a document or document metadata that exceeds the maximum possible.

code

integer

The HTTP error status code.

error

string

A message describing the error.

415 - Unsupported. Returned if the media type of the uploaded document is not supported by Discovery..

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get document details

GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}

Get details about a specific document, whether the document is added by uploading a file or by crawling an external data source.

Note: This method is available only from Cloud Pak for Data version 4.0.9 and later installed instances, and from IBM Cloud-managed instances.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - Returns the specified document details.

document_id

string

The unique identifier of the document.

created

string

Date and time that the document is added to the collection. For a child document, the date and time when the process that generates the child document runs. The date-time format is `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.

updated

string

Date and time that the document is finished being processed and is indexed. This date changes whenever the document is reprocessed, including for enrichment changes. The date-time format is `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.

status

string

The status of the ingestion of the document. The possible values are:

`available`: Ingestion is finished and the document is indexed.
`failed`: Ingestion is finished, but the document is not indexed because of an error.
`pending`: The document is uploaded, but the ingestion process is not started.
`processing`: Ingestion is in progress.

notices

array

Array of JSON objects for notices, meaning warning or error messages, that are produced by the document ingestion process. The array does not include notices that are produced for child documents that are generated when a document is processed.

children

object

Information about the child documents that are generated from a single document during ingestion or other processing.

filename

string

Name of the original source file (if available).

file_type

string

The type of the original source file, such as `csv`, `excel`, `html`, `json`, `pdf`, `text`, `word`, and so on.

sha256

string

The SHA-256 hash of the original source file. The hash is formatted as a hexadecimal string.

404 - Missing project, collection, or document.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a document

POST /v2/projects/{project_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.

Use this method to upload a file to a collection. You cannot use this method to crawl an external data source.

If the document is uploaded to a collection that shares its data with another collection, the X-Watson-Discovery-Force header must be set to `true`.

Notes:

Uploading a new document with this method automatically replaces any existing document stored with the same document ID.
If an uploaded document is split into child documents during ingestion, all existing child documents are overwritten, even if the updated version of the document has fewer child documents.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

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

document_id

string

The unique identifier of the ingested document.

status

string

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

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Not found. Returned if the project, collection, or document ID is missing or incorrect.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Too large. Returned if you attempt to add a document or document metadata that exceeds the maximum possible.

code

integer

The HTTP error status code.

error

string

A message describing the error.

415 - Unsupported. Returned if the media type of the uploaded document is not supported by Discovery..

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a document

DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}

Deletes the document with the document ID that you specify from the collection. Removes uploaded documents from the collection permanently. If you delete a document that was added by crawling an external data source, the document will be added again with the next scheduled crawl of the data source. The delete function removes the document from the collection, not from the external data source.

Note: Files such as CSV or JSON files generate subdocuments when they are added to a collection. If you delete a subdocument, and then repeat the action that created it, the deleted document is added back in to your collection. To remove subdocuments that are generated by an uploaded file, delete the original document instead. You can get the document ID of the original document from the `parent_document_id` of the subdocument result.

If the document with the given document ID exists, Watson Discovery first marks or tags the document as deleted when it sends the 200 response code. At a later time (within a couple of minutes unless the document has many child documents), it removes the document from the collection.

There is no bulk document delete API. Documents must be deleted one at a time using this API. However, you can delete a collection, and all the documents from the collection are removed along with the collection.

The document will be deleted from the given collection only, not from the corresponding data source. Wherever relevant, an incremental crawl will not bring back the document into Watson Discovery from the data source. Only a full crawl will retrieve the deleted document back from the data source provided it is still present in the same data source.

Finally, if multiple collections share the same dataset, deleting a document from a collection will remove it from that collection only (in other remaining collections the document will still exist). The document will be removed from the dataset, if this document is deleted from all the collections that share the same dataset.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

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.

403 - Forbidden. Returned if you attempt to delete a document in a collection that connects automatically to an external source.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Not found. Returned if the project, collection, or document ID is missing or incorrect.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query collection notices

GET /v2/projects/{project_id}/collections/{collection_id}/notices

Finds collection-level notices (errors and warnings) that are generated when documents are ingested.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

filter

string

Searches for documents that match the Discovery Query Language criteria that is specified as input. Filter calls are cached and are faster than query calls because the results are not ordered by relevance. When used with the `aggregation`, `query`, or `natural_language_query` parameters, the `filter` parameter runs first. This parameter is useful for limiting results to those that contain specific metadata values.

query

string

A query search that is written in the Discovery Query Language and returns all matching documents in your data set with full enrichments and full text, and with the most relevant documents listed first. You can use this parameter or the natural_language_query parameter to specify the query input, but not both.

natural_language_query

string

A natural language query that returns relevant documents by using natural language understanding. You can use this parameter or the query parameter to specify the query input, but not both. To filter the results based on criteria you specify, include the filter parameter in the request.

count

integer

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

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

Response

200 - Query for collection notices executed successfully.

matching_results

integer

The number of matching results

notices

array

Array of document results that match the query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List training queries

GET /v2/projects/{project_id}/training_data/queries

List the training queries for the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Training data for the specified project found and returned.

queries

array

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

404 - The specified project does not exist.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete training queries

DELETE /v2/projects/{project_id}/training_data/queries

Removes all training queries for the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

204 - All training data for the specified project has been deleted.

400 - Invalid headers.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Incorrect project specified.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a training query

POST /v2/projects/{project_id}/training_data/queries

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

Note: You cannot apply relevancy training to a `content_mining` project type.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - The query was successfully added.

query_id

string

The query ID associated with the training query.

natural_language_query

string

The natural text query that is used as the training query.

filter

string

The filter used on the collection before the natural_language_query is applied. Only specify a filter if the documents that you consider to be most relevant are not included in the top 100 results when you submit test queries. If you specify a filter during training, apply the same filter to queries that are submitted at runtime for optimal ranking results.

created

string

The date and time the query was created.

updated

string

The date and time the query was updated.

examples

array

Array of training examples.

400 - Invalid headers or request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - The specified project does not exist.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get a training data query

GET /v2/projects/{project_id}/training_data/queries/{query_id}

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

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Details of the specified training query.

query_id

string

The query ID associated with the training query.

natural_language_query

string

The natural text query that is used as the training query.

filter

string

created

string

The date and time the query was created.

updated

string

The date and time the query was updated.

examples

array

Array of training examples.

404 - Query or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a training query

POST /v2/projects/{project_id}/training_data/queries/{query_id}

Updates an existing training query and its examples. You must resubmit all of the examples with the update request.

Request

Request Body

TrainingQuery

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

query_id

string

The query ID associated with the training query.

natural_language_query

Required *

string

The natural text query that is used as the training query.

filter

string

created

string

The date and time the query was created.

updated

string

The date and time the query was updated.

examples

Required *

array

Array of training examples.

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - The example was successfully added to the query.

query_id

string

The query ID associated with the training query.

natural_language_query

string

The natural text query that is used as the training query.

filter

string

created

string

The date and time the query was created.

updated

string

The date and time the query was updated.

examples

array

Array of training examples.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a training data query

DELETE /v2/projects/{project_id}/training_data/queries/{query_id}

Removes details from a training data query, including the query string and all examples.

To delete an example, use the Update a training query method and omit the example that you want to delete from the example set.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

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

404 - Query or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Query project notices

GET /v2/projects/{project_id}/notices

Finds project-level notices (errors and warnings). Currently, project-level notices are generated by relevancy training.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

filter

string

query

string

natural_language_query

string

count

integer

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

offset

integer

Response

200 - Query for project notices executed successfully.

matching_results

integer

The number of matching results

notices

array

Array of document results that match the query.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get a custom stop words list

GET /v2/projects/{project_id}/collections/{collection_id}/stopwords

Returns the custom stop words list that is used by the collection. For information about the default stop words lists that are applied to queries, see the product documentation.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - List of custom stop words or an empty array if no custom stop words list is applied to the collection.

stopwords

array

List of stop words.

the product documentation.">

Create a custom stop words list

POST /v2/projects/{project_id}/collections/{collection_id}/stopwords

Adds a list of custom stop words. Stop words are words that you want the service to ignore when they occur in a query because they're not useful in distinguishing the semantic meaning of the query. The stop words list cannot contain more than 1 million characters.

A default stop words list is used by all collections. The default list is applied both at indexing time and at query time. A custom stop words list that you add is used at query time only.

The custom stop words list augments the default stop words list; you cannot remove stop words. For information about the default stop words lists per language, see the product documentation.

Request

Request Body

StopWordList

stopwords

Required *

array

List of stop words.

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - The array of custom stop words that are applied to the collection.

stopwords

array

List of stop words.

400 - Bad request.

Unable to create stop words because request body was not valid JSON or was incorrect JSON.
Stopword creation request contained no stopwords.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Could not find named collection.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Input stopwords file is too large. Input must be less than 1000000 characters.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a custom stop words list

DELETE /v2/projects/{project_id}/collections/{collection_id}/stopwords

Deletes a custom stop words list to stop using it in queries against the collection. After a custom stop words list is deleted, the default stop words list is used.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

204 - The custom stop words list was deleted.

Get the expansion list

GET /v2/projects/{project_id}/collections/{collection_id}/expansions

Returns the current expansion list for the specified collection. If an expansion list is not specified, an empty expansions array is returned.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - Successfully fetched expansion 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: Each entry in the `expanded_terms` list expands to include all expanded terms. For example, a query for `ibm` expands to `ibm OR international business machines OR big blue`.
Unidirectional: The terms in `input_terms` in the query are replaced by the terms in `expanded_terms`. For example, a query for the often misused term `on premise` is converted to `on premises OR on-premises` and does not contain the original term. If you want an input term to be included in the query, then repeat the input term in the expanded terms list.

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 an expansion list

POST /v2/projects/{project_id}/collections/{collection_id}/expansions

Creates or replaces the expansion list for this collection. An expansion list introduces alternative wording for key terms that are mentioned in your collection. By identifying synonyms or common misspellings, you expand the scope of a query beyond exact matches. The maximum number of expanded terms allowed per collection is 5,000.

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: Each entry in the `expanded_terms` list expands to include all expanded terms. For example, a query for `ibm` expands to `ibm OR international business machines OR big blue`.
Unidirectional: The terms in `input_terms` in the query are replaced by the terms in `expanded_terms`. For example, a query for the often misused term `on premise` is converted to `on premises OR on-premises` and does not contain the original term. If you want an input term to be included in the query, then repeat the input term in the expanded terms list.

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - The expansion list has been accepted and will be 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: Each entry in the `expanded_terms` list expands to include all expanded terms. For example, a query for `ibm` expands to `ibm OR international business machines OR big blue`.
Unidirectional: The terms in `input_terms` in the query are replaced by the terms in `expanded_terms`. For example, a query for the often misused term `on premise` is converted to `on premises OR on-premises` and does not contain the original term. If you want an input term to be included in the query, then repeat the input term in the expanded terms list.

400 - Bad request.

Unable to create expansions because request body was not valid JSON or was incorrect JSON.
Query expansion creation request contained no expansions.
Request exceeded expansion mappings limit.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Could not find named collection.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete the expansion list

DELETE /v2/projects/{project_id}/collections/{collection_id}/expansions

Removes the expansion information for this collection. To disable query expansion for a collection, delete the expansion list.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

204 - The expansion list was successfully deleted.

List curations

GET /v2/projects/{project_id}/curations

Lists the currently configured curation queries and the associated curated responses. The curations API methods are beta functionality. Beta features are not supported by the SDKs.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - List of curations associated with the specified project.

project_id

string

The project ID of the project that contains these curations.

curations

array

Array of curated queries and responses.

404 - Specified project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create curation

POST /v2/projects/{project_id}/curations

Add a new curated query and specify result documents. Curations with a total of 5,000 queries and 50,000 documents are allowed per project.

Note: The curations API methods are beta functionality. Beta features are not supported by the SDKs.

Request

Request Body

Curation

Natural language query to curate and array of results to return when the query is specified.

curation_id

string

The curation ID of this curation.

natural_language_query

string

The curated natural language query.

curated_results

array

Array of curated results.

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - Curation that has been created.

curation_id

string

The curation ID of this curation.

natural_language_query

string

The curated natural language query.

curated_results

array

Array of curated results.

400 - Specified natural language query already exists.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Specified project, collection, or document not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get curation

GET /v2/projects/{project_id}/curations/{curation_id}

Gets details about the specified curation. The curations API methods are beta functionality. Beta features are not supported by the SDKs.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

curation_id

Required *

string

The ID of the curation.

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 `2023-03-31`.

Response

200 - Object that contains an array of curated results for the specified curation id.

curated_results

array

Array of curated results.

404 - Specified project or curation ID not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete curation

DELETE /v2/projects/{project_id}/curations/{curation_id}

Deletes the specified curation. The curations API methods are beta functionality. Beta features are not supported by the SDKs.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

curation_id

Required *

string

The ID of the curation.

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 `2023-03-31`.

Response

200 - Curation has been successfully deleted.

curation_id

string

The curation ID of the curation.

status

string

The current status of the specified curation.

404 - Specified project or curation id not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update curation results

POST /v2/projects/{project_id}/curations/{curation_id}/curated_results

Update an existing curated results documents for the specified query. For example, you can enhance the curated result by adding a text snippet to it. The curations API methods are beta functionality. Beta features are not supported by the SDKs.

Request

Request Body

CurationResult

Result to add to the specified curated query.

document_id

string

The document ID of the curated result.

collection_id

string

The collection ID of the curated result.

snippet

string

Text to return in the `passage_text` field when this curated document is returned for the specified natural language query. If passages.per_document is `true`, the text snippet that you specify is returned as the top passage instead of the original passage that is chosen by search. Only one text snippet can be specified per document. If passages.max_per_document is greater than `1`, the snippet is returned first, followed by the passages that are chosen by search.

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

curation_id

Required *

string

The ID of the curation.

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 `2023-03-31`.

Response

201 - Result has been added to the curation.

document_id

string

The document ID of the curated result.

collection_id

string

The collection ID of the curated result.

snippet

string

400 - Specified document ID already exists in this curation.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Specified project, collection or document not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List projects

GET /v2/projects

Lists existing projects for this 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 `2023-03-31`.

Response

200 - Successful response.

projects

array

An array of project details.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a project

POST /v2/projects

Create a new project for this instance

Request

Request Body

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 `2023-03-31`.

Response

201 - The project has successfully been created.

project_id

string

The Universally Unique Identifier (UUID) of this project.

name

string

The human readable name of this project.

type

string

The type of project.

The `content_intelligence` type is a Document Retrieval for Contracts project and the `other` type is a Custom project.

The `content_mining` and `content_intelligence` types are available with Premium plan managed deployments and installed deployments only.

The Intelligent Document Processing (IDP) project type is available from IBM Cloud-managed instances only.

relevancy_training_status

object

Relevancy training status information for this project.

collection_count

integer

The number of collections configured in this project.

default_query_parameters

DefaultQueryParams

Default query parameters for this project.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get project

GET /v2/projects/{project_id}

Get details on the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Returns information about the specified project if it exists.

project_id

string

The Universally Unique Identifier (UUID) of this project.

name

string

The human readable name of this project.

type

string

The type of project.

The `content_intelligence` type is a Document Retrieval for Contracts project and the `other` type is a Custom project.

The `content_mining` and `content_intelligence` types are available with Premium plan managed deployments and installed deployments only.

The Intelligent Document Processing (IDP) project type is available from IBM Cloud-managed instances only.

relevancy_training_status

object

Relevancy training status information for this project.

collection_count

integer

The number of collections configured in this project.

default_query_parameters

DefaultQueryParams

Default query parameters for this project.

404 - Project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a project

POST /v2/projects/{project_id}

Update the specified project's name.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Returns the updated project information.

project_id

string

The Universally Unique Identifier (UUID) of this project.

name

string

The human readable name of this project.

type

string

The type of project.

The `content_intelligence` type is a Document Retrieval for Contracts project and the `other` type is a Custom project.

The `content_mining` and `content_intelligence` types are available with Premium plan managed deployments and installed deployments only.

The Intelligent Document Processing (IDP) project type is available from IBM Cloud-managed instances only.

relevancy_training_status

object

Relevancy training status information for this project.

collection_count

integer

The number of collections configured in this project.

default_query_parameters

DefaultQueryParams

Default query parameters for this project.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project not found

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a project

DELETE /v2/projects/{project_id}

Deletes the specified project.

Important: Deleting a project deletes everything that is part of the specified project, including all collections.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

204 - The project has been deleted.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project not found

code

integer

The HTTP error status code.

error

string

A message describing the error.

List fields

GET /v2/projects/{project_id}/fields

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

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

collection_ids

array

Comma separated list of the collection IDs. If this parameter is not specified, all collections in the project are used.

Response

200 - The list of fetched fields.

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

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

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

fields

array

An array that contains information about each field in the collections.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List enrichments

GET /v2/projects/{project_id}/enrichments

Lists the enrichments available to this project. The Part of Speech and Sentiment of Phrases enrichments might be listed, but are reserved for internal use only.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Returns an array of available enrichments.

enrichments

array

An array of enrichment definitions.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project not found

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create an enrichment

POST /v2/projects/{project_id}/enrichments

Create an enrichment for use with the specified project. To apply the enrichment to a collection in the project, use the Collections API.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - The enrichment has been successfully created

enrichment_id

string

The Universally Unique Identifier (UUID) of this enrichment.

name

string

The human readable name for this enrichment.

description

string

The description of this enrichment.

type

string

The type of this enrichment.

options

EnrichmentOptions

An object that contains options for the current enrichment. Starting with version `2020-08-30`, the enrichment options are not included in responses from the List Enrichments method.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get enrichment

GET /v2/projects/{project_id}/enrichments/{enrichment_id}

Get details about a specific enrichment.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

enrichment_id

Required *

string

The Universally Unique Identifier (UUID) of the enrichment.

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 `2023-03-31`.

Response

200 - Returns information about the specified enrichment.

enrichment_id

string

The Universally Unique Identifier (UUID) of this enrichment.

name

string

The human readable name for this enrichment.

description

string

The description of this enrichment.

type

string

The type of this enrichment.

options

EnrichmentOptions

An object that contains options for the current enrichment. Starting with version `2020-08-30`, the enrichment options are not included in responses from the List Enrichments method.

404 - Enrichment or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update an enrichment

POST /v2/projects/{project_id}/enrichments/{enrichment_id}

Updates an existing enrichment's name and description.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

enrichment_id

Required *

string

The Universally Unique Identifier (UUID) of the enrichment.

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 `2023-03-31`.

Response

200 - Returns the updated enrichment details.

enrichment_id

string

The Universally Unique Identifier (UUID) of this enrichment.

name

string

The human readable name for this enrichment.

description

string

The description of this enrichment.

type

string

The type of this enrichment.

options

EnrichmentOptions

An object that contains options for the current enrichment. Starting with version `2020-08-30`, the enrichment options are not included in responses from the List Enrichments method.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Enrichment or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete an enrichment

DELETE /v2/projects/{project_id}/enrichments/{enrichment_id}

Deletes an existing enrichment from the specified project.

Note: Only enrichments that have been manually created can be deleted.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

enrichment_id

Required *

string

The Universally Unique Identifier (UUID) of the enrichment.

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 `2023-03-31`.

Response

204 - The enrichment has been successfully deleted

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Enrichment or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List document classifiers

GET /v2/projects/{project_id}/document_classifiers

Get a list of the document classifiers in a project. Returns only the name and classifier ID of each document classifier.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

200 - Returns a list of document classifiers.

classifiers

array

An array of document classifier definitions.

404 - Document project is not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a document classifier

POST /v2/projects/{project_id}/document_classifiers

Create a document classifier. You can use the API to create a document classifier in any project type. After you create a document classifier, you can use the Enrichments API to create a classifier enrichment, and then the Collections API to apply the enrichment to a collection in the project.

Note: This method is supported on installed instances (IBM Cloud Pak for Data) or IBM Cloud-managed Premium or Enterprise plan instances.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

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 `2023-03-31`.

Response

201 - Returns the document classifier details.

classifier_id

string

The Universally Unique Identifier (UUID) of the document classifier.

name

string

A human-readable name of the document classifier.

description

string

A description of the document classifier.

created

string

The date that the document classifier was created.

language

string

The language of the training data that is associated with the document classifier. Language is specified by using the ISO 639-1 language code, such as `en` for English or `ja` for Japanese.

enrichments

array

An array of enrichments to apply to the data that is used to train and test the document classifier. The output from the enrichments is used as features by the classifier to classify the document content both during training and at run time.

recognized_fields

array

An array of fields that are used to train the document classifier. The same set of fields must exist in the training data, the test data, and the documents where the resulting document classifier enrichment is applied at run time.

answer_field

string

The name of the field from the training and test data that contains the classification labels.

training_data_file

string

Name of the CSV file with training data that is used to train the document classifier.

test_data_file

string

Name of the CSV file with data that is used to test the document classifier. If no test data is provided, a subset of the training data is used for testing purposes.

federated_classification

ClassifierFederatedModel

An object with details for creating federated document classifier models.

400 - Bad request. A required parameter is null or invalid. Specific failure messages include:

No request body (missing classifier configuration).
Missing required request parameter or its value.
Unsupported language is requested.
Provided `training_data` or `test_data` does not have field requested in `answer_field`.
Requested enrichment does not exist.
Provided `training_data` or `test_data` does not have the fields requested in `enrichments.fields`.
Provided `training_data` or `test_data` does not have the field requested in `federated_classification.field`.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Missing project.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get a document classifier

GET /v2/projects/{project_id}/document_classifiers/{classifier_id}

Get details about a specific document classifier.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

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 `2023-03-31`.

Response

200 - Returns details about a specific document classifier.

classifier_id

string

The Universally Unique Identifier (UUID) of the document classifier.

name

string

A human-readable name of the document classifier.

description

string

A description of the document classifier.

created

string

The date that the document classifier was created.

language

string

The language of the training data that is associated with the document classifier. Language is specified by using the ISO 639-1 language code, such as `en` for English or `ja` for Japanese.

enrichments

array

recognized_fields

array

answer_field

string

The name of the field from the training and test data that contains the classification labels.

training_data_file

string

Name of the CSV file with training data that is used to train the document classifier.

test_data_file

string

Name of the CSV file with data that is used to test the document classifier. If no test data is provided, a subset of the training data is used for testing purposes.

federated_classification

ClassifierFederatedModel

An object with details for creating federated document classifier models.

404 - Document classifier or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a document classifier

POST /v2/projects/{project_id}/document_classifiers/{classifier_id}

Update the document classifier name or description, update the training data, or add or update the test data.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

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 `2023-03-31`.

Response

201 - Returns the updated document classifier details.

classifier_id

string

The Universally Unique Identifier (UUID) of the document classifier.

name

string

A human-readable name of the document classifier.

description

string

A description of the document classifier.

created

string

The date that the document classifier was created.

language

string

The language of the training data that is associated with the document classifier. Language is specified by using the ISO 639-1 language code, such as `en` for English or `ja` for Japanese.

enrichments

array

recognized_fields

array

answer_field

string

The name of the field from the training and test data that contains the classification labels.

training_data_file

string

Name of the CSV file with training data that is used to train the document classifier.

test_data_file

string

Name of the CSV file with data that is used to test the document classifier. If no test data is provided, a subset of the training data is used for testing purposes.

federated_classification

ClassifierFederatedModel

An object with details for creating federated document classifier models.

400 - Bad request. A required parameter is null or invalid. Specific failure messages include:

No request body (missing classifier configuration).
Provided `training_data` or `test_data` does not have field requested in `answer_field`.
Provided `training_data` or `test_data` does not have the fields requested in `enrichments.fields`.
Provided `training_data` or `test_data` does not have the field requested in `federated_classification.field`.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Missing project or classifier.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a document classifier

DELETE /v2/projects/{project_id}/document_classifiers/{classifier_id}

Deletes an existing document classifier from the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

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 `2023-03-31`.

Response

204 - The document classifier was deleted successfully.

400 - The document classifier cannot be deleted because the resulting classifier enrichment is applied to a collection. You must remove the enrichment from any collections that are using it before you attempt to delete the document classifier.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Missing project or classifier.

code

integer

The HTTP error status code.

error

string

A message describing the error.

List document classifier models

GET /v2/projects/{project_id}/document_classifiers/{classifier_id}/models

Get a list of the document classifier models in a project. Returns only the name and model ID of each document classifier model.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

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 `2023-03-31`.

Response

200 - Returns a list of document classifier models.

models

array

An array of document classifier model definitions.

404 - Document classifier or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create a document classifier model

POST /v2/projects/{project_id}/document_classifiers/{classifier_id}/models

Create a document classifier model by training a model that uses the data and classifier settings defined in the specified document classifier.

Note: This method is supported on installed intances (IBM Cloud Pak for Data) or IBM Cloud-managed Premium or Enterprise plan instances.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

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 `2023-03-31`.

Response

201 - Returns the document classifier details.

model_id

string

The Universally Unique Identifier (UUID) of the document classifier model.

name

string

A human-readable name of the document classifier model.

description

string

A description of the document classifier model.

created

string

The date that the document classifier model was created.

updated

string

The date that the document classifier model was last updated.

training_data_file

string

Name of the CSV file that contains the training data that is used to train the document classifier model.

test_data_file

string

Name of the CSV file that contains data that is used to test the document classifier model. If no test data is provided, a subset of the training data is used for testing purposes.

status

string

The status of the training run.

evaluation

ClassifierModelEvaluation

An object that contains information about a trained document classifier model.

enrichment_id

string

The Universally Unique Identifier (UUID) of the enrichment that is generated by this document classifier model.

deployed_at

string

The date that the document classifier model was deployed.

400 - Bad request. A required parameter is null or invalid. Specific failure messages include:

No request body (discovery_missing_model_config).
Missing required request parameter or its value (classifier_missing_field_name).

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Missing project or classifier.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Get a document classifier model

GET /v2/projects/{project_id}/document_classifiers/{classifier_id}/models/{model_id}

Get details about a specific document classifier model.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

model_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier model.

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 `2023-03-31`.

Response

200 - Returns details about a specific document classifier model.

model_id

string

The Universally Unique Identifier (UUID) of the document classifier model.

name

string

A human-readable name of the document classifier model.

description

string

A description of the document classifier model.

created

string

The date that the document classifier model was created.

updated

string

The date that the document classifier model was last updated.

training_data_file

string

Name of the CSV file that contains the training data that is used to train the document classifier model.

test_data_file

string

Name of the CSV file that contains data that is used to test the document classifier model. If no test data is provided, a subset of the training data is used for testing purposes.

status

string

The status of the training run.

evaluation

ClassifierModelEvaluation

An object that contains information about a trained document classifier model.

enrichment_id

string

The Universally Unique Identifier (UUID) of the enrichment that is generated by this document classifier model.

deployed_at

string

The date that the document classifier model was deployed.

404 - Project or document classifier or document classifier model not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a document classifier model

POST /v2/projects/{project_id}/document_classifiers/{classifier_id}/models/{model_id}

Update the document classifier model name or description.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

model_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier model.

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 `2023-03-31`.

Response

201 - Returns the updated document classifier model details.

model_id

string

The Universally Unique Identifier (UUID) of the document classifier model.

name

string

A human-readable name of the document classifier model.

description

string

A description of the document classifier model.

created

string

The date that the document classifier model was created.

updated

string

The date that the document classifier model was last updated.

training_data_file

string

Name of the CSV file that contains the training data that is used to train the document classifier model.

test_data_file

string

Name of the CSV file that contains data that is used to test the document classifier model. If no test data is provided, a subset of the training data is used for testing purposes.

status

string

The status of the training run.

evaluation

ClassifierModelEvaluation

An object that contains information about a trained document classifier model.

enrichment_id

string

The Universally Unique Identifier (UUID) of the enrichment that is generated by this document classifier model.

deployed_at

string

The date that the document classifier model was deployed.

400 - No request body.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project or document classifier or document classifier model not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a document classifier model

DELETE /v2/projects/{project_id}/document_classifiers/{classifier_id}/models/{model_id}

Deletes an existing document classifier model from the specified project.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

classifier_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier.

model_id

Required *

string

The Universally Unique Identifier (UUID) of the classifier model.

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 `2023-03-31`.

Response

204 - The document classifier model was deleted successfully.

400 - The document classifier model cannot be deleted because the resulting classifier enrichment is applied to a collection. You must remove the enrichment from any collections that are using it before you attempt to delete the model.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project or document classifier or document classifier model not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Analyze a document

POST /v2/projects/{project_id}/collections/{collection_id}/analyze

Process a document and return it for realtime use. Supports JSON files only.

The file is not stored in the collection, but is processed according to the collection's configuration settings. To get results, enrichments must be applied to a field in the collection that also exists in the file that you want to analyze. For example, to analyze text in a `Quote` field, you must apply enrichments to the `Quote` field in the collection configuration. Then, when you analyze the file, the text in the `Quote` field is analyzed and results are written to a field named `enriched_Quote`.

Submit a request against only one collection at a time. Remember, the documents in the collection are not significant. It is the enrichments that are defined for the collection that matter. If you submit requests to several collections, then several models are initiated at the same time, which can cause request failures.

Note: This method is supported with Enterprise plan deployments and installed deployments only.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - The analyzed document.

notices

array

Array of notices that are triggered when the files are processed.

result

AnalyzedResult

Result of the document analysis.

400 - Bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

403 - Collection not supported for Analyze.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Project or collection not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

408 - Analyze timeout.

code

integer

The HTTP error status code.

error

string

A message describing the error.

413 - Document or metadata too large.

code

integer

The HTTP error status code.

error

string

A message describing the error.

415 - Unsupported media type.

code

integer

The HTTP error status code.

error

string

A message describing the error.

429 - Too many requests, try again later.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Information security.

Note: This method is only supported on IBM Cloud instances of Discovery.">

Delete labeled data

DELETE /v2/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.

Note: This method is only supported on IBM Cloud instances of Discovery.

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 `2023-03-31`.

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.

Get collection details

GET /v2/projects/{project_id}/collections/{collection_id}

Get details about the specified collection.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - Returns the specified collection details.

collection_id

string

The Universally Unique Identifier (UUID) of the collection.

name

string

The name of the collection.

description

string

A description of the collection.

created

string

The date that the collection was created.

language

string

The language of the collection. For a list of supported languages, see the product documentation.

ocr_enabled

boolean

If set to `true`, optical character recognition (OCR) is enabled. For more information, see Optical character recognition.

enrichments

array

An array of enrichments that are applied to this collection. To get a list of enrichments that are available for a project, use the List enrichments method.

webhooks

Webhooks

An object with webhook information. For more information, see Document status webhook API.

conversions

Conversions

Document processing operations that occur during the document conversion phase of ingestion.

Note: Available only from service instances that are managed by IBM Cloud.

normalizations

Normalizations

Defines operations that normalize the JSON representation of data after enrichments are applied. Operations run in the order that is specified in this array.

Note: Available only from service instances that are managed by IBM Cloud.

smart_document_understanding

object

An object that describes the Smart Document Understanding model for a collection.

source_document_counts

object

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

document_counts

object

Object with counts of documents in the collection grouped by document status.

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

404 - Collection or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Update a collection

POST /v2/projects/{project_id}/collections/{collection_id}

Updates the specified collection's name, description, enrichments, and configuration.

If you apply normalization rules to data in an existing collection, you must initiate reprocessing of the collection. To do so, from the Manage fields page in the product user interface, temporarily change the data type of a field to enable the reprocess button. Change the data type of the field back to its original value, and then click Apply changes and reprocess.

To remove a configuration that applies JSON normalization operations as part of the conversion phase of ingestion, specify an empty `json_normalizations` object (`[]`) in the request.

To remove a configuration that applies JSON normalization operations after enrichments are applied, specify an empty `normalizations` object (`[]`) in the request.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - Returns the updated collection details.

collection_id

string

The Universally Unique Identifier (UUID) of the collection.

name

string

The name of the collection.

description

string

A description of the collection.

created

string

The date that the collection was created.

language

string

The language of the collection. For a list of supported languages, see the product documentation.

ocr_enabled

boolean

If set to `true`, optical character recognition (OCR) is enabled. For more information, see Optical character recognition.

enrichments

array

An array of enrichments that are applied to this collection. To get a list of enrichments that are available for a project, use the List enrichments method.

webhooks

Webhooks

An object with webhook information. For more information, see Document status webhook API.

conversions

Conversions

Document processing operations that occur during the document conversion phase of ingestion.

Note: Available only from service instances that are managed by IBM Cloud.

normalizations

Normalizations

Defines operations that normalize the JSON representation of data after enrichments are applied. Operations run in the order that is specified in this array.

Note: Available only from service instances that are managed by IBM Cloud.

smart_document_understanding

object

An object that describes the Smart Document Understanding model for a collection.

source_document_counts

object

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

document_counts

object

Object with counts of documents in the collection grouped by document status.

Document status information is returned asynchronously. If counts are zero, wait a minute and then use the Get collection details method to check the status.

Note: Available from installed instances starting with Cloud Pak for Data 4.7 and from IBM Cloud-managed instances only.

400 - Bad request.

No request body.
Missing project or collection.
Invalid normalization operation is requested.
Missing normalization source.
Missing normalization destination.
Invalid normalization destination.

code

integer

The HTTP error status code.

error

string

A message describing the error.

404 - Collection or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Delete a collection

DELETE /v2/projects/{project_id}/collections/{collection_id}

Deletes the specified collection from the project. All documents stored in the specified collection and not shared is also deleted.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

204 - The collection has successfully been deleted.

404 - Collection or project not found.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Create enrichment API method.

Use the List batches API to get the following:

Notified batches that are not yet pulled by the external enrichment application.
Batches that are pulled, but not yet pushed to Discovery by the external enrichment application.">

List batches

GET /v2/projects/{project_id}/collections/{collection_id}/batches

A batch is a set of documents that are ready for enrichment by an external application. After you apply a webhook enrichment to a collection, and then process or upload documents to the collection, Discovery creates a batch with a unique batch_id.

To start, you must register your external application as a webhook type by using the Create enrichment API method.

Use the List batches API to get the following:

Notified batches that are not yet pulled by the external enrichment application.
Batches that are pulled, but not yet pushed to Discovery by the external enrichment application.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) 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 `2023-03-31`.

Response

200 - Returns an array of available batches that are ready to be pulled by the external enrichment application.

The batches timeout automatically after around 72 hours from the time they were created.

batches

array

An array that lists the batches in a collection.

404 - Missing project or collection, or bad request.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Pull batches

GET /v2/projects/{project_id}/collections/{collection_id}/batches/{batch_id}

Pull a batch of documents from Discovery for enrichment by an external application. Ensure to include the `Accept-Encoding: gzip` header in this method to get the file. You can also implement retry logic when calling this method to avoid any network errors.

Request

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) of the collection.

batch_id

Required *

string

The Universally Unique Identifier (UUID) of the document batch that is being requested from Discovery.

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 `2023-03-31`.

Response

200 - Returns a compressed NDJSON file.

file

string

A compressed NDJSON file containing the document.

404 - Not found. Returned when the project, collection, or batch is missing.

code

integer

The HTTP error status code.

error

string

A message describing the error.

Push batches

POST /v2/projects/{project_id}/collections/{collection_id}/batches/{batch_id}

Push a batch of documents to Discovery after annotation by an external application. You can implement retry logic when calling this method to avoid any network errors.

Request

Request Body

Path Parameters

project_id

Required *

string

The Universally Unique Identifier (UUID) of the project. This information can be found from the Integrate and Deploy page in Discovery.

collection_id

Required *

string

The Universally Unique Identifier (UUID) of the collection.

batch_id

Required *

string

The Universally Unique Identifier (UUID) of the document batch that is being requested from Discovery.

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 `2023-03-31`.

Response

202 - The batch has been accepted and is being processed.

404 - Not found. Returned when the project, collection, or batch is missing. It is also returned when the batch is already processed or when a batch gets timed out.

code

integer

The HTTP error status code.

error

string

A message describing the error.

409 - The batch is already pushed and accepted. Returned between the time the batch is submitted and the time when Discovery is processing the submitted documents.

code

integer

The HTTP error status code.

error

string

A message describing the error.