A conversation is a container that links multiple responses into a threaded exchange. When you supply a conversation’s id in a POST /v1/responses request, AI Assistant has access to the prior responses in that conversation to answer follow-up questions in context and refer back to earlier results and analysis.
The following outlines the endpoint to use for each conversation action:
| Action | Endpoint | Description |
|---|---|---|
| Create a conversation | POST /v1/conversations | Creates an empty conversation. |
| Retrieve a conversation | GET /v1/conversations/{id} | Retrieves conversation metadata. |
| List items in a conversation | GET /v1/conversations/{id}/items | Lists the transcript of each item in a conversation. |
| Delete a conversation | DELETE /v1/conversations/{id} | Deletes the conversation. |
Review the following sections for:
- Creating a conversation
- Sending multiple responses within that conversation
- Listing items in the conversation
- Deleting a conversation
Creating a conversation
To start a threaded exchange, you first create an empty conversation. This creates a new conversation container with a unique id that you will use to link subsequent responses together. Once created, you save the returned conv_… id, and then begin sending responses into it.
curl -s -X POST "https://<api-host>/v1/conversations" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{}'
Response:
{
"id": "conv_a1b2c3d4",
"object": "conversation",
"created_at": 1725475200,
"metadata": {}
}
Once you save the conv_… id from the response, you will pass it on every subsequent response request in this conversation.
Sending questions
Once you have a conversation id, you can send a series of questions that build on each other. By passing the same conversation id in each POST /v1/responses request, AI Assistant retains context from the prior responses, allowing you to ask follow-up questions without repeating previous context.
curl -N -X POST "https://<api-host>/v1/responses" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"stream": true,
"conversation": "conv_a1b2c3d4",
"input": "How many messages were sent from Andrea Lacey in the Lautner Wealth Merger case?",
"tools": [
{ "type": "archive_search" }
]
}'
Save the resp_… id if you need to retrieve this individual response later.
Sending a follow-up question
Because the same conversation id is used, AI Assistant has context from the prior response, so you can ask a follow-up question without repeating the prior context:
curl -N -X POST "https://<api-host>/v1/responses" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"stream": true,
"conversation": "conv_a1b2c3d4",
"input": "Can you summarize the key themes in those messages?",
"tools": [
{ "type": "archive_search" }
]
}'
AI Assistant understands “those messages” refers to the Andrea Lacey messages from the first response.
Listing conversation items
You can retrieve the full transcript of a conversation using GET /v1/conversations/{id}/items. The transcript includes every client question and AI Assistant answer in order.
To view the conversation chronologically, use order=asc
curl -s -X GET "https://<api-host>/v1/conversations/conv_a1b2c3d4/items?limit=100&order=asc" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response:
{
"object": "list",
"data": [
{
"id": "msg_000",
"type": "message",
"role": "user",
"content": [
{ "type": "input_text", "text": "How many messages were sent from Andrea Lacey in the Lautner Wealth Merger case?" }
],
"status": "completed"
},
{
"id": "msg_001",
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Andrea Lacey sent 47 messages related to the Lautner Wealth Merger between January 15 and March 3, 2026.",
"annotations": []
}
],
"status": "completed"
},
{
"id": "msg_002",
"type": "message",
"role": "user",
"content": [
{ "type": "input_text", "text": "Can you summarize the key themes in those messages?" }
],
"status": "completed"
},
{
"id": "msg_003",
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The key themes in Andrea Lacey's messages include merger timeline coordination, regulatory disclosure concerns, and internal approvals...",
"annotations": []
}
],
"status": "completed"
}
],
"first_id": "msg_000",
"last_id": "msg_003",
"has_more": false
}
The transcript includes every client question and AI Assistant answer in order. If the conversation is long, use the after and before cursor parameters to paginate:
curl -s -X GET "https://<api-host>/v1/conversations/conv_a1b2c3d4/items?limit=20&order=asc&after=msg_003" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Deleting the conversation
When you no longer need a conversation, you can permanently delete it using DELETE /v1/conversations/{id}. This removes the conversation, including all responses, messages, and reasoning items. If a response is currently in-progress, it is stopped first and then deleted.
Deletion is permanent and individual responses cannot be recovered afterward, so retrieve any responses you need to retain for audit purposes before deleting. However, if your organization archives AI Assistant data, your AI Assistant conversations are stored in Global Relay Archive for quick and convenient retrieval.
curl -s -X DELETE "https://<api-host>/v1/conversations/conv_a1b2c3d4" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response:
{
"id": "conv_a1b2c3d4",
"object": "conversation.deleted",
"deleted": true
}