API version comparison

For most API methods, the request parameters and response bodies differ between v1 and v2. Learn about the equivalent or alternative v2 methods that you can use to do actions that are supported by the v1 API.

The comparison information assumes you are using the latest version of the v1 API (version 2019-04-30) and compares it to the latest version of the v2 API (version 2020-08-30).

Environments

There is no concept of an environment in v2. The deployment details such as size and index capacity are managed based on the service plan type. In v2, collections are organized in projects. You can create different types of projects to apply default configuration settings to the collections that you add to the projects.

There are no equivalent methods in v2 for the v1 environment methods. However, the following table shows v2 methods that serve similar functions to the corresponding v1 methods. The supported parameters and response bodies that are returned for each method differ also.

Environment API action support details
Action	v1 API	Related v2 API
Create an environment	`POST /v1/environments`	`POST /v2/projects`
List environments	`GET /v1/environments`	`GET /v2/projects`
Get environment info	`GET /v1/environments/{environment_id}`	`GET /v2/projects/{project_id}`
Update an environment	`PUT /v1/environments/{environment_id}`	`POST /v2/projects/{project_id}` v2 uses `POST` instead of `PUT`.
Delete an environment	`DELETE /v1/environment/{environment_id}`	`DELETE /v2/projects/{project_id}`
List fields across collections	`GET /v1/environments/{environment_id}/fields`	`GET /v2/projects/{project_id}/fields`

Configurations

The v2 API does not have an endpoint that is dedicated to configurations. Instead, configuration settings for projects, collections, and queries are specified directly in the API for those objects. Not all of the configuration parameters that are available in v1 are available or applicable in v2.

In the v1 configuration API, the JSON object that is used to specify a configuration object contains several parameters that are either available in different formats from other v2 endpoints or are not available in v2. The following table describes how to find related parameters in v2.

You cannot customize the conversion of documents during the ingestion process in v2 as you can in v1.

Configuration setting details
v1 configuration parameter	v2 API
`"conversions.html": { ... }`	Not available
`"conversions.image_text_recognition": { ... }`	Not available from the API. However, you can enable optical character recognition (OCR) for a collection from the product user interface to extract text from images. OCR has other benefits, too. For example, if a page in a document can't be processed, OCR converts the page into an image and scans it to ensure that the document is uploaded successfully.
`"conversions.json_normalizations": { ... }`	Moved to the Collections API.
`"conversions.pdf": { ... }`	Not available. If you used special parameters to extract text from images in PDFs, enable optical character recognition (OCR) from the product user interface for the collection that contains the PDFs instead.
`"conversions.segment": { ... }`	Not available programmatically. You can split a document at each occurrence of an SDU-generated field such as `subtitle` from the product user interface. The `segment_metadata` object with `parent_id`, `id`, and `total_segments` information is not available in v2. You can use the `metadata.parent_document_id` field to find the common parent for many document segments.
`"conversions.word": { ... }`	Not available
`"enrichments": { ... }`	`/v2/projects/{project_id}/enrichments`, `/v2/projects/{project_id}/collections/{collection_id}` Use the enrichments API to explore existing enrichments. Use the collections API to see and change the enrichments that are enabled on a field in a collection. Some enrichments are applied to the service by default based on the type of project that you create. For more details, see Default project settings. The version of the Entities enrichment that is available in v2 doesn't include the `disambiguation` field, which in v1 contains the disambiguation information for the entity and includes the entity subtype information. The following enrichments are not available in v2: Categories Concepts Emotion Relations Semantic roles Sentiment of Entities Sentiment of Keywords
`"normalizations": [ ... ]`	Moved to the Collections API.
`"source": { ... }`	Not available. Configure connections to external data sources through the user interface. For more information, see Creating collections.

Collections

Collections API support details
Action	v1 API	v2 API
Create a collection	`POST /v1/environments/{environment_id}/collections`	`POST /v2/projects/{project_id}/collections` The supported parameters and responses differ between the two versions. See the collection notes.
List collections	`GET /v1/environments/{environment_id}/collections`	`GET /v2/projects/{project_id}/collections` In v2, only the collection ID and name of each collection are returned in the list. You must use the Get collection method to return more details about each collection.
Get collection details	`GET /v1/environments/{environment_id}/collections/{collection_id}`	`GET /v2/projects/{project_id}/collections/{collection_id}` See the collection notes.
Update a collection	`PUT /v1/environments/{environment_id}/collections/{collection_id}`	`POST /v2/projects/{project_id}/collections/{collection_id}`
Delete a collection	`DELETE /v1/environments/{environment_id}/collections/{collection_id}`	`DELETE /v2/projects/{project_id}/collections/{collection_id}` In v2, the `status` field is not returned in the response.
List collection fields	GET /v1/environments/{environment_id}/collections/{collection_id}/fields v1 lists the fields per collection.	GET /v2/projects/{project_id}/fields v2 lists fields per project instead. You can pass a single collection ID with the `collection_ids` parameter to get fields from a single collection.

