Entities

An entity is a language construct for a property, or particular detail, related to the user’s intent. For example, if the user’s intent is to order an espresso drink, entities might include COFFEE_TYPE, FLAVOR, TEMPERATURE, and so on.

See Overview of entities for more information about entity, literals, and values.

About exported entity literals

The package file exported with the export entity literals endpoint uses the following naming convention:

projectid-projectname-entityname-entity-literals-exportdate-exporttime.zip

Where:

projectid is the ID of the project
projectname is the name of the project
entityname is the name of the entity for which literal-value pairs were exported
exportdate is the date that the package was exported, in the yyyy-mm-dd format
exporttime is the time that the package was exported, in the hh-mm-ss format, using Greenwich Mean Time (GMT)

For example:

COFFEE_TYPE grammar export: 2960-Coffee App-COFFEE_TYPE-entity-literals-2021-06-02-20-36-54.zip

Entity literals package file content

An entity literals package includes one or more TRSX file, one for each locale in the project:

File name	Description
locale.trsx (for example, `en_US.trsx`)	TRSX file that defines the entity literal-value pairs for the locale. See the TRSX documentation for details.

Replacing and appending entity literals

When you replace entity literals, the information included in the package replaces the existing samples in the project.

When you append entity literals, the entity literals are added to the existing ones.

The file provided must be one of the following:

A valid TRSX file; see the TRSX documentation for details
A .list or .nmlist file; see Importing entity literals for details

About exported rule-based grammars

The package file exported with the export rule-based grammar endpoint uses the following naming convention:

projectid_grammarname_grammars.zip

where:

projectid is the ID of the project
grammarname is the name of the rule-based grammar

For example:

CARD_TYPE grammar export: 2960_CARD_TYPE_grammars.zip

Rule-based grammars package file structure

A rule-based grammar package can include the following files:

File name	Description	Availability
locale/name.grxml (for example, `en_US/CARD_TYPE.grxml`)	GrXML files that define any rule-based grammars. See Rule-based entities for details. Only available if rule-based grammars have been defined for this project.	Expert and Professional Services users (see note)

Note:

Note that rule-based grammars are restricted to Nuance Professional Services users and users with Expert organization role. As such, the package exported by regular users will not include these files.

Replacing rule-based grammars

When you replace a rule-based grammar, the grammars included in the zip file replace the existing rule-based grammars.

The GrXML files must be provided in a .zip file, in a folder identifying the locale for the grammar (for example, en-US/CARD_TYPE.grxml).

Note:

Note that rule-based grammars are restricted to Nuance Professional Services users and users with Expert organization role. As such, regular users will not be able to replace these files.

Get entities

GET /v4/projects/{projectId}/entities

Retrieve the list of entities available in a project.

Responses

Status	Meaning	Description	Schema
200	OK	List of entities	mix.api.ListEntitiesResponse
401	Unauthorized	Request could not be authorized	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Create a new entity

POST /v4/projects/{projectId}/entities

Create a new entity in a project. If creating a rule-based entity, a dummy GrXML rule will be used for all languages. This rule can be updated using the Replace rule-based grammar endpoint.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project under which the entity will be created.
body	body	mix.api.CreateEntityPayload	Object that defines the entity to create.

Body parameter

