ConceptsConceptsGuidesGuidesExamplesExamplesReferencesReferencesAPIsAPIs
GitHub (opens in a new tab)
      • Almanac API
      • Hosting API
      • Mailroom API
      • Search API
      • AI Engine Chat API
      • Functions API
      • ASI Alliance Wallet APIs
      • Almanac API
      • Hosting API
      • Mailroom API
      • Search API
      • 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 an 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
    Required
    required
    Description
    Contains the data for the type of payload being sent.
  • Name
    email
    Type
    email
    Required
    required
    Description
    The email of the user
  • Name
    requestModel
    Type
    string
    Required
    required
    Description
    The request model wherein the user wants to interact.
  • Name
    functionGroup
    Type
    string
    Required
    required
    Description
    The function group that the user wants to interact with. Previously known as service_group. Defaults to Public group!

Responses

Returns the newly created Session object.
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\"}"
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.

Responses

Returns a list of Session objects associated with the user.
Curl
Curl

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1beta1/engine/chat/sessions
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
    Required
    required
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Required
    required
    Description
    The type of message being sent. For starting the session set it to 'start'.
  • Name
    objective
    Type
    string
    Required
    required
    Description
    The objective of the conversation. This is used to determine which agent to use for the conversation.
  • Name
    context
    Type
    string
    Required
    required
    Description
    The context of the conversation. This is used to give information about the user to the agent.
  • Name
    recommend_only
    Type
    boolean
    Required
    required
    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
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If the request is successful, there will be no response.
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\"}}"
HTTP 200
HTTP 200


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
    Required
    required
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Required
    required
    Description
    The type of message being sent. Set it to 'execute_functions'.
  • Name
    functions
    Type
    string[]
    Required
    required
    Description
    List of function ids you want the system to execute.
  • Name
    objective
    Type
    string
    Required
    required
    Description
    The objective of the conversation. This will guide context building.
  • Name
    context
    Type
    string
    Required
    required
    Description
    The context of the conversation. This is used to give information about the user to the agent.
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
If request is successful, there will be no response.
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\":\"\"}}"
HTTP 200
HTTP 200


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
    Required
    required
    Description
    Contains the data for the type of message being sent.
  • Name
    type
    Type
    string
    Required
    required
    Description
    The type of message being sent.
  • Name
    user_message
    Type
    string
    Required
    required
    Description
    The user response to a question asked by the agent or to confirm the context
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
If request is successful, there will be no response.
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\"}}"
HTTP 200
HTTP 200


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
    Required
    required
    Description
    Contains the data for the type of message being sent. The payload is different for each type of message.
  • Name
    type
    Type
    string
    Required
    required
    Description
    The type of message being sent.
  • Name
    user_json
    Type
    JSON
    Required
    required
    Description
    The objective of the conversation. This is used to determine which agent to use for the conversation.
  • Name
    user_json-type
    Type
    string
    Required
    required
    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
    Required
    required
    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
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
If request is successful, there will be no response.
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\"]}}}"
HTTP 200
HTTP 200


Sending stop message


Endpoint:POST
/v1beta1/engine/chat/sessions/{session_id}/submit
Request
Sending a stop message to an agent
  • Name
    payload
    Type
    JSON
    Required
    required
    Description
    Contains the data for the type of message being sent. The payload is different for each type of message.
  • Name
    type
    Type
    string
    Required
    required
    Description
    The type of message being sent.
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
If request is successful, there will be no response.
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\"}}"
HTTP 200
HTTP 200


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.
Responses
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}
HTTP 200
HTTP 200


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
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.
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
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
    Required
    optional
    Description
    The timestamp from which to fetch the agent messages. The timestamp is in ISO 8601 format.
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
Return the most recent list of agent messages given a timestamp. The timestamp is in ISO 8601 format.
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
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 an 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
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The unique identifier of the chat session for which all messages are being retrieved.
Responses
Returns all messages sent by the Agent for a specific 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/all
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.."
      }
    ]
  }
]


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
    Required
    required
    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.
Responses
Returns a list of new messages for the session. If specified, it 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.
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
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.."
          }
        ]
      }
    ]
  }
]


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
    Required
    required
    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
    Required
    required
    Description
    The feedback of the user. It can be positive or negative.
  • Name
    session_id
    Type
    string
    Required
    required
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
Responses
Retrieves the remaining tokens for the models that have been queried.
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\"}"
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
    Required
    required
    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
    Required
    required
    Description
    The email of the user
Responses
Retrieves the remaining tokens for the models that have been queried.
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
HTTP 200
HTTP 200
{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}
Was this page helpful?
You can also leave detailed feedbackon Github
Search APIFunctions 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 an 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