Skip to main content

​
POST /api/chat

Create a new chat message and stream AI responses. This endpoint handles both new messages and tool approval flows.

​
Authentication

Requires authenticated session. Returns 401 if not authenticated.

​
Request body

​
id
string
required
The chat ID (UUID format). Used to identify the conversation.
​
message
object
A new user message. Required when sending a new message (not in tool approval flow).
​
messages
array
All conversation messages. Used in tool approval flows when continuing from a specific state.
​
selectedChatModel
string
required
The AI model to use for generating responses. Must be from the allowed models list.
​
selectedVisibilityType
string
required
Chat visibility: "public" or "private"

​
Request example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "role": "user",
    "parts": [
      {
        "type": "text",
        "text": "What is the weather like today?"
      }
    ]
  },
  "selectedChatModel": "gpt-4o",
  "selectedVisibilityType": "private"
}

​
Response

Returns a streaming response with Server-Sent Events (SSE) containing:
​
stream
UIMessageStream
A stream of UI messages including text deltas, tool calls, and data events

​
Response events

{
  "type": "textDelta",
  "data": "The weather is"
}

​
Error responses

​
400
Bad Request
Invalid request body or unsupported model
​
401
Unauthorized
Not authenticated or bot detected
​
403
Forbidden
Chat belongs to different user
​
429
Rate Limited
Exceeded daily message limit

​
Rate limiting

The endpoint enforces:
  • IP-based rate limiting
  • Per-user daily message limits based on user type
  • Free users: limited messages per day
  • Premium users: higher message limits

​
Available tools

When using non-reasoning models, the AI can call these tools:
  • getWeather - Fetch weather information
  • createDocument - Create new documents (text, code, image, sheet)
  • updateDocument - Update existing documents
  • requestSuggestions - Request document editing suggestions
Reasoning models (models ending in -thinking or containing reasoning) do not have access to tools.

​
Implementation details

From app/(chat)/api/chat/route.ts:54-289:
  • Messages are saved to database before streaming begins
  • Chat title is auto-generated for new conversations
  • Streaming supports resumable streams via Redis (when configured)
  • Maximum duration: 60 seconds
  • Stop condition: 5 tool execution steps

​
DELETE /api/chat

Delete a chat conversation and all associated data.

​
Authentication

Requires authenticated session. Returns 401 if not authenticated.

​
Query parameters

​
id
string
required
The chat ID to delete (UUID format)

​
Request example

DELETE /api/chat?id=550e8400-e29b-41d4-a716-446655440000

​
Response

​
deletedChat
object
The deleted chat object
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Weather Discussion",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "visibility": "private",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Error responses

​
400
Bad Request
Missing chat ID parameter
​
401
Unauthorized
Not authenticated
​
403
Forbidden
Chat belongs to different user

​
Cascade behavior

Deleting a chat also removes:
  • All messages in the chat
  • All votes on messages
  • All stream records
From app/(chat)/api/chat/route.ts:291-314

​
GET /api/chat/[id]/stream

Health check endpoint for chat streaming. Always returns 204 No Content. From app/(chat)/api/chat/[id]/stream/route.ts:1-4

​
Response

204 No Content

Build docs developers (and LLMs) love

Get started for freeTalk to us