How to create projects in orchestration workflow

Orchestration workflow allows you to create projects that connect your applications to:

Custom Language Understanding
Question Answering
LUIS

Prerequisites

Before you start using orchestration workflow, you will need several things:

An Azure subscription - Create one for free.
An Azure Language in Foundry Tools resource

Create a Language resource

Before you start using orchestration workflow, you will need a Language resource.

Note

You need to have an owner role assigned on the resource group to create a Language resource.
If you're planning to use question answering, you have to enable question answering in resource creation

Create a new resource from the Azure portal

Go to the Azure portal to create a new Azure Language in Foundry Tools resource.
Select Continue to create your resource
Create a Language resource with following details.

Instance detail Required value

Region One of the supported regions.

Name A name for your Language resource.

Pricing tier One of the supported pricing tiers.

Instance detail	Required value
Region	One of the supported regions.
Name	A name for your Language resource.
Pricing tier	One of the supported pricing tiers.

Create an orchestration workflow project (REST API)

Once you have a Language resource created, create an orchestration workflow project.

Submit a PATCH request using the following URL, headers, and JSON body to create a new project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	The name for your project. This value is case-sensitive.	`myProject`
`{API-VERSION}`	The version of the API you're calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.

Body

Use the following sample JSON as your body.

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

Key	Placeholder	Value	Example
`projectName`	`{PROJECT-NAME}`	The name of your project. This value is case-sensitive.	`EmailApp`
`language`	`{LANGUAGE-CODE}`	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code for most of the utterances.	`en-us`

Import an orchestration workflow project (REST API)

You can import an orchestration workflow JSON into the service

Submit a POST request using the following URL, headers, and JSON body to import your project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	The name for your project. This value is case-sensitive.	`myProject`
`{API-VERSION}`	The version of the API you're calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.

Body

Note

Each intent should only be of one type only from (CLU,LUIS and qna)

Use the following sample JSON as your body.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

Key	Placeholder	Value	Example
`api-version`	`{API-VERSION}`	The version of the API you're calling. The version used here must be the same API version in the URL.	`2022-03-01-preview`
`projectName`	`{PROJECT-NAME}`	The name of your project. This value is case-sensitive.	`EmailApp`
`language`	`{LANGUAGE-CODE}`	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code for most of the utterances.	`en-us`

Export project (REST API)

You can export an orchestration workflow project as a JSON file at any time.

Create a POST request using the following URL, headers, and JSON body to export your project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	The name for your project. This value is case-sensitive.	`EmailApp`
`{API-VERSION}`	The version of the API you're calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.

Once you send your API request, you receive a 202 response indicating success. In the response headers, extract the operation-location value formatted like this:

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

JOB-ID is used to identify your request, since this operation is asynchronous. Use this URL to get the exported project JSON, using the same authentication method.

Get orchestration project details (REST API)

To get an orchestration workflow project's details, submit a GET request using the following URL and headers. Replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	The name for your project. This value is case-sensitive.	`myProject`
`{API-VERSION}`	The version of the API you're calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.

Response Body

Once you send the request, you get the following response.

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Orchestration",
  "projectName": "{PROJECT-NAME}",
  "description": "This is a sample orchestration project.",
  "language": "{LANGUAGE-CODE}"
}

Once you send your API request, you receive a 200 response indicating success and JSON response body with your project details.

Delete project (REST API)

When you don't need your project anymore, you can delete your project using the APIs.

Create a DELETE request using the following URL, headers, and JSON body to delete a conversational language understanding project.

Request URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	The name for your project. This value is case-sensitive.	`myProject`
`{API-VERSION}`	The version of the API you're calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.

Once you send your API request, you receive a 202 response indicating success, which means your project is deleted.

Next Steps

Build schema

Feedback

Was this page helpful?

Last updated on 2025-12-18

Share via

How to create projects in orchestration workflow

Prerequisites

Create a Language resource

Create a new resource from the Azure portal

Create an orchestration workflow project (REST API)

Request URL

Headers

Body

Import an orchestration workflow project (REST API)

Request URL

Headers

Body

Export project (REST API)

Request URL

Headers

Get orchestration project details (REST API)

Headers

Response Body

Delete project (REST API)

Request URL

Headers

Next Steps

Feedback

Additional resources