{
  "listEntity": {
    "name": "BILL_PAID",
    "isDynamic": false,
    "settings": {
      "isSensitive": false,
      "canonicalize": true
    },
    "dataType": "YES_NO",
    "data": {
      "en-US": {
        "entries": [
          {
            "meaning": "yes",
            "patterns": [
              "yes"
            ]
          },
          {
            "meaning": "no",
            "patterns": [
              "no"
            ]
          }
        ]
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Entity successfully created	mix.api.CreateEntityResponse
401	Unauthorized	Request could not be authorized	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Get entity details

GET /v4/projects/{projectId}/entities/{entityName}

Retrieve the details of an entity in a project.

Responses

Status	Meaning	Description	Schema
200	OK	Entity details	mix.api.GetEntityResponse
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Delete an entity

DELETE /v4/projects/{projectId}/entities/{entityName}

Delete an entity from a project.

Responses

Status	Meaning	Description	Schema
200	OK	Entity successfully deleted	google.rpc.Status
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Update an entity

PUT /v4/projects/{projectId}/entities/{entityName}

Update an entity’s properties in a project.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project for which to update an entity.
entityName	path	string	Name of the entity to update.
body	body	mix.api.EntityPayload	Object that defines the content to update.

Body parameter

{
  "listEntity": {
    "settings": {
      "isSensitive": true
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Entity successfully updated	mix.api.UpdateEntityResponse
400	Bad Request	The request was invalid; for example, when attempting to change an entity’s type	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Rename an entity

PUT /v4/projects/{projectId}/entities/{entityName}/.rename

Rename an entity in a project.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project for which to rename the entity.
entityName	path	string	Name of the entity to update.
body	body	mix.api.RenameEntityRequest.EntityName	Object that defines the new entity name.

Body parameter

{
  "newEntityName": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Entity successfully renamed	mix.api.RenameEntityResponse
400	Bad Request	The request was invalid	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Change entity type

PUT /v4/projects/{projectId}/entities/{entityName}/.type

Update the type of an entity to another type. If updating to a regex type, a valid regular expression pattern must be provided and will be applied to all languages initially. If updating to a rule-based grammar, a dummy GrXML rule will be used for all languages initially. This rule can be updated using the Replace rule-based grammar endpoint.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project for which to change the entity type.
entityName	path	string	Name of the entity to update.
body	body	mix.api.ChangeEntityTypeRequest.ChangeEntityTypeData	Object that defines the new entity type.

Body parameter

{
  "newType": "UNSPECIFIED",
  "pattern": "string",
  "isA": "string",
  "hasA": {
    "entities": [
      "string"
    ]
  },
  "data": {
    "property1": {
      "entries": [
        {
          "meaning": "string",
          "patterns": [
            "string"
          ]
        }
      ]
    },
    "property2": {
      "entries": [
        {
          "meaning": "string",
          "patterns": [
            "string"
          ]
        }
      ]
    }
  },
  "dataType": "NOT_SET"
}

Responses

Status	Meaning	Description	Schema
200	OK	Entity type successfully changed	mix.api.ChangeEntityTypeResponse
400	Bad Request	The request was invalid; for example, an invalid regular expression for a Regex entity was provided	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Export rule-based grammar

GET /v4/projects/{projectId}/entities/{entityName}/grammars/.export

Export the rule-based GrXML grammars for an entity. Note that exporting rule-based grammars is restricted
and not available to all users. See About exported rule-based grammars for details.

Responses

Status	Meaning	Description	Schema
200	OK	A .zip file of the grammar(s)	Inline
400	Bad Request	The request was invalid	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Replace rule-based grammar

POST /v4/projects/{projectId}/entities/{entityName}/grammars/.replace

Replace the rule-based GrXML grammars for an entity. The GrXML files must be provided in a .zip file, in a folder identifying the locale for the grammar (for example, en-US/grammar.grxml). Note that replacing rule-based grammars is restricted and not available to all users. See Replacing rule-based grammars for details.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project for which to replace the grammar.
entityName	path	string	Name of entity for which to replace the grammar.
» content	body	string (binary)	File that contains the new GrXML content.

Responses

Status	Meaning	Description	Schema
200	OK	Entity GrXML rules updated successfully	mix.api.ReplaceRuleBasedGrammarsResponse
400	Bad Request	The request was invalid	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Entity not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

200 response

Export the entity literals package

GET /v4/projects/{projectId}/entities/{entityName}/literals/.export

Export the literal-value pairs for an entity.

Responses

Status	Meaning	Description	Schema
200	OK	Literal-value pairs (zip file, with application/octet-stream content-type)	Inline
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Project not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Append the entity literals

PUT /v4/projects/{projectId}/entities/{entityName}/literals/.append

Append the literal-value pairs in the provided file to the existing ones for the specified project and entity. The literal-value pairs must be provided in a valid TRSX file (.trsx), a .list file, or a .nmlist file.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project to append literal-value pairs to.
entityName	path	string	Case-sensitive name of the entity to append the literal-value pairs to.
locale	query	string	Locale for which the literal-value pairs will be appended.
» content	body	string (binary)	Entity literals content file. Can be .trsx, .nmlist or .list.

Responses

Status	Meaning	Description	Schema
200	OK	Job successfully created	mix.api.JobResponse
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Project not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

Job successfully created

Replace entity literals

POST /v4/projects/{projectId}/entities/{entityName}/literals/.replace

Replace the existing literal-value pairs associated with an entity with the ones provided in the file. The literal-value pairs must be provided in a valid TRSX file (.trsx), a .list file, or a .nmlist file.

Warning:

This endpoint will delete any existing literal-value pairs.

Parameters

Name	In	Type	Description
projectId	path	string	ID of project for which to replace literal-value pairs.
entityName	path	string	Case-sensitive name of the entity for which to replace literal-value pairs.
locale	query	string	Locale for which to replace literal-value pairs.
» content	body	string (binary)	Entity literals content file. Can be .trsx, .nmlist or .list.

Responses

Status	Meaning	Description	Schema
200	OK	Job successfully created	mix.api.JobResponse
401	Unauthorized	Request could not be authorized	Inline
404	Not Found	Project not found	Inline
500	Internal Server Error	Internal server error	Inline
default	Default	An unexpected error response.	grpc.gateway.runtime.Error

Example responses

Job successfully created

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.