Projects

When you create a project, you specify:

  • The language topic
  • The list of languages that will be supported
  • The list of channels and modalities that will be available for the project

A project is created in an organization and is shared with all the members in this organization. If a user is not part of the organization in which a project is created, this user will not see the project. To share a project with a user that is not in your organization, you must add that user as a member of the project.

Users also have a role inside a project. Members can have one of the following default project roles:

  • Owner: Can perform all actions on the project.
  • Admin: Can perform all actions on the project except:
    • Delete the project
    • Edit project details
  • Viewer: Can see the organization details, projects, and applications, but cannot edit them.

About exported project packages

The package files exported with the project and metadata export endpoints use the following naming convention:

projectid-projectname-[metadata]-exportdate-exporttime[.zip|.json]

Where:

  • projectid is the ID of the project
  • projectname is the name of the project
  • metadata indicates that the metadata file was 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)

The project package is exported to a .zip file; the metadata package is exported to a .json file.

For example:

  • Package export: 2960-Coffee App-2021-05-27-20-39-10.zip
  • Metadata export: 2960-Coffee App-metadata-2021-06-02-17-26-49.json

Project package file structure

A project package can include the following files:

File name Description Availability Package export Metadata export
dialog.json File that defines the dialog application. See the Dialog application specification for details. All users X
metadata.json File that defines the metadata of the project, such as the date and time the project was created, name of the project, channels and modalities of the project, and so on. All users X X
locale/locale.trsx
(for example, en_US/en_US.trsx)		 TRSX file that defines the NLU ontology for a locale. The content provided depends on the type of package exported (complete project or ontology only). See the TRSX documentation for details. All users X
locale/grammars/* 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. Nuance Professional Services users
(see note)		 X
locale/_client_prons.txt ASR pronunciation file. Only available if pronunciations have been uploaded for this project. Nuance Professional Services users
(see note)		 X
locale/_tmfe.tsv ASR transformations file. Only available if a Transformation Modeling Front End (TMFE) file has been uploaded for this project. Nuance Professional Services users
(see note)		 X

Replacing a project package

When you replace a project package, the contents of the files included in the project package replace the content of the project.

Make sure to include all the files described in Project package file structure, following the same structure, otherwise your project may not be replaced correctly.

Get list of Mix projects

GET /v4/projects

Retrieve the list of Mix projects to which you have access, across all organizations. This endpoint returns an extended set of attributes for each project.

You can limit the number of results returned and use an offset to determine the starting position of results returned.

Responses

Status Meaning Description Schema
200 OK List of projects mix.api.ListExtendedProjectsResponse
401 Unauthorized Request could not be authorized Inline
404 Not Found No content 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 Nuance data pack version

PUT /v4/projects/{projectId}/.datapack

Update the Nuance data pack version used by a project for a locale.

Parameters

Name In Type Description
projectId path string ID of the project for which to update the Nuance data pack.
body body mix.api.DataPackUpdateRequest Locale to update and new version to update it to.

Body parameter

{
  "locale": "string",
  "version": "string"
}

Responses

Status Meaning Description Schema
200 OK Job to update data pack successfully created mix.api.JobResponse
401 Unauthorized Request could not be authorized Inline
404 Not Found Project or data pack 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  

Get organization projects

GET /v4/organizations/{orgId}/projects

Retrieve the list of projects available in an organization.

Responses

Status Meaning Description Schema
200 OK List of projects mix.api.ListProjectsResponse
401 Unauthorized Request could not be authorized Inline
404 Not Found Organization 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  

Create a new project

POST /v4/organizations/{orgId}/projects

Create a new project in an organization.

Nuance’s Child Data Policy is related to online services that are subject to applicable child data privacy laws, such as, but not limited to, the Children’s Online Privacy Protection Act (COPPA) and Article 8 of GDPR. Nuance’s Child Data Policy prohibits providing hosted services to websites or online services that are primarily directed towards children under the age of 16.

When you create a project, you are required to acknowledge whether or not the builds for this project will be used in an application that is deployed in a Nuance hosted service in connection with an online site, service, application or product that is primarily directed to children under 16. This acknowledgement must be completed for any projects that are intended for use in the Nuance SaaS cloud.

To acknowledge such a project, set the isChildDataCompliant parameter to YES and provide a description of the project in projectDescription.

Parameters

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

Body parameter

{
  "displayName": "string",
  "languages": [
    "string"
  ],
  "languageTopic": "string",
  "channels": [
    {
      "displayName": "string",
      "modes": [
        "MODE_UNSPECIFIED"
      ],
      "color": "COLOR_UNSPECIFIED"
    }
  ],
  "projectDescription": "string",
  "isChildDataCompliant": "NO",
  "enginePackId": "string"
}

Responses

Status Meaning Description Schema
200 OK Project successfully created mix.api.CreateProjectResponse
401 Unauthorized Request could not be authorized Inline
404 Not Found Organization 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  

Get project details

GET /v4/projects/{projectId}

Retrieve the details of a project.

Responses

Status Meaning Description Schema
200 OK Project details mix.api.GetProjectResponse
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

  200 response  

Delete a project

DELETE /v4/projects/{projectId}

Delete a project.

Responses

Status Meaning Description Schema
200 OK Project successfully deleted google.rpc.Status
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

  200 response  

Rename a project

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

Rename a project.

Parameters

Name In Type Description
projectId path string ID of the project to rename.
body body mix.api.RenameProjectPayload Object that defines the new project name.

Body parameter

{
  "displayName": "string"
}

Responses

Status Meaning Description Schema
200 OK Project successfully renamed mix.api.RenameProjectPayload
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

  200 response  

Export the project package

GET /v4/projects/{projectId}/.export

Export the project package to a .zip file. Note that the grammar, transformation, and pronunciation files are restricted and not available to all users. As such, the project package exported by regular users will not include these files. Regular users may end up with an incomplete project after calling this endpoint. See About exported project packages for details.

Responses

Status Meaning Description Schema
200 OK Project package (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

Replace project content

POST /v4/projects/{projectId}/.replace

Replace the project content with the .zip file provided in the content parameter.

When replacing an existing project, Nuance recommends that you back up the existing project by first exporting it. Note that the grammar, transformation, and pronunciation files are restricted and not available to all users. As such, regular users are not allowed to replace grammar, transformation, and pronunciation files, so they may end up with an incomplete project after calling this endpoint. See Replacing a project package for details.

Parameters

Name In Type Description
projectId path string ID of project to replace.
» content body string (binary) Zip file of the project content to replace.

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  

Export the project metadata

GET /v4/projects/{projectId}/metadata/.export

Export the project metadata to a .json file.

Responses

Status Meaning Description Schema
200 OK Project metadata (json file, with application/json 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

Get project lock

GET /v4/projects/{projectId}/.lock

Retrieve the details of a specific project lock.

Responses

Status Meaning Description Schema
200 OK Project lock details mix.api.GetProjectLockResponse
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

  200 response  

Unlock a project

PUT /v4/projects/{projectId}/.unlock

Unlock a project. Other users with appropriate permissions will now be able to edit the project.

Responses

Status Meaning Description Schema
200 OK Project successfully unlocked google.rpc.Status
401 Unauthorized Request could not be authorized Inline
403 Forbidden Request not allowed 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

  200 response  

Lock a project

PUT /v4/projects/{projectId}/.lock

Lock a project. When you lock a project, other users will be able to view the project in Mix.nlu, Mix.dialog, and the Mix dashboard but will not be able to edit the project. Also, other Mix.api users will not be able to call endpoints that edit the project; these endpoints will return an error message indicating that the project is locked.

Parameters

Name In Type Description
projectId path string ID of the project to lock.
body body mix.api.LockRequest Object that defines the project lock notes.

Body parameter

{
  "notes": "string"
}

Responses

Status Meaning Description Schema
200 OK Project successfully locked mix.api.LockProjectResponse
400 Bad Request Bad request 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

Example responses

  200 response  

Get project locks

GET /v4/projects/.locks

Retrieve the list of projects locks in all organizations.

You can limit the number of results returned and use an offset to determine the starting position of results returned.

By default, results are sorted by alphabetical order of lock ID. You can also sort the results by another field and specify the sort order with the - or + sign. For example, to sort by alphabetical order of projectId, enter +projectId.

Note that this endpoint is restricted to Nuance Professional Services and global admin users.

Responses

Status Meaning Description Schema
200 OK List of projects locks mix.api.ListProjectsLocksResponse
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 project channel

POST /v4/projects/{projectId}/channels

Create a new channel in a project.

Parameters

Name In Type Description
projectId path string ID of the project where to create the channel.
body body mix.api.ChannelRequest Object that defines the project channel to create.

Body parameter

{
  "displayName": "string",
  "modes": [
    "MODE_UNSPECIFIED"
  ],
  "color": "COLOR_UNSPECIFIED"
}

Responses

Status Meaning Description Schema
200 OK Project channel details mix.api.CreateProjectChannelResponse
400 Bad Request Project not found Inline
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  

Update project channel

PUT /v4/projects/{projectId}/.channel

Update the channel details in a project.

Parameters

Name In Type Description
projectId path string ID of the project for which to update the channel.
body body mix.api.UpdateChannelRequest Object that defines the project channel to update.

Body parameter

{
  "channelId": "string",
  "modes": [
    "MODE_UNSPECIFIED"
  ],
  "color": "COLOR_UNSPECIFIED"
}

Responses

Status Meaning Description Schema
200 OK Updated project channel details mix.api.UpdateProjectChannelResponse
400 Bad Request Project not found Inline
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  

Activate project channel

PUT /v4/projects/{projectId}/channels/{channelId}/.activate

Activate a channel in a project.

Parameters

Name In Type Description
projectId path string ID of the project.
channelId path string ID of the channel.
body body object Leave this body empty.

Responses

Status Meaning Description Schema
200 OK Project channel successfully activated google.rpc.Status
400 Bad Request Project not found Inline
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  

Deactivate project channel

PUT /v4/projects/{projectId}/channels/{channelId}/.deactivate

Deactivate a channel in a project.

Parameters

Name In Type Description
projectId path string ID of the project.
channelId path string ID of the channel.
body body object Leave this body empty.

Responses

Status Meaning Description Schema
200 OK Project channel successfully deactivated google.rpc.Status
400 Bad Request Project not found Inline
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  

Rename project channel

PUT /v4/projects/{projectId}/channels/{channelId}/.rename

Rename a channel in a project.

Parameters

Name In Type Description
projectId path string ID of project for which to rename the channel.
channelId path string ID of the channel to rename.
body body mix.api.RenameProjectChannelPayload New channel name.

Body parameter

{
  "displayName": "Updated channel name"
}

Responses

Status Meaning Description Schema
200 OK Project channel successfully renamed mix.api.RenameProjectChannelPayload
400 Bad Request Project not found Inline
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