Analyze text
POST /v1/analyze
Analyzes text, HTML, or a public webpage for the following features:
- Categories
- Classifications
- Concepts
- Emotion
- Entities
- Keywords
- Metadata
- Relations
- Semantic roles
- Sentiment
- Syntax
- Summarization (Experimental)
If a language for the input text is not specified with the `language` parameter, the service automatically detects the language.
Request
Parameters
features
Required *
Features
Specific features to analyze the document for.
text
str
The plain text to analyze. One of the `text`, `html`, or `url` parameters is required.
html
str
The HTML file to analyze. One of the `text`, `html`, or `url` parameters is required.
url
str
The webpage to analyze. One of the `text`, `html`, or `url` parameters is required.
clean
bool
Set this to `false` to disable webpage cleaning. For more information about webpage cleaning, see Analyzing webpages.
Default: true
xpath
str
An XPath query to perform on `html` or `url` input. Results of the query will be appended to the cleaned webpage text before it is analyzed. To analyze only the results of the XPath query, set the `clean` parameter to `false`.
fallback_to_raw
bool
Whether to use raw HTML content if text cleaning fails.
Default: true
return_analyzed_text
bool
Whether or not to return the analyzed text.
Default: false
language
str
ISO 639-1 code that specifies the language of your text. This overrides automatic language detection. Language support differs depending on the features you include in your analysis. For more information, see Language support.
limit_text_characters
int
Sets the maximum number of characters that are processed by the service.
Response
200 -
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
List models
GET /v1/models
Lists Watson Knowledge Studio custom entities and relations models that are deployed to your Natural Language Understanding service.
Request
Parameters
Response
200 -
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
Delete model
DELETE /v1/models/{model_id}
Deletes a custom model
Request
Parameters
model_id
Required *
str
Model ID of the model to delete.
Response
200 -
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
Create categories model
POST /v1/models/categories
(Beta) Creates a custom categories model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.
Request
Parameters
language
Required *
str
The 2-letter language code of this model.
training_data
Required *
BinaryIO
Training data in JSON format. For more information, see Categories training data requirements.
training_data_content_type
str
The content type of training_data.
Allowed values: json, application/json
name
str
An optional name for the model.
user_metadata
dict
An optional map of metadata key-value pairs to store with this model.
Example: {"region":"North America","latest":true}
description
str
An optional description of the model.
model_version
str
An optional version string.
workspace_id
str
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
version_description
str
The description of the version.
Response
201 - Model created successfully
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
List categories models
GET /v1/models/categories
(Beta) Returns all custom categories models associated with this service instance.
Request
Parameters
Response
200 - Models retrieved
models
array
The categories models
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Get categories model details
GET /v1/models/categories/{model_id}
(Beta) Returns the status of the categories model with the given model ID.
Request
Parameters
model_id
Required *
str
ID of the model.
Response
200 - Model retrieved
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Update categories model
PUT /v1/models/categories/{model_id}
(Beta) Overwrites the training data associated with this custom categories model and retrains the model. The new model replaces the current deployment.
Request
Parameters
model_id
Required *
str
ID of the model.
language
Required *
str
The 2-letter language code of this model.
training_data
Required *
BinaryIO
Training data in JSON format. For more information, see Categories training data requirements.
training_data_content_type
str
The content type of training_data.
Allowed values: json, application/json
name
str
An optional name for the model.
user_metadata
dict
An optional map of metadata key-value pairs to store with this model.
Example: {"region":"North America","latest":true}
description
str
An optional description of the model.
model_version
str
An optional version string.
workspace_id
str
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
version_description
str
The description of the version.
Response
200 - Model overwrite successful
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Delete categories model
DELETE /v1/models/categories/{model_id}
(Beta) Un-deploys the custom categories model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.
Request
Parameters
model_id
Required *
str
ID of the model.
Response
200 -
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Create classifications model
POST /v1/models/classifications
Creates a custom classifications model by uploading training data and associated metadata. The model begins the training and deploying process and is ready to use when the `status` is `available`.
Request
Parameters
language
Required *
str
The 2-letter language code of this model.
training_data
Required *
BinaryIO
Training data in JSON format. For more information, see Classifications training data requirements.
training_data_content_type
str
The content type of training_data.
Allowed values: json, application/json
name
str
An optional name for the model.
user_metadata
dict
An optional map of metadata key-value pairs to store with this model.
Example: {"region":"North America","latest":true}
description
str
An optional description of the model.
model_version
str
An optional version string.
workspace_id
str
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
version_description
str
The description of the version.
training_parameters
ClassificationsTrainingParameters
Optional classifications training parameters along with model train requests.
Response
201 - Model created successfully
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
List classifications models
GET /v1/models/classifications
Returns all custom classifications models associated with this service instance.
Request
Parameters
Response
200 - Models retrieved
models
array
The classifications models
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Get classifications model details
GET /v1/models/classifications/{model_id}
Returns the status of the classifications model with the given model ID.
Request
Parameters
model_id
Required *
str
ID of the model.
Response
200 - Model retrieved
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Update classifications model
PUT /v1/models/classifications/{model_id}
Overwrites the training data associated with this custom classifications model and retrains the model. The new model replaces the current deployment.
Request
Parameters
model_id
Required *
str
ID of the model.
language
Required *
str
The 2-letter language code of this model.
training_data
Required *
BinaryIO
Training data in JSON format. For more information, see Classifications training data requirements.
training_data_content_type
str
The content type of training_data.
Allowed values: json, application/json
name
str
An optional name for the model.
user_metadata
dict
An optional map of metadata key-value pairs to store with this model.
Example: {"region":"North America","latest":true}
description
str
An optional description of the model.
model_version
str
An optional version string.
workspace_id
str
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding.
version_description
str
The description of the version.
training_parameters
ClassificationsTrainingParameters
Optional classifications training parameters along with model train requests.
Response
200 - Model overwrite successful
name
string
An optional name for the model
user_metadata
object
An optional map of metadata key-value pairs to store with this model
language
string
The 2-letter language code of this model
description
string
An optional description of the model
model_version
string
An optional version string
version
string
Deprecated — use `model_version`
workspace_id
string
ID of the Watson Knowledge Studio workspace that deployed this model to Natural Language Understanding
version_description
string
The description of the version
features
array
The service features that are supported by the custom model
status
string
When the status is `available`, the model is ready to use
model_id
string
Unique model ID
created
string
dateTime indicating when the model was created
notices
array
last_trained
string
dateTime of last successful model training
last_deployed
string
dateTime of last successful model deployment
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error
Delete classifications model
DELETE /v1/models/classifications/{model_id}
Un-deploys the custom classifications model with the given model ID and deletes all associated customer data, including any training data or binary artifacts.
Request
Parameters
model_id
Required *
str
ID of the model.
Response
200 -
400 - Invalid request
code
integer
The HTTP error status code
error
string
A message describing the error
403 - Access forbidden
code
integer
The HTTP error status code
error
string
A message describing the error