Conversations
Create and manage conversations to store and retrieve conversation state across Response API calls.
Create a conversation
POST https://api.extravaganza.com.pl/v1/conversations
Create a conversation
Request body
Returns
Returns a conversation object.
curl -X POST https://api.extravaganza.com.pl/v1/conversations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"metadata": {"topic": "demo"},
"items": [
{
"type": "message",
"role": "user",
"content": "Hello!"
}
]
}'{
"id": "conv_123",
"object": "conversation",
"created_at": 1741900000,
"metadata": {"topic": "demo"}
}Retrieve a conversation
GET https://api.extravaganza.com.pl/v1/conversations/{conversation_id}
Get a conversation.
Path parameters
conversation_id: string (Required)
The ID of the conversation to retrieve.
Returns
Returns a conversation object.
curl -X GET https://api.extravaganza.com.pl/v1/conversations/conv_123 \
-H "Authorization: Bearer $API_KEY"{
"id": "conv_123",
"object": "conversation",
"created_at": 1741900000,
"metadata": {"topic": "demo"}
}Update a conversation
POST https://api.extravaganza.com.pl/v1/conversations/{conversation_id}
Update a conversation
Path parameters
conversation_id: string (Required)
The ID of the conversation to update.
Request body
metadata: map (Required)
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
Returns
Returns the updated conversation object.
curl -X POST https://api.extravaganza.com.pl/v1/conversations/conv_123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"metadata": {"topic": "project-x"}
}'{
"id": "conv_123",
"object": "conversation",
"created_at": 1741900000,
"metadata": {"topic": "project-x"}
}Delete a conversation
DELETE https://api.extravaganza.com.pl/v1/conversations/{conversation_id}
Delete a conversation. Items in the conversation will not be deleted.
Path parameters
conversation_id: string (Required)
The ID of the conversation to delete.
Returns
A success message.
curl -X DELETE https://api.extravaganza.com.pl/v1/conversations/conv_123 \
-H "Authorization: Bearer $API_KEY"{
"id": "conv_123",
"object": "conversation.deleted",
"deleted": true
}List items
GET https://api.extravaganza.com.pl/v1/conversations/{conversation_id}/items
List all items for a conversation with the given ID.
Path parameters
conversation_id: string (Required)
The ID of the conversation to list items for.
Query parameters
after: string (Optional)
include: array (Optional)
Returns
Returns a list object containing conversation items.
curl -X GET "https://api.extravaganza.com.pl/v1/conversations/conv_123/items?limit=10" \
-H "Authorization: Bearer $API_KEY"{
"object": "list",
"data": [
{
"type": "message",
"id": "msg_abc",
"status": "completed",
"role": "user",
"content": [
{"type": "input_text", "text": "Hello!"}
]
}
],
"first_id": "msg_abc",
"last_id": "msg_abc",
"has_more": false
}Create items
POST https://api.extravaganza.com.pl/v1/conversations/{conversation_id}/items
Create items in an conversation with the given ID.
Path parameters
conversation_id: string (Required)
The ID of the conversation to add the item to.
Query parameters
include: array (Optional)
Additional fields to include in the response. See the include parameter for listing conversation items above for more information.
Request body
items: array (Required)
The items to add to the conversation. You may add up to 20 items at a time.
Returns
Returns the list of added items.
curl -X POST https://api.extravaganza.com.pl/v1/conversations/conv_123/items \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"items": [
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "Hello!"}
]
},
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "How are you?"}
]
}
]
}'{
"object": "list",
"data": [
{
"type": "message",
"id": "msg_abc",
"status": "completed",
"role": "user",
"content": [
{"type": "input_text", "text": "Hello!"}
]
},
{
"type": "message",
"id": "msg_def",
"status": "completed",
"role": "user",
"content": [
{"type": "input_text", "text": "How are you?"}
]
}
],
"first_id": "msg_abc",
"last_id": "msg_def",
"has_more": false
}Retrieve an item
GET https://api.extravaganza.com.pl/v1/conversations/{conversation_id}/items/{item_id}
Get a single item from a conversation with the given IDs.
Path parameters
conversation_id: string (Required)
The ID of the conversation that contains the item.
item_id: string (Required)
The ID of the item to retrieve.
Query parameters
include: array (Optional)
Additional fields to include in the response. See the include parameter for listing conversation items above for more information.
Returns
Returns a conversation item.
curl -X GET https://api.extravaganza.com.pl/v1/conversations/conv_123/items/msg_abc \
-H "Authorization: Bearer $API_KEY"{
"type": "message",
"id": "msg_abc",
"status": "completed",
"role": "user",
"content": [
{"type": "input_text", "text": "Hello!"}
]
}Delete an item
DELETE https://api.extravaganza.com.pl/v1/conversations/{conversation_id}/{item_id}
Delete an item from a conversation with the given IDs.
Path parameters
conversation_id: string (Required)
The ID of the conversation that contains the item.
item_id: string (Required)
The ID of the item to delete.
Returns
Returns the updated conversation object.
curl -X DELETE https://api.extravaganza.com.pl/v1/conversations/conv_123/items/msg_abc \
-H "Authorization: Bearer $API_KEY"{
"id": "conv_123",
"object": "conversation",
"created_at": 1741900000,
"metadata": {"topic": "demo"}
}The conversation object
The time at which the conversation was created, measured in seconds since the Unix epoch.
The unique ID of the conversation.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
The object type, which is always conversation.
The item list
A list of conversation items.
A list of conversation items.
The ID of the first item in the list.
Whether there are more items available.
The ID of the last item in the list.
The type of object returned, must be list.