Chat with an AI Agent

Send messages to a RubikChat AI Agent and receive intelligent responses.

Introduction

The Chat with an AI Agent endpoint allows your application to send messages to a RubikChat AI Agent and receive intelligent responses.

This endpoint automatically creates a new conversation if no conversation ID is provided. To continue an existing conversation, simply include the previously returned conversationId in your request.

The endpoint also supports streaming responses using Server-Sent Events (SSE) for real-time AI-generated output.

Endpoint

POST/api/v1/chat

Base URL

Base URL · text

https://api-proxy-v1.rubikchat.com/api/v1/

This endpoint requires Bearer Token authentication.

Request Body

Body parameters

Name	Type	Required	Description
message	`String`	required	The user's message to send to the AI Agent. This field may be omitted only when continuing a conversation after submitting a tool result.
conversationId	`String`	optional	Existing conversation ID. If omitted, RubikChat automatically creates a new conversation.
chatbotId	`String`	required	The unique identifier of the AI Agent that will process the request.
guest_user_id	`String`	optional	Associates the conversation with a specific end user. This value is only applied when creating a new conversation and cannot be changed later.

Note

Fields marked Yes* in the original spec indicate that the field may be omitted in specific contexts — see the field descriptions above for details.

Example Request

Request · bash

curl -X POST 'https://api-proxy-v1.rubikchat.com/api/v1/chat' \
-H 'Authorization: Bearer YOUR-API-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "chatbotId": "YOUR_CHATBOT_ID",
  "message": "Hello!"
}'

Example Request (Continue Existing Conversation)

Request · bash

curl -X POST 'https://api-proxy-v1.rubikchat.com/api/v1/chat' \
-H 'Authorization: Bearer YOUR-API-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "chatbotId": "YOUR_CHATBOT_ID",
  "conversationId": "PREVIOUS_CONVERSATION_ID",
  "message": "Tell me more"
}'

Successful Response

A successful request returns the assistant's message along with conversation details.

Response · json

{
  "conversationId": "conv_123456",
  "message": "Hello! How can I help you today?",
  "errors": []
}

Response Fields — Message Object

Field	Description
conversationId	Unique assistant message ID.
message	Response from agent about your query.
errors	Empty array in case of success response.

Common Error Responses

HTTP Status	Error Code	Description
`422`	Validation Error	Invalid request body or missing required fields.

Best Practices

Reuse the returned conversationId to maintain conversation context.
Store the conversationId in your application database for future requests.
Never expose your API Key in frontend applications.

Back to Overview