ConceptsConceptsGuidesGuidesExamplesExamplesReferencesReferencesAPIsAPIs
GitHub (opens in a new tab)
  • APIs
      • Almanac APIs
      • Hosting APIs
      • Mailroom APIs
      • AI Engine Chat API
      • Functions API
      • ASI Alliance Wallet APIs
  • APIs
      • Almanac APIs
      • Hosting APIs
      • Mailroom APIs
      • AI Engine Chat API
        • Overview
        • Starting your session
        • Get all sessions for a user
        • Sending a new message
        • Delete a session for a user
        • Fetch new messages sent by agent Deprecated
        • Fetch recent messages given a timestamp Deprecated
        • Fetch all messages sent by agent in a session
        • Retrieve new messages sent by agent (with possible duplicate or missed messages)
        • Provide feedback for a session
        • Retrieve remaining tokens
      • Functions API
      • ASI Alliance Wallet APIs
APIs
AI Engine
AI Engine Chat API

AI Engine Chat API

Most of the endpoints depends on various instances and are considered parameters for the actual endpoint, but these are not meant to be passed directly by the user.

Instead, these instance-dependent elements are integrated and managed directly by the backend system. We refer to them as *name_parameter, where the asterisk (*) is used to denote a specific instance-dependent parameter that the route relies on.

Mind that: to access these APIs, user must be authenticated and have the correct permissions.

Overview

The AI Engine Chat API allows you to interact with the DeltaV backend, allowing you to interact with your agents and more.

Endpoints
GET /v1beta1/engine/chat/sessions
POST /v1beta1/engine/chat/sessions
 
DELETE /v1beta1/engine/chat/sessions/:session_id
 
POST /v1beta1/engine/chat/sessions/:session_id/submit
 
GET /v1beta1/engine/chat/sessions/:session_id/responses (Deprecated)
 
GET /v1beta1/engine/chat/sessions/:session_id/messages (Deprecated)
 
GET /v1beta1/engine/chat/sessions/:session_id/messages/all
 
GET /v1beta1/engine/chat/sessions/:session_id/new-messages
 
POST /v1beta1/engine/chat/sessions/:session_id/feedback
 
GET /v1beta1/engine/chat/remaining_tokens

Starting your session

Endpoint:POST/v1beta1/engine/chat/sessions

Request

Start a new session for a user authenticated through JWT.
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of payload being sent.
  • Name
    email
    Type
    email
    Description
    The email of the user
  • Name
    requestModel
    Type
    string
    Description
    The request model wherein the user wants to interact.
  • Name
    functionGroup
    Type
    string
    Description
    The function group that the user wants to interact with. Previously known as service_group. Defaults to Public group!
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions -d "{\"email\":\"your_email_address\",\"requestedModel\":\"talkative-01\",\"functionGroup\":\"12c8601c-cccd-42de-a5f1-7eab76ae3121\"}"

Responses

Returns the newly created Session object
HTTP 200
HTTP 200
[
  {
    "session_id": "c320b5c4-518c-428b-889d-3cb8403901c0",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "model": "talkative-01",
    "remaining_tokens": 10000000,
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121"
  }
]

Get all sessions for a user

Endpoint:GET/v1beta1/engine/chat/sessions

Request

Retrieves all sessions for a user authenticated through JWT.
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions

Responses

Returns a list of Session objects associated with the user
HTTP 200
HTTP 200
[
  {
    "session_id": "7be16891-39a6-44a6-88cb-377250dd8eb7",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121",
    "model": "talkative-01",
    "remaining_tokens": 9999099
  },
  {
    "session_id": "aed47bb4-9d73-4135-89f7-925036aa83bd",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121",
    "model": "talkative-01",
    "remaining_tokens": 9999099
  }
]

Sending a new message

There are 4 types of messages that can be sent to the backend:

  • start: This is the first message that should be sent to the AI Engine for full session (search + execution). It contains the objective and context of the conversation. The objective and context are used to determine which agent to use for the conversation.
  • execute_functions: This is the first message that should be sent to the AI Engine for execution only (no search). It contains the list of function-ids you want to execute and a function group (for secondary function picks).
  • user_message: This is a message sent by the user.
  • user_json: This is a JSON message sent by the user.
  • stop: This is the last message that should be sent to the backend. It indicates that the conversation has ended.

IMPORTANT: you need to either send start or execute_functions. These two can't be combined.

Sending start message

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending start message
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Description
    The type of message being sent. For starting the session set it to 'start'.
  • Name
    objective
    Type
    string
    Description
    The objective of the conversation. This is used to determine which agent to use for the conversation.
  • Name
    context
    Type
    string
    Description
    The context of the conversation. This is used to give information about the user to the agent.
  • Name
    recommend_only
    Type
    boolean
    Description
    Optional flag, if is set to true, AI Engine will only do search, it will match your objective to functions/agents and then stops. False by default. Only supported by Next Generation personality.
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit -d "{\"payload\":{\"type\":\"start\",\"objective\":\"I'd like to go to London\",\"context\":\"User full Name: Test User\\nUser email: user@user.com\\nUser location: latitude=51.5072, longitude=0.1276\\n\"}}"

