Skip to main content

​
GET /api/history

Retrieve paginated chat history for the authenticated user.

​
Authentication

Requires authenticated session. Returns 401 if not authenticated.

​
Query parameters

​
limit
number
default:"10"
Number of chats to return (pagination limit)
​
starting_after
string
Chat ID to start after (for forward pagination). Returns chats created after this chat.
​
ending_before
string
Chat ID to end before (for backward pagination). Returns chats created before this chat.
You cannot use both starting_after and ending_before in the same request.

​
Request examples

GET /api/history?limit=10

​
Response

Returns paginated chat history.
​
chats
array
Array of chat objects ordered by creation date (newest first)
​
hasMore
boolean
Whether more results are available for pagination

​
Response example

{
  "chats": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Weather Discussion",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "private",
      "createdAt": "2024-01-15T14:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Code Review Help",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "public",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "hasMore": true
}

​
Pagination behavior

The endpoint implements cursor-based pagination:
  1. First request: Omit both cursor parameters to get the first page
  2. Next page: Use starting_after with the ID of the last chat from current page
  3. Previous page: Use ending_before with the ID of the first chat from current page
  4. hasMore: Indicates if more results exist beyond the current page

​
Error responses

​
400
Bad Request
Both starting_after and ending_before provided, or referenced chat not found
​
401
Unauthorized
Not authenticated
From app/(chat)/api/history/route.ts:6-34

​
DELETE /api/history

Delete all chats for the authenticated user.

​
Authentication

Requires authenticated session. Returns 401 if not authenticated.

​
Request example

DELETE /api/history

​
Response

Returns count of deleted chats. 
{
  "deletedCount": 25
}
​
deletedCount
number
Number of chats deleted

​
Error responses

​
401
Unauthorized
Not authenticated

​
Cascade behavior

Deleting all chats also removes:
  • All messages in all user’s chats
  • All votes on messages
  • All stream records
From app/(chat)/api/history/route.ts:36-46
This action cannot be undone. All chat history and associated data will be permanently deleted.

​
Implementation details

From lib/db/queries.ts:125-154, the deletion process:
  1. Queries all chat IDs for the user
  2. Deletes all votes for those chats
  3. Deletes all messages for those chats
  4. Deletes all stream records for those chats
  5. Deletes all chat records
  6. Returns count of deleted chats

Build docs developers (and LLMs) love

Get started for freeTalk to us