Conversations

Conversations represent interactions with an application and its sources. Each conversation has a set of messages that are updated automatically for each new request/response.

You can have many conversations, each with a different application and set of messages. Message history is stored by Chariot so you don't have to maintain it in your app.

To have a conversation with data such as a file (PDF, Word, PowerPoint, etc.), text, or website, add the respective data as a source for the application. Relevant sources are automatically retrieved and included as context for the language model for each request.

The conversation object

Name
id
Type
string
Description
Unique identifier for the conversation.
Name
application_id
Type
string
Description
Unique identifier for the application this conversation is associated with.
Name
messages
Type
array
Description
List of messages in the conversation.
Name
title
Type
string
Description
Title of the conversation. This is auto generated by the language model at creation time based on the context of the first message and can be updated.
Name
prompt_tokens
Type
integer
Description
Total number of prompt tokens used by the convesation.
Name
completion_tokens
Type
integer
Description
Total number of completion tokens used by the convesation.
Name
total_tokens
Type
integer
Description
Total tokens used by the convesation.
Name
created_at
Type
string
Description
Timestamp of when the conversation was created.
Name
updated_at
Type
string
Description
Timestamp of when the conversation was last updated.

GET/conversations

List conversations

Returns a list of all conversations for your account. This endpoint does not include messages for the conversations. To get messages, retrieve the conversation by its id.

Request

GET

/conversations

curl https://api.chariotai.com/conversations \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Response

[
  {
        "id": "string",
        "application_id": "app_123",
        "messages": [],
        "title": "string",
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0,
        "created_at": "2023-05-21T00:00:00.000Z",
        "updated_at": "2023-05-21T00:00:00.000Z"
  }
]

POST/conversations

Create or continue conversation

Creates or continues an existing conversation. If conversation_id is provided, the conversation will be continued. Otherwise, a new conversation will be created.

If a new conversation is created, the conversation_id will be returned in the response. You can use this id to continue the conversation.

The messages array is automatically updated for each request/response, so you don't need to maintain any message history locally.

To stream the output, set stream:true in the request body. The reponse will use server-sent events to stream new message chunks as they are generated.

For more information on how to stream messages in your application, see our guide on streaming conversations.

Required attributes

Name
message
Type
string
Description
Message to start or continue the conversation with.

Optional attributes

Name
application_id
Type
string
Description
Unique identifier for the application this conversation is associated with. This field is required when starting a new conversation.
Name
conversation_id
Type
string
Description
Unique identifier for the conversation. If not provided, a new conversation will be created.
Name
stream
Type
boolean
Description
If true, the response will be streamed using server-sent events

Request

POST

/conversations

curl https://api.chariotai.com/conversations \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Response

{
  "conversation_id": "conv_123",
  "title": "Hello world",
  "message": "Hello! I'm an AI language model, so I don't have feelings, but I'm here and ready to assist you.",
  "sources": [
        {
              "source": "textbook.pdf",
              "page": 3,
              "score": 0.9
        }
  ]
}

GET/conversations/{id}

Get conversation

Retrieves a single conversation, including all messages.

Request

GET

/conversations/{id}

curl https://api.chariotai.com/conversations/{id} \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Response

{
  "id": "string",
  "application_id": "app_123",
  "messages": [],
  "title": "string",
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_tokens": 0,
  "created_at": "2023-05-21T00:00:00.000Z",
  "updated_at": "2023-05-21T00:00:00.000Z"
}

PUT/conversations/{id}

Update conversation

Updates the specifed conversation.

Optional attributes

Name
title
Type
string
Description

Request

PUT

/conversations/{id}

curl https://api.chariotai.com/conversations/{id} \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Response

{
  "id": "string",
  "application_id": "app_123",
  "messages": [],
  "title": "string",
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_tokens": 0,
  "created_at": "2023-05-21T00:00:00.000Z",
  "updated_at": "2023-05-21T00:00:00.000Z"
}

DELETE/conversations/{id}

Delete conversation

Permanently deletes a conversation and all related messages. This cannot be undone.

Request

DELETE

/conversations/{id}

curl https://api.chariotai.com/conversations/{id} \
  -H "Authorization: Bearer {YOUR_API_KEY}"