Sending execute functions message

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending execute functions message. Currently only supported by Next Generation personality. Don't use this if you already sent 'start' message.
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Description
    The type of message being sent. Set it to 'execute_functions'.
  • Name
    functions
    Type
    string[]
    Description
    List of function ids you want the system to execute.
  • Name
    objective
    Type
    string
    Description
    The objective of the conversation. This will guide context building.
  • Name
    context
    Type
    string
    Description
    The context of the conversation. This is used to give information about the user to the agent.
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit -d "{\"payload\":{\"type\":\"execute_functions\",\"functions\":[\"b320b5c4-518c-428b-889d-3cb8403901c0\"],\"objective\":\"\",\"context\":\"\"}}"

Sending user message

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Send an answer to a question asked by the agent
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Description
    The type of message being sent.
  • Name
    user_message
    Type
    string
    Description
    The user response to a question asked by the agent or to confirm the context
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit -d "{\"payload\":{\"type\":\"user_message\",\"user_message\":\"The booking is for 2 people\"}}"

Sending user json message

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending an option in a task list requested by an agent
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of message being sent. The payload is different for each type of message.
  • Name
    type
    Type
    string
    Description
    The type of message being sent.
  • Name
    user_json
    Type
    JSON
    Description
    The objective of the conversation. This is used to determine which agent to use for the conversation.
  • Name
    user_json-type
    Type
    string
    Description
    The context of the conversation. type: `task_list`, `options`. `task_list` is used to select a task pertaining to a specific agent. `options` is used to select a subtask pertaining to a specific agent or select an option from a list of suggestions given by the agent.
  • Name
    user_json-selection
    Type
    array
    Description
    The selection of the user from the list of options. The selection is an array of integers or UUID4
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit -d "{\"payload\":{\"type\":\"user_json\",\"user_json\":{\"type\":\"task_list | options\",\"selection\":[\"0 | 9f157712-472d-4f0d-814d-d5aae9fd7b28\"]}}}"

Sending stop message

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending a stop message to an agent
  • Name
    payload
    Type
    JSON
    Description
    Contains the data for the type of message being sent. The payload is different for each type of message.
  • Name
    type
    Type
    string
    Description
    The type of message being sent.
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit -d "{\"payload\":{\"type\":\"stop\"}}"

Delete a session for a user

Endpoint:DELETE/v1beta1/engine/chat/sessions/{session_id}

Request

Delete a specific session given a session id for a user authenticated through JWT.
Curl
Curl

curl -X DELETE
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}

Fetch new messages sent by agent Deprecated

Endpoint:GET/v1beta1/engine/chat/sessions/{session_id}/responses

Request

Fetches new messages for a specific session identified by the session_id
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/responses

Responses

Return an agent_response object containing the agent response in JSON format, which can be parsed to retrieve the agent message. It can be an AgentMessage or an AgentJsonMessage. They are almost similar to user_message and user_json_message, but they are sent by the agent.
HTTP 200
HTTP 200
[
  {
    "agent_response": "{\"message_id\": \"c5c27376-0edc-41db-ae7b-980b4a6bfe8b\", \"timestamp\": \"2023-08-31T13:10:48.941865\", \"score\": 0.0, \"type\": \"agent_json\", \"agent_json\": {\"type\": \"task_list\", \"text\": \"Found tasks for your objective. Please select.\", \"options\": [{\"key\": 0, \"value\": \"TopActivities/TopActivities\"}, {\"key\": 1, \"value\": \"Flights/Flights\"}, {\"key\": 2, \"value\": \"Hotels/Hotels\"}], \"context_json\": null}}"
  }
]

Fetch recent messages given a timestamp Deprecated

Endpoint:GET/v1beta1/engine/chat/sessions/{session_id}/messages?from_timestamp=2023-08-31T13:26:30.941865

Request

Fetches agent messages filtered by timestamps for a specific session identified by the session_id
  • Name
    from_timestamp
    Type
    datetime
    Description
    The timestamp from which to fetch the agent messages. The timestamp is in ISO 8601 format.
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages?from_timestamp=2023-08-31T13:26:30.941865

Responses

Return the most recent list of agent messages given a timestamp. The timestamp is in ISO 8601 format.
HTTP 200
HTTP 200
[
  {
    "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
    "messages": [
      {
        "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
        "timestamp": "2023-08-31T13:26:42.093485",
        "score": 0,
        "type": "agent_info",
        "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
      },
      {
        "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
        "timestamp": "2023-08-31T13:26:51.744958",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "context_json",
          "text": "Can you confirm the following context?",
          "options": null,
          "context_json": {
            "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
            "args": {
              "city": "London",
              "date": "[date]",
              "preferred_activities": ""
            }
          }
        }
      }
    ]
  }
]

Fetch all messages sent by agent in a session

Endpoint:GET/v1beta1/engine/chat/sessions/{session_id}/messages/all