Collections API notes

The following table shows the important differences between the v1 and v2 collection APIs.

Collections API notes
Method	Notes
Create a collection	The v2 response doesn't include the `status` and `configuration_id` fields. You can get status information for a specific document by using the Get document details method. The objects `disk_usage`, `training_status`, and `crawl_status` are not present in the response body in v2. The `document_counts` object is not present in the response body in v2 currently. Training status is returned in the Get project method response. The other information is not available in v2. In v2, you can define the enrichments to apply to the documents in the collection by specifying an optional `enrichments` object.
Get collection details	The v2 response doesn't include the `status` and `configuration_id` fields. You can get status information for a specific document by using the Get document details method. The objects `document_counts`, `disk_usage`, `training_status`, and `crawl_status` are not present in the response body in v2. Training status is returned in the Get project method response. The other information is not available in v2. For example, you cannot get the document count for a collection and cannot get the crawl status for a collection that connects to an external data source in v2. In v2, you can get information about the enrichments that are applied to the collection.
Update a collection	v2 uses `POST` instead of `PUT`. In v2, you can update the enrichments that are applied to the documents in the collection by specifying an optional `enrichments` object. The v2 response doesn't include the `status` and `configuration_id` fields.

Query modifications

The method that was available in v1 for configuring tokenization programmatically is not supported in the v2 API.

Query modifications API support details
v1 API	v2 API
Tokenization dictionary API	Not available.
Expansions v1 API	Expansions v2 API
Stopwords v1 API	Stopwords v2 API

Documents

