Skip to main content

​
Endpoint

POST /api/messages
Sends a user message to the AI assistant within a conversation and triggers asynchronous message processing. This endpoint creates both a user message and an assistant message placeholder, then dispatches the processing to a background job.

​
Authentication

Requires a valid Clerk session token. See Authentication for details.

​
Request Body

​
conversationId
string
required
The unique identifier of the conversation. Must be a valid Convex ID.
​
message
string
required
The user’s message content to send to the AI assistant.

​
Response

​
success
boolean
Indicates whether the message was successfully queued for processing.
​
eventId
string
The Inngest event ID for tracking the background processing job.
​
messageId
string
The Convex ID of the created assistant message placeholder.

​
Request Example

const response = await fetch('/api/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conversationId: 'k57abc123def456',
    message: 'Add error handling to the user registration function'
  })
});

const data = await response.json();
console.log(data);

​
Response Example

{
  "success": true,
  "eventId": "01HQXYZ789ABCDEF",
  "messageId": "k58xyz789ghi012"
}

​
Behavior

​
Automatic Cancellation

When a new message is sent, the endpoint automatically:
  1. Finds all processing messages in the same project
  2. Cancels those messages by sending message/cancel events
  3. Updates their status to cancelled
This ensures only one message is being processed at a time per project.

​
Message Creation

The endpoint creates two messages:
  1. User Message: Contains the user’s input with role user
  2. Assistant Message: Empty placeholder with role assistant and status processing

​
Asynchronous Processing

The actual AI response generation happens asynchronously:
  • An Inngest message/sent event is triggered
  • Background processing handles the AI generation
  • The assistant message is updated with the response
  • Status changes from processing to completed or failed

​
Error Responses

​
error
string
Description of the error that occurred.

​
Common Errors

Status CodeErrorDescription
401UnauthorizedMissing or invalid authentication token
404Conversation not foundThe specified conversationId doesn’t exist
500Internal key not configuredServer configuration error

​
Notes

  • The response is returned immediately after queueing the message, not after AI generation completes
  • Use the returned messageId to subscribe to updates and receive the AI response
  • Messages are stored in Convex database
  • Background processing is handled by Inngest
  • Only one message per project can be processing at a time

Build docs developers (and LLMs) love

Get started for freeTalk to us