Skip to main content
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:

How to Set Up

Setup on the Cognigy.AI Side

  1. In the left-side menu of your Project, click Deploy > Endpoints.
  2. On the Endpoints page, click + New Endpoint.
  3. 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. Save changes.
  4. Go to the Configuration Information section and copy the URL from the Endpoint URL field. Save changes.

Setup on the Third-Party Provider Side

Send a POST request to the Endpoint URL.
  • cURL
  • Postman
  • Next.js
  • Python
Replace https://<your-endpoint-url> with the Endpoint URL from your Endpoint’s 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"
    }
  }'
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 Say Nodes are placed 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"
}
ParameterTypeDescription
userIdStringThe ID of the end user.
sessionIdStringThe 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.
textStringThe text the assigned Flow should process.
dataObjectThe data the assigned Flow should process.
outputStackArrayAn array of outputs generated by the Flow, each with detailed metadata.
outputStack.textStringThe text of the output.
outputStack.dataObjectThe data of the output.
outputStack.traceIdStringThe ID used for tracing and debugging purposes.
outputStack.disableSensitiveLoggingBooleanThe flag indicating if logging is disabled. If the value is true, this interaction won’t be logged for privacy or compliance reasons.
outputStack.sourceStringThe message source. Always "bot" for AI Agent replies.

1: 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.
I