API v1 to v2 Migration guide for LUIS apps

Important

LUIS will be retired on October 1st 2025 and starting April 1st 2023 you will not be able to create new LUIS resources. We recommend migrating your LUIS applications to conversational language understanding to benefit from continued product support and multilingual capabilities.

The version 1 endpoint and authoring APIs are deprecated. Use this guide to understand how to migrate to version 2 endpoint and authoring APIs.

New Azure regions

LUIS has new regions provided for the LUIS APIs. LUIS provides a different portal for region groups. The application must be authored in the same region you expect to query. Applications do not automatically migrate regions. You export the app from one region then import into another for it to be available in a new region.

Authoring route changes

The authoring API route changed from using the prog route to using the api route.

version	route
1	/luis/v1.0/prog/apps
2	/luis/api/v2.0/apps

Endpoint route changes

The endpoint API has new query string parameters as well as a different response. If the verbose flag is true, all intents, regardless of score, are returned in an array named intents, in addition to the topScoringIntent.

version	GET route
1	/luis/v1/application?ID={appId}&q={q}
2	/luis/v2.0/apps/{appId}?q={q}[&timezoneOffset][&verbose][&spellCheck][&staging][&bing-spell-check-subscription-key][&log]

v1 endpoint success response:

{
  "odata.metadata":"https://dialogice.cloudapp.net/odata/$metadata#domain","value":[
    {
      "id":"bccb84ee-4bd6-4460-a340-0595b12db294","q":"turn on the camera","response":"[{\"intent\":\"OpenCamera\",\"score\":0.976928055},{\"intent\":\"None\",\"score\":0.0230718572}]"
    }
  ]
}

v2 endpoint success response:

{
  "query": "forward to frank 30 dollars through HSBC",
  "topScoringIntent": {
    "intent": "give",
    "score": 0.3964121
  },
  "entities": [
    {
      "entity": "30",
      "type": "builtin.number",
      "startIndex": 17,
      "endIndex": 18,
      "resolution": {
        "value": "30"
      }
    },
    {
      "entity": "frank",
      "type": "frank",
      "startIndex": 11,
      "endIndex": 15,
      "score": 0.935219169
    },
    {
      "entity": "30 dollars",
      "type": "builtin.currency",
      "startIndex": 17,
      "endIndex": 26,
      "resolution": {
        "unit": "Dollar",
        "value": "30"
      }
    },
    {
      "entity": "hsbc",
      "type": "Bank",
      "startIndex": 36,
      "endIndex": 39,
      "resolution": {
        "values": [
          "BankeName"
        ]
      }
    }
  ]
}

Key management no longer in API

The subscription endpoint key APIs are deprecated, returning 410 GONE.

version	route
1	/luis/v1.0/prog/subscriptions
1	/luis/v1.0/prog/subscriptions/{subscriptionKey}

Azure endpoint keys are generated in the Azure portal. You assign the key to a LUIS app on the Publish page. You do not need to know the actual key value. LUIS uses the subscription name to make the assignment.

New versioning route

The v2 model is now contained in a version. A version name is 10 characters in the route. The default version is "0.1".

version	route
1	/luis/v1.0/prog/apps/{appId}/entities
2	/luis/api/v2.0/apps/{appId}/versions/{versionId}/entities

Metadata renamed

Several APIs that return LUIS metadata have new names.

v1 route name	v2 route name
PersonalAssistantApps	assistants
applicationcultures	cultures
applicationdomains	domains
applicationusagescenarios	usagescenarios

"Sample" renamed to "suggest"

LUIS suggests utterances from existing endpoint utterances that may enhance the model. In the previous version, this was named sample. In the new version, the name is changed from sample to suggest. This is called Review endpoint utterances in the LUIS website.

version	route
1	/luis/v1.0/prog/apps/{appId}/entities/{entityId}/sample
1	/luis/v1.0/prog/apps/{appId}/intents/{intentId}/sample
2	/luis/api/v2.0/apps/{appId}/versions/{versionId}/entities/{entityId}/suggest
2	/luis/api/v2.0/apps/{appId}/versions/{versionId}/intents/{intentId}/suggest

Create app from prebuilt domains

Prebuilt domains provide a predefined domain model. Prebuilt domains allow you to quickly develop your LUIS application for common domains. This API allows you to create a new app based on a prebuilt domain. The response is the new appID.

v2 route	verb
/luis/api/v2.0/apps/customprebuiltdomains	get, post
/luis/api/v2.0/apps/customprebuiltdomains/{culture}	get

Importing 1.x app into 2.x

The exported 1.x app's JSON has some areas that you need to change before importing into LUIS 2.0.

Prebuilt entities

The prebuilt entities have changed. Make sure you are using the V2 prebuilt entities. This includes using datetimeV2, instead of datetime.

Actions

The actions property is no longer valid. It should be an empty

Labeled utterances

V1 allowed labeled utterances to include spaces at the beginning or end of the word or phrase. Removed the spaces.

Common reasons for HTTP response status codes

See LUIS API response codes.

Next steps

Use the v2 API documentation to update existing REST calls to LUIS endpoint and authoring APIs.