Documents API support details
Action	v1 API	v2 API
List documents	Not available from the v1 API	GET /v2/projects/{project_id}/collections/{collection_id}/documents
Create a document	`POST /v1/environments/{environment_id}/collections/{collection_id}/documents`	`POST /v2/projects/{project_id}/collections/{collection_id}/documents` Unlike v1, the v2 response does not include a notices object. However, you can get notices information by using the Get document details method in v2.
Update a document	`POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	`POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}` When you update a document that was split, all of the document segments are overwritten.
Get document details	`GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id} In v2, there is no `statusDescription`. v2 has a `children` object with information about any notices that are associated with the child documents that are generated during ingestion.
Delete a document	`DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	`DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}` Segments of an uploaded document cannot be deleted individually. Delete all segments with a DELETE request that includes the parent_document_id of a segment result.

v2 introduces a custom header that is named X-Watson-Discovery-Force that is not available in v1. You must include the header when you perform an operation on data that is shared across many collections to indicate that you want to perform the operation in each collection. If you do not include the header, a 403 error is returned.

Fields from JSON files that are added to a collection are converted differently during ingestion between v1 and v2. For more information about how JSON files are stored in the v2 index, see JSON files.

Queries

Documents API support details
Action	v1 API	v2 API
Query a collection	Supports a GET or POST request. GET or POST /v1/environments/{environment_id}/collections/{collection_id}/query	Queries a project. To specify a single collection, include the {collection_id} parameter. Supports a POST request only. POST /v2/projects/{project_id}/query
Query multiple collections	GET or POST /v1/environments/{environment_id}/query	POST /v2/projects/{project_id}/query
Query system notices	GET /v1/environments/{environment_id}/collections/{collection_id}/notices	GET /v2/projects/{project_id}/collections/{collection_id}/notices
Query multiple collection system notices	GET /v1/environments/{environment_id}/notices	GET /v2/projects/{project_id}/notices
Get Autocomplete suggestions	/v1/environments/{environment_id}/collections/{collection_id}/autocompletion	GET /v2/projects/{project_id}/autocompletion See the query notes.

Some query result configurations are applied to the service by default based on the type of project that you create. For more details, see Default project settings.

Query notes

v2 queries return results from all of the collections in the project. To restrict the query to use only certain collections within the project, use the collection_ids query parameter. You cannot query multiple collections that are added to different projects with one v2 query request.
v2 results include a confidence field, but not a score field.

The confidence score replaced the score information in v1, but score was retained for backward compatibility. In v2, only the confidence field is returned.
Use POST calls (instead of GET calls) to submit queries with v2.

v1 queries accept many parameters. The Query parameters comparison table maps v1 parameters to v2 parameters.

Query parameters comparison
v1 parameter	v2 parameter	Notes
N/A	collection_ids	Use this parameter in v2 to specify collection ids.
filter	filter	Same expression language.
query	query	Same expression language.
natural_language_query	natural_language_query	No notes.
passages	passages	The passage format changed and was enhanced in v2. The `passages:true` parameter changed to `passages.enable:true`. In addition to the `count`, `characters`, and `fields` options, you can specify `per_document`, which ranks the documents by document quality, and then returns the highest-ranked passages per document. You can also specify `find_answers` to return an answer object per passage, which contains a succinct answer to the query.
aggregation	aggregation	Same expression language.
count	count	No notes.
offset	offset	No notes.
return	return	No notes.
sort	sort	No notes.
highlight	highlight	If `passages.enabled` and `passages.per_document` are `true`, then passages are returned for each document instead of highlights.
spelling_suggestions	spelling_suggestions	No notes.
deduplicate	N/A	Not supported in v2.
similar	similar	The format changed in v2. The `similar:true` parameter changed to `similar.enable:true`. The `document_ids` and `fields` parameters changed from strings to string arrays. The `document_ids` parameter now is required if `enabled` is true.
bias	N/A	Not supported in v2.

Training data

You can use the v1 training data API to work with two related objects:

trained queries
examples that are used to train the queries

These two objects have separate API endpoints in v1. In v2, the examples that are used to train each query are provided together with the query and only one endpoint is used to work with the training data.

For example, to add a trained query and its training example documents in v2, you use the request POST /v2/projects/{project_id}/training_data/queries and pass the query and all examples in the payload of one call. Similarly, if you want to update one example in the training set in v2, you must pass the query and the modified example (along with all of the other examples) to the v2 update endpoint. In v1, to update the example information, you use the update example endpoint to modify one example only.

Another important difference between v1 and v2 is that in v1, the trained model is associated with a particular collection. In v2, the trained model is associated with a project. You can use the data from multiple collections within a project to train a relevancy model. When you create or update training examples in v2, the API requires the collection_id for the collection where the document is stored.

Training data API support details
Action	v1 API	v2 API
List training data	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`GET /v2/projects/{project_id}/training_data /queries`
Add query to training data	`POST /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`POST /v2/projects/{project_id}/training_data /queries`
Delete all training data	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`DELETE /v2/projects/{project_id}/training_data /queries`
Get details about a query	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}`	`GET /v2/projects/{project_id}/training_data /queries/{query_id}`
Delete a training data query	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}`	`DELETE /v2/projects/{project_id}/training_data /queries/{query_id}`
List examples for a training data query	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples`	`GET /v2/projects/{project_id}/training_data /queries/{query_id}` The examples are in the list that is returned with the query.
Add example to training data query	`POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples`	`POST /v2/projects/{project_id}/training_data /queries/{query_id}` Use the Create training query method in v2 and pass all examples when you create the query. Otherwise, use the update API.
Delete example for training data query	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	`POST /v2/projects/{project_id}/training_data/ queries/{query_id}` Use the v2 training_data update method.
Change label or cross-reference for example	`PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	`POST /v2/projects/{project_id}/training_data/ queries/{query_id}` Use the v2 training_data update method.
Get details for a training data example	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	Not available. Use the Read all examples call to get all examples associated with a query and find the example that you need in the returned list.

User data

The user data API is the same in v2 and v1.

User data API support details
Action	v1 API	v2 API
Delete	`DELETE /v1/user_data`	`DELETE /v2/user_data` Similar to v1. Use `customer_id` to delete the data associated with that customer ID.

Events and feedback

The v1 events and feedback API (/v1/events) is not available in v2.

Credentials

The v1 credentials API (/v1/environments/{environment_id}/credentials) is not available in v2. The function is available from the v2 product user interface.

Gateway configuration

The v1 gateways API (/v1/environments/{environment_id}/gateways) is not available in v2. The function is available from the v2 product user interface. For more information, see Installing IBM Secure Gateway for on-premises data.

Status codes

For almost every API method, the status codes that are returned for v2 requests are different from the status codes that are returned for v1 requests.