automatically detects the language.">

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

automatically detects the language.">

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