Skip to main content

​
List messages

Retrieve all messages for a project, ordered by creation date (oldest first).

​
Input parameters

​
projectId
string
required
Unique project identifier

​
Response

Returns an array of message objects:
​
id
string
Unique message identifier
​
projectId
string
ID of the parent project
​
role
string
Message role (e.g., “user”, “assistant”, “system”)
​
content
string
Message content
​
createdAt
DateTime
Message creation timestamp

​
Example

Request
{
  "projectId": "clx1234567890"
}
Response
[
  {
    "id": "msg_abc123",
    "projectId": "clx1234567890",
    "role": "user",
    "content": "Create a new authentication system",
    "createdAt": "2026-03-03T10:00:00Z"
  },
  {
    "id": "msg_def456",
    "projectId": "clx1234567890",
    "role": "assistant",
    "content": "I'll help you create an authentication system. Let me break this down into tickets.",
    "createdAt": "2026-03-03T10:00:15Z"
  }
]

​
Schema details

​
Input validation

The messages API uses Zod for input validation: 
import { z } from "zod"

export const listMessagesInput = z.object({ 
  projectId: z.string() 
})

​
Database model

Messages are stored with the following Prisma schema: 
model Message {
  id        String   @id
  projectId String
  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
  role      String
  content   String
  createdAt DateTime @default(now())

  @@index([projectId])
  @@map("message")
}

​
Key features

  • Messages are automatically deleted when their parent project is deleted (cascade)
  • Messages are indexed by projectId for efficient querying
  • Messages are returned in chronological order (oldest first)
  • The role field typically contains values like “user”, “assistant”, or “system” to distinguish between different message types

Build docs developers (and LLMs) love

Get started for freeTalk to us