Skip to main content
Conversations group related messages together and give the agent memory across multiple turns. Every time you send a message to the chat endpoint without a conversationId, Wraith creates a new conversation automatically. You can also create, list, inspect, and delete conversations explicitly using the endpoints below.

​
List conversations


GET /agent/:id/conversations Returns all conversations for the specified agent, ordered by most recently updated.
​
id
string
required
The agent’s UUID.

​
Response

An array of Conversation objects:
​
id
string
Unique conversation ID.
​
title
string
Auto-generated title derived from the first message.
​
createdAt
string
ISO 8601 timestamp when the conversation was created.
​
updatedAt
string
ISO 8601 timestamp of the most recent message.
curl https://api.wraith.dev/agent/3f7a2b1c-.../conversations \
  --header "Authorization: Bearer wraith_live_abc123"
Response
[
  {
    "id": "conv-uuid-1",
    "title": "Send 0.1 ETH to bob.wraith",
    "createdAt": "2025-04-10T12:00:00Z",
    "updatedAt": "2025-04-10T12:01:30Z"
  },
  {
    "id": "conv-uuid-2",
    "title": "Invoice for consulting fee",
    "createdAt": "2025-04-09T09:00:00Z",
    "updatedAt": "2025-04-09T09:02:00Z"
  }
]

​
Create conversation


POST /agent/:id/conversations Create a new, empty conversation. You can then send messages to the chat endpoint using the returned id as the conversationId.
​
id
string
required
The agent’s UUID.

​
Response

A single Conversation object. 
curl https://api.wraith.dev/agent/3f7a2b1c-.../conversations \
  --request POST \
  --header "Authorization: Bearer wraith_live_abc123"
Response
{
  "id": "conv-uuid-3",
  "title": "",
  "createdAt": "2025-04-13T10:00:00Z",
  "updatedAt": "2025-04-13T10:00:00Z"
}

​
Get messages


GET /agent/:id/conversations/:convId/messages Fetch all messages in a conversation, in chronological order. Messages include user inputs, agent replies, tool calls, and system messages.
​
id
string
required
The agent’s UUID.
​
convId
string
required
The conversation’s UUID.

​
Response

An array of Message objects:
​
role
string
The speaker. One of user, agent, tool, or system.
​
text
string
The message content.
​
createdAt
string
ISO 8601 timestamp.
curl https://api.wraith.dev/agent/3f7a2b1c-.../conversations/conv-uuid-1/messages \
  --header "Authorization: Bearer wraith_live_abc123"
Response
[
  {
    "role": "user",
    "text": "send 0.1 ETH to bob.wraith",
    "createdAt": "2025-04-10T12:00:00Z"
  },
  {
    "role": "tool",
    "text": "{\"name\":\"send_payment\",\"status\":\"success\",\"detail\":\"{\\\"txHash\\\":\\\"0xabc...\\\"}\"}",
    "createdAt": "2025-04-10T12:00:05Z"
  },
  {
    "role": "agent",
    "text": "Payment sent — 0.1 ETH to bob.wraith. Transaction confirmed.",
    "createdAt": "2025-04-10T12:00:06Z"
  }
]

​
Delete conversation


DELETE /agent/:id/conversations/:convId Permanently delete a conversation and all of its messages. This action cannot be undone.
​
id
string
required
The agent’s UUID.
​
convId
string
required
The conversation’s UUID.
The endpoint returns 200 OK with an empty body on success. 
curl https://api.wraith.dev/agent/3f7a2b1c-.../conversations/conv-uuid-1 \
  --request DELETE \
  --header "Authorization: Bearer wraith_live_abc123"