# REST API ## Instructions The API key and deployed URL can be found by navigating to your application's deployment: * Navigate to *Applications* in workspace menu > Select application * Choose your application's *Deployment* tab * Click *Details* on the latest deployment * Expand the *Setup instructions* for the API channel * Copy the *Application URL* and *API key* *** ## OpenAPI spec of the API channel REST endpoint {% file src="/files/tolRZfPVj1nd47KgpaB5" %} Download OpenAPI Specification {% endfile %} {% openapi src="/files/JFRmcn2XWQsuF7uRCXfs" path="/c/{deploymentId}/{channelId}" method="post" %} [openapi.yaml](https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2FRVC6DnVR17KiBk8Xjqc9%2Fopenapi.yaml?alt=media\&token=d0f01399-8c3e-417e-8877-5f7a83423920) {% endopenapi %} *** ## Sample requests ```bash # sending an unstructured request curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \ -H 'content-type: application/json' \ -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \ --data-raw '{"request":{"unstructured":{"text":"hello there!"}}}' \ --compressed # sending a structured request with a specified intent curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \ -H 'content-type: application/json' \ -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \ --data-raw '{"request":{"structured":{"intentId":"GreetingIntent"}}}' \ --compressed # sending a structured request with a choiceId curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \ -H 'content-type: application/json' \ -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \ --data-raw '{"request":{"structured":{"choiceId":"ABC123456789"}}}' \ --compressed # sending a structured request with an intentId and slots curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \ -H 'content-type: application/json' \ -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \ --data-raw '{"request":{"structured":{"intentId":"GreetingIntent","slots":[{"slotId":"Confirmation","value":"yes"}]}}}' \ --compressed # sending an unstructured request with a specific conversationId, userId, and context curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \ -H 'content-type: application/json' \ -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \ --data-raw '{"conversationId": "abc1234lkjhgf","userId":"poiuytrewq098765","request":{"unstructured":{"text":"hello there!"}},"context":{"originPage":"contact"}}' \ --compressed ``` *** ## Modalities [Modalities](/platform/nlx-platform-guide/flows-and-building-blocks/modalities.md) that have been set on a conversation flow node will come back in the response under the `modalities` property as an object where each key is the name of the modality you have created. For example, if you wanted to display a video as a message within your client application, you could define a Video modality like so:
Video modality example
When the conversation reaches the node where the Video [modality is enabled](/platform/nlx-platform-guide/flows-and-building-blocks/modalities.md#use-a-modality), the API response may contain the following: ```json { // API reponse properties // ... "modalities": { "Video": { "title": "Tutorial", "url": "", "resolution": 1080 } } } ``` The modalities can then be interpreted by the client application and a video may be displayed. *** ## Node Payloads A [node payload](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#add-functionality) that has been set on a conversation flow node will come back in the response under the `payload` property as a string. For example, if you wanted to apply a confetti effect to the client application upon completing a purchase, you could send the following payload:
When the conversation reaches the last node where the node payload is set, the API response may contain the following: ```json { // API reponse properties // ... "payload": "confettiDisplay=true" } ``` The payload can then be interpreted by the client application and a confetti effect could be triggered along with the confirmation message. *** ## Choice payloads Custom slot values can contain a predefined [choice payload](broken://pages/QXjePzwOq37RfhbKZd87#add-values), which can be especially useful to sort values within your client application. For example, assume you want to display a list of 10 countries for the end user to choose from. But, you have a slot value called "Other" which needs to always appear last in the list, no matter the language your application is using, while the rest of the values follow an alphabetical order. You could add `isLastValue` to the choice payload field of the custom slot value:

Choice payload field of a custom slot value

When a conversation reaches a [*User choice*](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#user-choice) node (make sure the *Show choices* toggle is on) with a custom slot that contains a choice payload for at least one of the values, the API response may contain the following: ```json { // API reponse properties // ... "messages": [ { // other message properties // ... "choices": [ { "choiceId": "PM9IDxF-ZaSdVSBdTTwjL", "choiceText": "France" }, { "choiceId": "nV0HdHhaq6-OcDWWyzdlY", "choiceText": "Germany" }, { "choiceId": "H7Vcp-1vcH2uVUECmD_bn", "choiceText": "Greece" }, { "choiceId": "YJKeTDohZP6m1CAxwEgMY", "choiceText": "Italy" }, { "choiceId": "QIo1lO36U03gsTzzyG9NE", "choiceText": "Netherlands" }, { "choiceId": "uO-s_-b1-EcECG6Wi5ddg", "choiceText": "Other", "choicePayload": "isLastValue" // predefined choice payload }, { "choiceId": "x26Swi_WzeZQzovU3NzKs", "choiceText": "Poland" }, { "choiceId": "8ylDu33QqCpT-of5_ZvnL", "choiceText": "Portugal" }, { "choiceId": "oxw20hd6aG3oVwP7j0zSx", "choiceText": "Spain" }, { "choiceId": "dP4apL17V44PxsyhxN5Pv", "choiceText": "Sweden", } ], "choicesMetadata": { "source": "slot", "slotId": "CountryList", "slotType": "CountryList", "transient": false, "resolutionType": "static", "elicitationStyle": "default", "associatedSlotIds": [], "intentId": "SampleIntent" } } ] } ``` Within your client application, you could sort the `choices` array and always have the value with `choicePayload=isLastValue` appended at the end of the list, no matter what the `choiceText` value is. *** ## Send context [Context variables](/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables.md) that have been set throughout the course of a conversation can be appended to the API response any time the [Send context](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#add-functionality) functionality is enabled on a conversation flow node. The context will come back in the response under the `context` property like so: 
{
  // API reponse properties
  // ...
  "context": {
    // properties sent by default
    "botId": "ce2acb13-c5fc-4df1-abd5-7918491b8ac2",
    "channelId": "15f672f2-da64-47de-ae68-c4d1a5bb1d4e",
    "languageCode": "en-US",
    // context attributes that hold a value
    "SampleContextAttribute": "some-value"
  }
}
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.nlx.ai/platform/nlx-platform-guide/ai-applications/deployment/managing-channels/creating-an-api-channel/rest-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.