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

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