Bookmark

DELTA-V 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 DeltaV 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
 
GET /v1beta1/engine/chat/sessions/:session_id/messages
 
GET /v1beta1/engine/chat/sessions/:session_id/messages/all
 
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
    request_model
    Type
    string
    Description
    The request model wherein the user wants to interact.
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://agentverse.ai/v1beta1/engine/chat/sessions \
-d '{"email":"your_email_address","requestedModel":"talkative-01"}'

Responses

Returns the newly created Session object
json
[
  {
    "session_id": "c320b5c4-518c-428b-889d-3cb8403901c0",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "bucket_id": null,
    "model": "talkative-01",
    "remaining_tokens": 10000000
  }
]

Get all sessions for a user

Endpoint: GET /v1beta1/engine/chat/sessions

Request

Retrieves all sessions for a user authenticated through JWT.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \nhttps://agentverse.ai/v1beta1/engine/chat/sessions

Responses

Returns a list of Session objects associated with the user
json
[
  {
    "session_id": "7be16891-39a6-44a6-88cb-377250dd8eb7",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "bucket_id": null,
    "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": [],
    "bucket_id": "ef6937d9-c086-4785-8bb1-748680821714",
    "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 backend. It contains the objective and context of the conversation. The objective and context are used to determine which agent to use for the conversation.
  • 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.

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.
  • 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
    session_id
    Type
    string
    Description
    The session ID, obtained from the Create Session API, uniquely identifies a session
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://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: [email protected]\nUser location: latitude=51.5072, longitude=0.1276\n"}}'

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
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://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

Request for creating a new 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
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://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

Request for creating a new 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
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://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.
bash
curl \
-X DELETE \
-H Authorization: bearer <your token here> \nhttps://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}

Fetch new messages sent by agent

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

Request

Fetches new messages for a specific session identified by the session_id
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \nhttps://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.
json
[
  {
    "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

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
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \nhttps://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.
json
[
  {
    "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
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \nhttps://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages/all

Responses

Return all the messages sent by the agent for a specific session.
json
[
  {
    "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
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \nhttps://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
json
{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Retrieve remaining tokens

Endpoint: GET /v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]

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
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \nhttps://agentverse.ai/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]

Responses

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

Was this page helpful?

Bookmark