Managing grammars

Listing grammars for a custom language model

The customization interface provides two methods for listing information about the grammars for a custom language model:

• The GET /v1/customizations/{customization_id}/grammars method lists information about all grammars for a custom model.
• The GET /v1/customizations/{customization_id}/grammars/{grammar_name} method lists information about a specified grammar for a custom model.

Both methods return the same information about a grammar. The information includes the name of the grammar and, for custom models based on previous-generation models, the number of out-of_vocabulary_words that are recognized by the grammar. The response also includes the status of the grammar, which is important for checking the service's analysis of the grammar when you add it to a custom model:

• being_processed indicates that the service is still processing the grammar in response to a POST /v1/customizations/{customization_id}/grammars/{grammar_name} request.

• analyzed indicates that the service has successfully processed the grammar and added it to the custom model.

• undetermined means that the service encountered an error while processing the grammar. The information that is returned for the grammar includes an error message that offers guidance for correcting the error.

  For example, the grammar might be invalid, or you might have tried to add a grammar with the same name as an existing grammar. You can try to add the grammar again and include the allow_overwrite parameter with the request. You can also delete the grammar and then try adding it again.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/grammars"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/grammars"

{
  "grammars": [
    {
      "out_of_vocabulary_words": 0,
      "name": "confirm-xml",
      "status": "analyzed"
    },
    {
      "out_of_vocabulary_words": 0,
      "name": "confirm-abnf",
      "status": "analyzed"
    },
    {
      "out_of_vocabulary_words": 8,
      "name": "list-abnf",
      "status": "analyzed"
    }
  ]
}

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/grammars/list-abnf"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/grammars/list-abnf"

{
  "out_of_vocabulary_words": 8,
  "name": "list-abnf",
  "status": "analyzed"
}

Deleting a grammar from a custom language model

Use the DELETE /v1/customizations/{customization_id}/grammars/{grammar_name} method to remove an existing grammar from a custom language model. When it deletes the grammar, the service removes any OOV words that are associated with the grammar from the custom model's words resource unless

• The word was also added by another grammar or by a corpus.
• The word was modified in some way with the POST /v1/customizations/{customization_id}/words or PUT /v1/customizations/{customization_id}/words/{word_name} method.

Removing a grammar does not affect the custom model until you train the model on its updated data by using the POST /v1/customizations/{customization_id}/train method. If you successfully trained the model on the grammar, the grammar continues to be available for speech recognition until you retrain the model.

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/grammars/list-abnf"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/grammars/list-abnf"