Overview The Chats API allows you to create and manage conversations with Sure’s AI assistant. Each chat contains multiple messages, and the AI automatically responds to user messages.
AI features must be enabled for your account to use these endpoints. Contact your administrator if AI features are not available.
Authentication
List/Show : Requires read or write scopeCreate/Update/Delete : Requires write scope
Chat Endpoints List All Chats Retrieve all chats for the current user.
Response Returns a paginated list of chats ordered by most recent first.
{ "chats" : [ { "id" : "1" , "title" : "Budget planning for Q1" , "last_message_at" : "2024-03-04T15:30:00Z" , "message_count" : 8 , "error" : null , "created_at" : "2024-03-01T10:00:00Z" , "updated_at" : "2024-03-04T15:30:00Z" }, { "id" : "2" , "title" : "Transaction categorization help" , "last_message_at" : "2024-03-03T12:15:00Z" , "message_count" : 4 , "error" : null , "created_at" : "2024-03-03T11:00:00Z" , "updated_at" : "2024-03-03T12:15:00Z" } ], "pagination" : { "page" : 1 , "per_page" : 20 , "total_count" : 15 , "total_pages" : 1 } }
Example Request curl -X GET https://your-domain.com/api/v1/chats \ -H "X-Api-Key: your_api_key_here"
Get a Specific Chat Retrieve a chat with its messages.
The unique identifier of the chat
Response Returns the chat object with paginated messages (50 per page).
{ "id" : "1" , "title" : "Budget planning for Q1" , "error" : null , "created_at" : "2024-03-01T10:00:00Z" , "updated_at" : "2024-03-04T15:30:00Z" , "messages" : [ { "id" : "1" , "type" : "user_message" , "role" : "user" , "content" : "Help me create a budget for Q1" , "created_at" : "2024-03-01T10:00:00Z" , "updated_at" : "2024-03-01T10:00:00Z" }, { "id" : "2" , "type" : "assistant_message" , "role" : "assistant" , "content" : "I'd be happy to help you create a Q1 budget..." , "model" : "gpt-4o" , "created_at" : "2024-03-01T10:00:15Z" , "updated_at" : "2024-03-01T10:00:15Z" , "tool_calls" : [] } ], "pagination" : { "page" : 1 , "per_page" : 50 , "total_count" : 8 , "total_pages" : 1 } }
Example Request curl -X GET https://your-domain.com/api/v1/chats/1 \ -H "X-Api-Key: your_api_key_here"
Create a Chat Create a new chat conversation.
Request Parameters Optional title for the chat. If not provided, will be generated from the first message.
Optional initial message content to start the conversation
AI model to use (defaults to system default model)
Response Returns the created chat with status 201 Created. If a message was included, it will be in the messages array and an AI response will be generated asynchronously.
{ "title" : "Investment portfolio analysis" , "message" : "Can you analyze my investment portfolio?" , "model" : "gpt-4o" }
{ "id" : "3" , "title" : "Investment portfolio analysis" , "error" : null , "created_at" : "2024-03-04T16:00:00Z" , "updated_at" : "2024-03-04T16:00:00Z" , "messages" : [ { "id" : "10" , "type" : "user_message" , "role" : "user" , "content" : "Can you analyze my investment portfolio?" , "created_at" : "2024-03-04T16:00:00Z" , "updated_at" : "2024-03-04T16:00:00Z" } ], "pagination" : { "page" : 1 , "per_page" : 50 , "total_count" : 1 , "total_pages" : 1 } }
Example Request curl -X POST https://your-domain.com/api/v1/chats \ -H "X-Api-Key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "title": "Investment portfolio analysis", "message": "Can you analyze my investment portfolio?", "model": "gpt-4o" }'
Update a Chat The unique identifier of the chat
Response { "id" : "3" , "title" : "Q1 Portfolio Review" , "error" : null , "created_at" : "2024-03-04T16:00:00Z" , "updated_at" : "2024-03-04T16:30:00Z" , "messages" : [ ... ] }
Example Request curl -X PATCH https://your-domain.com/api/v1/chats/3 \ -H "X-Api-Key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "title": "Q1 Portfolio Review" }'
Delete a Chat Delete a chat and all its messages.
The unique identifier of the chat to delete
Response Returns status 204 No Content on success.
Example Request curl -X DELETE https://your-domain.com/api/v1/chats/3 \ -H "X-Api-Key: your_api_key_here"
Message Endpoints Create a Message POST
/api/v1/chats/:chat_id/messages
Add a new message to a chat. The AI will automatically respond asynchronously.
The unique identifier of the chat
AI model to use for the response (defaults to system default)
Response Returns the created message with status 201 Created.
{ "content" : "What were my biggest expenses last month?" , "model" : "gpt-4o" }
{ "id" : "15" , "chat_id" : "1" , "type" : "user_message" , "role" : "user" , "content" : "What were my biggest expenses last month?" , "created_at" : "2024-03-04T17:00:00Z" , "updated_at" : "2024-03-04T17:00:00Z" , "ai_response_status" : "pending" , "ai_response_message" : "AI response is being generated" }
Example Request curl -X POST https://your-domain.com/api/v1/chats/1/messages \ -H "X-Api-Key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "content": "What were my biggest expenses last month?", "model": "gpt-4o" }'
Retry Last Message POST
/api/v1/chats/:chat_id/messages/retry
Regenerate the last AI assistant response.
The unique identifier of the chat
Response { "message" : "Retry initiated" , "message_id" : "16" }
Example Request curl -X POST https://your-domain.com/api/v1/chats/1/messages/retry \ -H "X-Api-Key: your_api_key_here"
Response Objects Unique identifier for the chat
Title of the conversation
Error message if the chat encountered an issue
ISO 8601 timestamp when the chat was created
ISO 8601 timestamp when the chat was last updated
Unique identifier for the message
Message type: user_message or assistant_message
Message role: user or assistant
AI model used (only for assistant messages)
Array of tool calls made by the assistant (only for assistant messages)
Unique identifier for the tool call
Name of the function called
Arguments passed to the function
Result returned by the function
Error Responses { "error" : "Chat not found" }
{ "error" : "Failed to create chat" , "details" : [ "Title can't be blank" ] }
{ "error" : "No assistant message to retry" }
{ "error" : "feature_disabled" , "message" : "AI features are not enabled for this user" }
Important Notes Asynchronous AI Responses : When you create a message, the AI response is generated asynchronously. The message creation endpoint returns immediately with status information. You’ll need to poll the chat endpoint or use webhooks to get the AI’s response.
Duplicate Response Prevention : The API automatically prevents duplicate AI responses. Each user message triggers exactly one AI response job.
AI Models : The default model is configured in your system settings. You can override it per message using the model parameter.