5706280dd7
* Replace Maybe for Sure in select code areas * Make sure passwords are consistent * Remove (admin|member) from demo data first name * Database and schema names finally to `sure` * Fix broken test * Another (benchmarking) database name to `sure_*` * More rebranding to Sure * Missed this Maybe mention in the same page * Random nitpicks and more Maybes * Demo data accounts and more Maybes * Test data account updates * Impersonation test accounts * Consistency with `compose.example.yml`
4.2 KiB
Chat API Documentation
The Chat API allows external applications to interact with Sure's AI chat functionality.
Authentication
All chat endpoints require authentication via OAuth2 or API keys. The chat endpoints also require the user to have AI features enabled (ai_enabled: true).
Endpoints
List Chats
GET /api/v1/chats
Required Scope: read
Response:
{
"chats": [
{
"id": "uuid",
"title": "Chat title",
"last_message_at": "2024-01-01T00:00:00Z",
"message_count": 5,
"error": null,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total_count": 50,
"total_pages": 3
}
}
Get Chat
GET /api/v1/chats/:id
Required Scope: read
Response:
{
"id": "uuid",
"title": "Chat title",
"error": null,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"messages": [
{
"id": "uuid",
"type": "user_message",
"role": "user",
"content": "Hello AI",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
{
"id": "uuid",
"type": "assistant_message",
"role": "assistant",
"content": "Hello! How can I help you?",
"model": "gpt-4",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"tool_calls": []
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total_count": 2,
"total_pages": 1
}
}
Create Chat
POST /api/v1/chats
Required Scope: write
Request Body:
{
"title": "Optional chat title",
"message": "Initial message to AI",
"model": "gpt-4" // optional, defaults to gpt-4
}
Response: Same as Get Chat endpoint
Update Chat
PATCH /api/v1/chats/:id
Required Scope: write
Request Body:
{
"title": "New chat title"
}
Response: Same as Get Chat endpoint
Delete Chat
DELETE /api/v1/chats/:id
Required Scope: write
Response: 204 No Content
Create Message
POST /api/v1/chats/:chat_id/messages
Required Scope: write
Request Body:
{
"content": "User message",
"model": "gpt-4" // optional, defaults to gpt-4
}
Response:
{
"id": "uuid",
"chat_id": "uuid",
"type": "user_message",
"role": "user",
"content": "User message",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"ai_response_status": "pending",
"ai_response_message": "AI response is being generated"
}
Retry Last Message
POST /api/v1/chats/:chat_id/messages/retry
Required Scope: write
Retries the last assistant message in the chat.
Response:
{
"message": "Retry initiated",
"message_id": "uuid"
}
AI Response Handling
AI responses are processed asynchronously. When you create a message or chat with an initial message, the API returns immediately with the user message. The AI response is generated in the background.
Checking for AI Responses
Currently, you need to poll the chat endpoint to check for new AI responses. Look for new messages with type: "assistant_message".
Available AI Models
gpt-4(default)gpt-4-turbogpt-3.5-turbo
Tool Calls
The AI assistant can make tool calls to access user financial data. These appear in the tool_calls array of assistant messages:
{
"tool_calls": [
{
"id": "uuid",
"function_name": "get_accounts",
"function_arguments": {},
"function_result": { ... },
"created_at": "2024-01-01T00:00:00Z"
}
]
}
Error Handling
All endpoints return standard error responses:
{
"error": "error_code",
"message": "Human readable error message",
"details": ["Additional error details"] // optional
}
Common error codes:
unauthorized- Invalid or missing authenticationforbidden- Insufficient permissions or AI not enablednot_found- Resource not foundunprocessable_entity- Invalid request datarate_limit_exceeded- Too many requests
Rate Limits
Chat API endpoints are subject to the standard API rate limits based on your API key tier.