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 |
Note:
Grammar, transformation, and pronunciation files are restricted to Nuance Professional Services users and not available to all users. As such, the package exported by regular users will not include these files.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.
Note:
Grammar, transformation, and pronunciation files are restricted to Nuance Professional Services users and not available to all users. As such, regular users will not be able to replace these files.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
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
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
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
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
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
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
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.
Warning:
This endpoint may permanently delete data.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
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
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
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
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
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
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
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
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
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
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.