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

• Building custom web chat widgets or mobile app integrations.

• Server-to-server communication where streaming is not required.

• Integration with legacy systems that do not support Server-Sent Events (SSE).

Authentication

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

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

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).

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

curl -X POST "https://apps.nlx.ai/c/xxxx/xxxx-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.

{
  "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
  }
}