REST

Updated in 2026.14

The REST Endpoint enables you to connect your AI Agent to a REST client. The REST client can be any application, tool, or service capable of making HTTP requests to RESTful APIs. This includes custom-built applications, third-party tools like Postman or Insomnia, or backend services that interact with external APIs.

Prerequisites

Set up a REST client, for example, Postman, Insomnia, a custom application, or any tool capable of sending HTTP requests.

Generic Endpoint Settings

Learn about the generic Endpoint settings on the following pages:

Specific Endpoint Settings

API Key Authentication

Use this section to configure how incoming requests to this Endpoint are authenticated.

Parameter	Type	Description
Authentication Method	List	Sets an authentication step for requests sent to this Endpoint. Select one of the options: None — no authentication step. This option is selected by default. API Key — sets API key-based authentication.
Generate API Key	Button	This button appears in the Endpoint API Keys section when you select API Key in Authentication Method. Opens a dialog to generate an Endpoint-specific API key. You can generate multiple Endpoint-specific API keys.

How to Set Up

Setup on the Cognigy.AI Side

1. Create a REST Endpoint

In the left-side menu of your Project, go to Deploy > Endpoints and click + New Endpoint.
In the New Endpoint section, do the following:
1. Select the REST Endpoint type.
2. Specify a unique name.
3. Select a Flow from the list.
(Optional) To set up Endpoint-specific API authentication, select API Key from the Authentication Method list in the API Key Authentication section. The Endpoint API Keys section appears. Follow these steps:
1. Click + Generate API Key.
2. In the dialog box, enter a unique name for your API key in the Key name field and click Generate API Key.
3. Click the Key field to copy the generated API key for later use in the x-rest-endpoint-key header of requests to the Endpoint URL. Save the API key because you can’t retrieve it after closing the dialog. Alternatively, you can create and manage API keys for this Endpoint using the /v2.0/endpoints/{endpointId}/apikeys routes via Cognigy API.
Save changes and go to the Configuration Information section. Copy the URL from the Endpoint URL field.

Setup on the Third-Party Provider Side

1. Send a Request

Send a POST request to the Endpoint URL.

No Authentication

cURL
Postman
Next.js
Python

Replace https://<your-endpoint-url> with the Endpoint URL from the Endpoint settings.

curl -X POST https://<your-endpoint-url> \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
      "exampleKey": "exampleValue"
    }
  }'

Open the Postman collection, select Add a request, then set the request type to POST.
Enter the Endpoint URL as the request URL.
Go to the Headers tab and add Content-Type: application/json.
Go to the Body tab, select raw, then select JSON as the format.
Paste the request body:

{
  "userId": "user123",
  "sessionId": "session123",
  "text": "Hello, I need help with my order",
  "data": {
    "exampleKey": "exampleValue"
  }
}

Replace https://<your-endpoint-url> with the Endpoint URL from the Endpoint settings.

const axios = require('axios');

