API Spec#

CreateConversation#

Creates a new conversation object in memory

POST /_plugins/_ml/memory/conversation
{
	"name": "Name for conversation"
}

Field

Type

Optional

Default

Description

name

string

yes

“”

A user-defined name for the conversation, for better identification than a uuid

Response

{
	"conversation_id": "ureogi540fedf"
}

Field

Type

Optional

Description

conversation_id

string

no

id of the newly created conversation

CreateInteraction#

Creates a new interaction object in a conversation (in memory)

POST /_plugins/_ml/memory/conversation/{conversation_id}
{
	"input": "What are the sort benchmarks",
	"prompt_template": "Answer the question, but also pay attention to these search results",
	"response": "The Sort Benchmarks are a series of benchmarks for sorting",
	"origin": "RAG Pipeline",
	"additional_info": "[Document1, Document2, etc]"
}

Field

Type

Optional

Default

Description

conversation_id

string

no

id of the conversation to add this interaction to

input

string

no

human input that started this interaction

prompt_template

string

yes

null

prompt template used to construct the prompt for this interaction

response

string

no

AI’s response for this interaction

origin

string

yes

null

Name of the system that generated this interaction

additional_info

string

yes

null

Any additional info required for reconstructing the prompt; e.g. search results in RAG

Response

{
	"interaction_id": "049t4ttjh3po"
}

Field

Type

Optional

Description

interaction_id

string

no

id of the newly created interaction

GetConversations#

Returns a list of conversations, sorted most recent → least recent

GET /_plugins/_ml/memory/conversation?max_results=5&next_token=3

Field

Type

Optional

Default

Description

next_token

int

yes

0

ordered position to start retrieving conversations from

max_results

int

yes

10

number of conversations to retrieve

Response

{
	"conversations": [
		{
			"conversation_id": "14924u4hjge",
			"create_time": timestamp,
			"name": "Name for conversation"
		}, ...
	],
	"next_token": 8
}

Field

Type

Optional

Description

conversations

List[Conversation]

no

list of conversation objects

next_token

int

yes

next next_token to use to continue retrieving conversations. If no more conversations, next_token does not appear

Conversation

Field

Type

Optional

Description

name

string

yes

A user-defined name for the conversation, for better identification than a uuid

conversation_id

string

no

uuid for this conversation

create_time

timestamp

no

when this conversation was created

GetInteractions#

Returns a list of interactions belonging to a conversation, sorted most recent → least recent

GET /_plugins/_ml/memory/conversation/{conversation_id}?max_results=5&next_token=3

Field

Type

Optional

Default

Description

conversation_id

string

no

id of the conversation to get interactions from

next_token

int

yes

0

ordered position to start retrieving conversations from

max_results

int

yes

10

number of conversations to retrieve

Response

{
	"interactions": [
		{
			"conversation_id": "14924u4hjgenkau4",
			"interaction_id": "l24ng4op5gih88ei",
			"create_time": timestamp,
			"input": "What are the sort benchmarks",
			"prompt_template": "Answer the question, but also pay attention to these search results",
			"response": "The Sort Benchmarks are a series of benchmarks for sorting",
			"origin": "RAG Pipeline",
			"additional_info": "[Document1, Document2, etc]"
		}, ...
	],
	"next_token": 8
}

Field

Type

Optional

Description

interactions

List[Interaction]

no

list of conversation objects

next_token

int

yes

next next_token to use to continue retrieving conversations. If no more conversations, next_token does not appear

Interaction

Field

Type

Optional

Description

conversation_id

string

no

id of the conversation this interaction belongs to

interaction_id

string

no

id of this interaction

create_time

timestamp

no

When this interaction was created

input

string

no

human input that started this interaction

prompt_template

string

yes

prompt template used to construct the prompt for this interaction

response

string

no

AI’s response for this interaction

origin

string

yes

Name of the system that generated this interaction

additional_info

string

yes

Any additional info required for reconstructing the prompt; e.g. search results in RAG

DeleteConversation#

Deletes a conversation and all of its interactions

DELETE /_plugins/_ml/memory/conversation/{conversation_id}

Field

Type

Optional

Description

conversation_id

string

no

id of the conversation to delete

Response

{
	"success": true
}

Field

Type

Optional

Description

success

boolean

no

whether the deletion was successful