Analyze text (GET)
GET /v1/analyze
Analyzes raw text, HTML, or a public webpage.
If a language for the input text is not specified with the `language` parameter, the service automatically detects the language.
Request
Path Parameters
Query Parameters
text
string
URL-encoded text to analyze. One of the `text`, `html`, or `url` parameters is required.
html
string
URL-encoded HTML to analyze. One of the `text`, `html`, or `url` parameters is required.
url
string
Public webpage to analyze. One of the `text`, `html`, or `url` parameters is required. `url` is not supported in IBM Cloud Dedicated instances.
features
Required *
array
Comma separated list of analysis features
return_analyzed_text
boolean
Set this to `true` to show the analyzed text in the response
clean
boolean
Set this to `false` to disable text cleaning when analyzing webpages. For more information about webpage cleaning, see Analyzing webpages.
xpath
string
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
boolean
Whether to use raw HTML content if text cleaning fails
language
string
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.
categories.explanation
boolean
Set this to `true` to return explanations for each categorization. This feature is available only for English language text.
categories.limit
integer
Maximum number of categories to return.
categories.model
string
(Beta) Enter a custom model ID to override the standard categories model. This feature is available only for English language text.
classifications.model
string
Model ID of the classifications model to be used
concepts.limit
integer
Maximum number of concepts to return.
emotion.document
boolean
Set this to `false` to hide document-level emotion results
emotion.targets
array
Target strings, separated by commas. Emotion results will be returned for each target string found in the document
entities.limit
integer
Maximum number of entities to return.
entities.mentions
boolean
Set this to `true` to return locations of entity mentions
entities.model
string
Enter a custom model ID to override the standard entity detection model
entities.emotion
boolean
Set this to `true` to return emotion information for detected entities
entities.sentiment
boolean
Set this to `true` to return sentiment information for detected entities
keywords.limit
integer
Maximum number of keywords to return.
keywords.emotion
boolean
Set this to `true` to return emotion information for detected keywords
keywords.sentiment
boolean
Set this to `true` to return sentiment information for detected keywords
relations.model
string
Enter a custom model ID to override the default `en-news` relations model
semantic_roles.limit
integer
Maximum number of semantic_roles results to return
semantic_roles.entities
boolean
Set this to `true` to return entity information for subjects and objects
semantic_roles.keywords
boolean
Set this to `true` to return keyword information for subjects and objects
sentiment.document
boolean
Set this to `false` to disable document level sentiment analysis
sentiment.targets
array
Sentiment information will return for each target string that is found in the text
syntax.tokens
boolean
Set this to `true` to return information about the tokens in the input text.
syntax.tokens.lemma
boolean
Set this to `true` to return the lemma for each token.
syntax.tokens.part_of_speech
boolean
Set this to `true` to return the part of speech for each token.
syntax.sentences
boolean
Set this to `true` to return information about the sentences in the input text.
limit_text_characters
integer
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
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
Request Body
Parameters
An object containing request parameters. The `features` object and one of the `text`, `html`, or `url` attributes are required.
text
string
The plain text to analyze. One of the `text`, `html`, or `url` parameters is required.
html
string
The HTML file to analyze. One of the `text`, `html`, or `url` parameters is required.
url
string
The webpage to analyze. One of the `text`, `html`, or `url` parameters is required.
features
Required *
object
Analysis features and options
classifications
object
Returns text classifications for the content.
concepts
object
Returns high-level concepts in the content. For example, a research paper about deep learning might return the concept, "Artificial Intelligence" although the term is not mentioned.
Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
emotion
object
Detects anger, disgust, fear, joy, or sadness that is conveyed in the content or by the context around target phrases specified in the targets parameter. You can analyze emotion for detected entities with `entities.emotion` and for keywords with `keywords.emotion`.
Supported languages: English
entities
object
Identifies people, cities, organizations, and other entities in the content. For more information, see Entity types and subtypes.
Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish. Arabic, Chinese, and Dutch are supported only through custom models.
keywords
object
Returns important keywords in the content.
Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish.
metadata
object
Returns information from the document, including author name, title, RSS/ATOM feeds, prominent page image, and publication date. Supports URL and HTML input types only.
relations
object
Recognizes when two entities are related and identifies the type of relation. For example, an `awardedTo` relation might connect the entities "Nobel Prize" and "Albert Einstein". For more information, see Relation types.
Supported languages: Arabic, English, German, Japanese, Korean, Spanish. Chinese, Dutch, French, Italian, and Portuguese custom models are also supported.
semantic_roles
object
Parses sentences into subject, action, and object form.
Supported languages: English, German, Japanese, Korean, Spanish.
sentiment
object
Analyzes the general sentiment of your content or the sentiment toward specific target phrases. You can analyze sentiment for detected entities with `entities.sentiment` and for keywords with `keywords.sentiment`.
Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish
summarization
object
(Experimental) Returns a summary of content.
Supported languages: English only.
Supported regions: Dallas region only
categories
object
Returns a hierarchical taxonomy of the content. The top three categories are returned by default.
Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
syntax
object
Returns tokens and sentences from the input text.
clean
boolean
Set this to `false` to disable webpage cleaning. For more information about webpage cleaning, see Analyzing webpages.
xpath
string
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
boolean
Whether to use raw HTML content if text cleaning fails
return_analyzed_text
boolean
Whether or not to return the analyzed text
language
string
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
integer
Sets the maximum number of characters that are processed by the service.
advanced_rules.model
string
The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.
An advanced rules model ID
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
Path Parameters
Query Parameters
version
Required *
string
Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is `2022-04-07`.
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
Path Parameters
model_id
Required *
string
Model ID of the model to delete
Query Parameters
version
Required *
string
Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is `2022-04-07`.
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
Request Body
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
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
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
Request Body
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
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
Request Body
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
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
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
Request Body
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
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