async function sendRequest() {
  try {
    const response = await axios.post('https://<your-endpoint-url>', {
      userId: "user123",
      sessionId: "session123",
      text: "Hello, I need help with my order",
      data: {
        exampleKey: "exampleValue"
      }
    }, {
      headers: {
        "Content-Type": "application/json"
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

sendRequest();

Replace https://<your-endpoint-url> with the Endpoint URL from the Endpoint settings.

import requests

url = "https://<your-endpoint-url>"
payload = {
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
        "exampleKey": "exampleValue"
    }
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Parameter	Type	Description	Required
userId	String	The ID of the end user.	Yes
sessionId	String	The ID used to track the current session and maintain its state. Generate a new unique ID for each new session. For testing, you can use any string and change it whenever you want to start a new session.	Yes
text	String	The text that the assigned Flow processes.	No, if `data` is specified¹
data	Object	The data that the assigned Flow processes.	No, if `text` is specified¹

With API Key Authentication

cURL
Postman
Next.js
Python

Replace https://<your-endpoint-url> with the Endpoint URL and <your-rest-endpoint-api-key> with an active API key from your Endpoint settings.

curl -X POST https://<your-endpoint-url> \
  -H "Content-Type: application/json" \
  -H "x-rest-endpoint-key: <your-rest-endpoint-api-key>" \
  -d '{
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
      "exampleKey": "exampleValue"
    }
  }'

Open the Postman collection, select Add a request, then set the request type to POST.
Enter the Endpoint URL as the request URL.
Go to the Headers tab and configure:
- Content-Type — select application/json
- x-rest-endpoint-key — the API key you created using the Cognigy API.
Go to the Body tab, select raw, then select JSON as the format.
Paste the request body:

{
  "userId": "user123",
  "sessionId": "session123",
  "text": "Hello, I need help with my order",
  "data": {
    "exampleKey": "exampleValue"
  }
}

Replace https://<your-endpoint-url> with the Endpoint URL and <your-rest-endpoint-api-key> with an active API key from your Endpoint settings.

const axios = require('axios');

async function sendRequest() {
  try {
    const response = await axios.post('https://<your-endpoint-url>', {
      userId: "user123",
      sessionId: "session123",
      text: "Hello, I need help with my order",
      data: {
        exampleKey: "exampleValue"
      }
    }, {
      headers: {
        "Content-Type": "application/json",
        "x-rest-endpoint-key": "<your-rest-endpoint-api-key>"
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

sendRequest();

Replace https://<your-endpoint-url> with the Endpoint URL and <your-rest-endpoint-api-key> with an active API key from your Endpoint settings.

import requests

url = "https://<your-endpoint-url>"
payload = {
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
        "exampleKey": "exampleValue"
    }
}
headers = {
    "Content-Type": "application/json",
    "x-rest-endpoint-key": "<your-rest-endpoint-api-key>"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

2. Get a Response

The response contains the output text, output data, and the outputStack, which is an array of all Flow outputs. The REST Endpoint can concatenate AI Agent outputs into a single text or data output, for example, when you place Say Nodes sequentially in the Flow. You can use the outputStack for debugging purposes.

{
  "text": "Hello, this is the Cognigy.AI Agent. How can I help you?",
  "data": {},
  "outputStack": [
    {
      "text": "Hello, this is the Cognigy.AI Agent.",
      "data": {},
      "traceId": "endpoint-httpIncomingMessage-068f1748-dadb-4792-bd2e-971335e9c88c",
      "disableSensitiveLogging": false,
      "source": "bot"
    },
    {
      "text": "How can I help you?",
      "data": {},
      "traceId": "endpoint-httpIncomingMessage-068f1748-dadb-4792-bd2e-971335e9c88c",
      "disableSensitiveLogging": false,
      "source": "bot"
    }
  ],
  "userId": "user123",
  "sessionId": "session123"
}

Parameter	Type	Description
userId	String	The ID of the end user.
sessionId	String	The ID used to track the current session and to maintain its state. Generate a new unique ID for each new session. For testing, you can use any string and change it whenever you want to start a new session.
text	String	The text the assigned Flow processes.
data	Object	The data the assigned Flow processes.
outputStack	Array	An array of outputs generated by the Flow, each with detailed metadata.
outputStack.text	String	The text of the output.
outputStack.data	Object	The data of the output.
outputStack.traceId	String	The ID used for tracing and debugging purposes.
outputStack.disableSensitiveLogging	Boolean	The flag indicating if logging is disabled. If the value is `true`, this interaction won’t be logged for privacy or compliance reasons.
outputStack.source	String	The message source. Always `"bot"` for AI Agent replies.

¹: You must provide at least one of text or data. You can send either, or both. If both are missing or invalid, the REST Endpoint throws an error.

Overview

AI Agents

Human Escalation

Platform Features

For Developers

Administration and Installation

Prerequisites

Generic Endpoint Settings

Specific Endpoint Settings

How to Set Up

Setup on the Cognigy.AI Side

Setup on the Third-Party Provider Side

​Prerequisites

​Generic Endpoint Settings

​Specific Endpoint Settings

​How to Set Up

​Setup on the Cognigy.AI Side

​Setup on the Third-Party Provider Side

Prerequisites

Generic Endpoint Settings

Specific Endpoint Settings

How to Set Up

Setup on the Cognigy.AI Side

Setup on the Third-Party Provider Side