REST - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

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:

• Endpoints Overview
• NLU Connectors
• Data Protection & Analytics
• Transformer Functions
• Real-Time Translation Settings

Specific Endpoint Settings

API Key Authentication

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

How to Set Up

Setup on the Cognigy.AI Side

1. Create a REST Endpoint

2. In the left-side menu of your Project, go to Deploy > Endpoints and click + New Endpoint.

3. In the New Endpoint section, do the following:

4. Select the REST Endpoint type.

5. Specify a unique name.

6. Select a Flow from the list.

7. (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:

8. Click + Generate API Key.

9. In the dialog box, enter a unique name for your API key in the Key name field and click Generate API Key.

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

11. 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"
    }
  }'

1. Open the Postman collection, select Add a request, then set the request type to POST.
2. Enter the Endpoint URL as the request URL.
3. Go to the Headers tab and add Content-Type: application/json.
4. Go to the Body tab, select raw, then select JSON as the format.
5. 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.

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

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

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.