Request

Fetches agent messages filtered by timestamps for a specific session identified by the session_id
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages/all

Responses

Return all the messages sent by the agent for a specific session.
HTTP 200
HTTP 200
[
  {
    "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
    "messages": [
      {
        "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
        "timestamp": "2023-08-31T13:26:23.238697",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "task_list",
          "text": "Found tasks for your objective. Please select.",
          "options": [
            {
              "key": 0,
              "value": "TopActivities/TopActivities"
            },
            {
              "key": 1,
              "value": "Flights/Flights"
            },
            {
              "key": 2,
              "value": "Hotels/Hotels"
            }
          ],
          "context_json": null
        }
      },
      {
        "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
        "timestamp": "2023-08-31T13:26:42.093485",
        "score": 0,
        "type": "agent_info",
        "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
      },
      {
        "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
        "timestamp": "2023-08-31T13:26:51.744958",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "context_json",
          "text": "Can you confirm the following context?",
          "options": null,
          "context_json": {
            "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
            "args": {
              "city": "London",
              "date": "[date]",
              "preferred_activities": ""
            }
          }
        }
      }
    ]
  }
]

Retrieve new messages sent by agent (with possible duplicate or missed messages)

Endpoint:GET/v1beta1/engine/chat/sessions/{session_id}/new-messages

Request

Retrieves a batch of new messages since the last retrieved message for a specific chat session.
  • Name
    session_id
    Type
    UUID4
    Description
    The unique identifier of the chat session. It must be a valid UUID4 string.
  • Name
    last_message_id
    Type
    string
    Required
    optional
    Description
    The message ID of the last message that was retrieved. This is optional and, if provided, the service will return messages that were sent after this message.
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/new-messages

Responses

Returns a list of new messages for the session, if specified then returns the messages since the last checked message. If there are no new messages, an empty list is returned. If the session is not found, a 404 error with a descriptive message is returned.
HTTP 200
HTTP 200
[
  {
    "status": 200,
    "agent_response": [
      {
        "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
        "messages": [
          {
            "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
            "timestamp": "2023-08-31T13:26:23.238697",
            "score": 0,
            "type": "agent_json",
            "agent_json": {
              "type": "task_list",
              "text": "Found tasks for your objective. Please select.",
              "options": [
                {
                  "key": 0,
                  "value": "TopActivities/TopActivities"
                },
                {
                  "key": 1,
                  "value": "Flights/Flights"
                },
                {
                  "key": 2,
                  "value": "Hotels/Hotels"
                }
              ],
              "context_json": null
            }
          },
          {
            "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
            "timestamp": "2023-08-31T13:26:42.093485",
            "score": 0,
            "type": "agent_info",
            "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
          },
          {
            "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
            "timestamp": "2023-08-31T13:26:51.744958",
            "score": 0,
            "type": "agent_json",
            "agent_json": {
              "type": "context_json",
              "text": "Can you confirm the following context?",
              "options": null,
              "context_json": {
                "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
                "args": {
                  "city": "London",
                  "date": "[date]",
                  "preferred_activities": ""
                }
              }
            }
          }
        ]
      }
    ]
  }
]

Provide feedback for a session

Endpoint:POST/v1beta1/engine/chat/sessions/{session_id}/feedback

Request

Give feedback for a specific session identified by the session_id
  • Name
    models
    Type
    array
    Description
    Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
  • Name
    feedback
    Type
    string
    Description
    The feedback of the user. It can be positive or negative.
  • Name
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Curl
Curl

curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/feedback -d "{\"feedback\":\"positive\"}"

Responses

On a successful request returns the remaining tokens for the models that have been queried
HTTP 200
HTTP 200
{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Retrieve remaining tokens

Endpoint:GET/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&email=user@user.com

Request

Request for retrieving the amount of tokens left for each model
  • Name
    models
    Type
    array
    Description
    Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
  • Name
    email
    Type
    string
    Description
    The email of the user
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&email=user@user.com

Responses

On a successful request returns the remaining tokens for the models that have been queried
HTTP 200
HTTP 200
{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Was this page helpful?

You can also leave detailed feedbackon Github

Mailroom APIsFunctions API

On This Page

  • Overview
  • Starting your session
  • Get all sessions for a user
  • Sending a new message
  • Sending start message
  • Sending execute functions message
  • Sending user message
  • Sending user json message
  • Sending stop message
  • Delete a session for a user
  • Fetch new messages sent by agent Deprecated
  • Fetch recent messages given a timestamp Deprecated
  • Fetch all messages sent by agent in a session
  • Retrieve new messages sent by agent (with possible duplicate or missed messages)
  • Provide feedback for a session
  • Retrieve remaining tokens
    • Edit this page on github (opens in a new tab)

Main website

Integrations

Events

We’re hiring!

Twitter (opens in a new tab)Telegram (opens in a new tab)Discord (opens in a new tab)GitHub (opens in a new tab)YouTube (opens in a new tab)LinkedIn (opens in a new tab)Reddit (opens in a new tab)
Sign up for developer updates