# REST

The NLX Conversation REST API is the primary interface for building custom conversational experiences. It follows a standard RESTful pattern, allowing you to send user inputs (text or structured data) and receive a complete JSON response containing the AI app's reply.

### When to use this API

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-gears">:gears:</i></td><td>Building custom web chat widgets or mobile app integrations</td></tr><tr><td><i class="fa-server">:server:</i></td><td>Server-to-server communication where streaming is not required</td></tr><tr><td><i class="fa-key-skeleton">:key-skeleton:</i></td><td>Integration with legacy systems that do not support Server-Sent Events (SSE)</td></tr></tbody></table>

### Authentication

This API uses a custom header for authentication. You must include your NLX API key in every request. &#x20;

| Header         | Value              |
| -------------- | ------------------ |
| `nlx-api-key`  | `YOUR_API_KEY`     |
| `Content-Type` | `application/json` |

The Application URL and API Key are located in the *API Delivery channel* setup.

<figure><img src="https://3978076094-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2VnkvXtkrR2qhkVBmB1l%2Fuploads%2Fgl5zjWcycOSXc75z8lVa%2Fimage.png?alt=media&#x26;token=e58b07fd-ef5e-4a50-ae68-0f0b9e5cc78f" alt=""><figcaption></figcaption></figure>

Click *Setup instructions* to view Application URL and API Key.

<figure><img src="https://3978076094-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2VnkvXtkrR2qhkVBmB1l%2Fuploads%2FUijCBq1DMCfm7v9XGkqH%2Fimage.png?alt=media&#x26;token=55221381-ac3e-4832-ba1d-ba31bc34a7b1" alt=""><figcaption></figcaption></figure>

### Base URL

All requests are made to the NLX App runtime. Note that the URL must include the language code (e.g., `-en-US`, `-es-MX`) appended to the channel key.

`https://apps.nlx.ai/c/{deploymentKey}/{channelKey}-{languageCode}`

* *deploymentKey*: The unique identifier for your specific AI app deployment
* *channelKey*: The identifier for the channel
* *languageCode*: The ISO language-country code (e.g., `en-US`)

The deploymentKey and channelKey values can be found below the Application URL and API Key in the Setup instructions dialog pictured in the [Authentication](#authentication) instructions above.  &#x20;

### Request structure

The API supports two main types of input:

1. *Unstructured*: Free-form text (natural language).
2. *Structured*: Explicit intent triggering or button clicks.

**Example: Sending a text message**

```bash
curl -X POST "https://apps.nlx.ai/c/YOUR_DEPLOYMENT_KEY/YOUR_CHANNEL_KEY-en-US" \
  -H "nlx-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "unstructured": {
        "text": "Check my order status"
      }
    },
    "userId": "800f8dd7-4970-4d7e-aef4-4998e9843b0c",
    "conversationId": "9e8ad2b0-8cee-470c-89cf-93b8efde9ef0"
  }'
```

### Response format

The API returns a standard JSON object containing the AI app's messages, metadata, and updated session context.

```json
{
  "messages": [
    {
      "text": "Your order #5544 is out for delivery.",
      "type": "text",
      "messageId": "5aa637fc-e425-4f16-96fc-8ce17fa98520"
    }
  ],
  "conversationId": "9e8ad2b0-8cee-470c-89cf-93b8efde9ef0",
  "metadata": {
    "intentId": "OrderCheck",
    "isGenerative": true
  }
}
```