Skip to main content
GET
/
api
/
lists
/
{id}
/
messages
Get the agent chat history for a list
curl --request GET \
  --url https://app.puffle.ai/api/lists/{id}/messages \
  --header 'Authorization: Bearer <token>'
{
  "messages": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "listId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "role": "<string>",
      "content": "<string>",
      "toolCalls": [
        {}
      ],
      "toolResult": {},
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ]
}

​
Overview

Returns every row in list_messages for the given list, ordered oldest → newest. Each entry carries:
  • role — user, assistant, system, or tool.
  • content — natural-language text, or null for pure tool-call / tool-result turns.
  • toolCalls — array of tool calls emitted by the assistant on this turn, or null.
  • toolResult — record of the tool’s result for tool-role turns, or null.
  • createdAt — ISO 8601 timestamp.
Use this to render the chat panel or to reconstruct conversation context before calling streamListChat. The server reconstructs the agent’s working memory from this transcript on every turn (profile data is serialized into HTML comments embedded in assistant messages), so editing or deleting messages via direct DB access will change the agent’s behavior on the next turn.

​
AI agent notes

When to call.
  • Before rendering the chat panel on a list detail view.
  • Before calling streamListChat if the client has been idle long enough that its in-memory copy may be stale.
  • For debugging agent behavior — tool call arguments and results are preserved here.
Ordering is stable. Messages come back ascending by createdAt. The server also persists in that order, so you can trust index positions across calls.Working memory is embedded in content. Assistant messages may contain <!-- PROFILE_DATA:...:END_PROFILE_DATA --> blocks. These are agent-internal state — render them as empty space, or strip them before displaying to the user.No pagination. The full transcript is returned in one shot. For very long-running lists this can be large, but the cap is the model’s context window applied server-side when the next turn runs, not this read endpoint.404 vs. empty. A list with no messages returns 200 { "messages": [] }. A 404 means the list doesn’t exist or isn’t owned by the caller.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

List UUID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

Full message history for the list.

​
messages
object[]
required

All messages for this list, oldest first.