API Reference

Complete API documentation for integrating Fleety's customer support platform. Access endpoints for tickets, messages, chat sessions, and knowledge base management.

Base URL

https://api.fleety.dev/v1

💡 Note: All API requests should be made to https://api.fleety.dev/v1

Authentication

Fleety uses anonymous session tokens for public-facing widgets. This allows unauthenticated users to interact with your chat and ticket system without requiring user accounts.

🔓

Anonymous Sessions

For public chat widgets and ticket creation - allows unauthenticated users to interact with AI

POST /v1/init-session

{
  "project_id": "YOUR_PROJECT_ID"
}

Response:
{
  "token": "eyJ...",
  "expires_at": "2024-01-15T..."
}

Anonymous Token Endpoint

🎫 Get Anonymous Token

POST /v1/init-session

Initialize an anonymous session to get a short-lived token (5-minute TTL). Use this token for chat and ticket operations without requiring user authentication.

POST /v1/init-session
Content-Type: application/json

{
  "project_id": "YOUR_PROJECT_ID"
}

Response (200 OK):
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T12:30:00Z",
  "project_id": "YOUR_PROJECT_ID"
}

Usage:
Use the returned token in the Authorization header for subsequent API calls:
Authorization: Bearer {token}

💡 Note: Anonymous tokens expire after 5 minutes. If you receive a 401 error, request a new token using this endpoint. The tokens are tied to a unique anonymous session ID.

Chat Endpoints

💬 Send Chat Message (with Tool Calling)

POST /v1/chat/tools

Send a message to the AI chat with tool calling support (can create tickets automatically). Returns streaming response via Server-Sent Events (SSE) or JSON for tool calls.

POST /v1/chat/tools
Authorization: Bearer {anon_token}
Content-Type: application/json

{
  "messages": [
    {
      "role": "user",
      "content": "I need help with login issues"
    }
  ],
  "enable_tool_calling": true
}

Response (SSE Stream for regular chat):
data: {"choices":[{"delta":{"content":"I can"}}]}
data: {"choices":[{"delta":{"content":" help"}}]}
data: {"choices":[{"delta":{"content":" you"}}]}
data: [DONE]

OR Response (JSON for tool call):
{
  "type": "tool_call",
  "message": "I've created a support ticket...",
  "ticket_slug": "swift-bear-053"
}

💡 Note: This endpoint supports conversation history by sending an array of messages. The AI can automatically create support tickets when appropriate based on user requests.

💬 Send Chat Message (Simple)

POST /v1/chat

Send a single prompt to the AI chat. Returns streaming response via Server-Sent Events (SSE).

POST /v1/chat
Authorization: Bearer {anon_token}
Content-Type: application/json

{
  "prompt": "How do I reset my password?"
}

Response (SSE Stream):
data: {"content": "To reset"}
data: {"content": " your password"}
data: {"content": ", follow these steps..."}
data: [DONE]

Ticket Endpoints

🎫 Create Ticket

POST /v1/tickets/{projectId}

Create a new support ticket. Public endpoint, no authentication required. Slugs are unique per project.

POST /v1/tickets/YOUR_PROJECT_ID
Content-Type: application/json

{
  "title": "Login issue",
  "description": "I can't log in to my account..."
}

Response:
{
  "id": "...",
  "slug": "swift-bear-053",
  "project_id": "YOUR_PROJECT_ID",
  "title": "Login issue",
  "description": "I can't log in...",
  "status": "open",
  "created_at": "2024-01-15T10:00:00Z",
  "messages": []
}

📋 Get Ticket

GET /v1/tickets/{projectId}/{slug}

Retrieve a ticket by project ID and slug. Public endpoint with rate limiting (10 req/min).

GET /v1/tickets/YOUR_PROJECT_ID/swift-bear-053

Response:
{
  "id": "...",
  "slug": "swift-bear-053",
  "project_id": "YOUR_PROJECT_ID",
  "title": "Login issue",
  "description": "I can't log in...",
  "status": "open",
  "messages": [
    {
      "id": "...",
      "author": "user",
      "content": "Still having issues",
      "timestamp": "2024-01-15T10:05:00Z",
      "read_by": ["admin"]
    }
  ]
}

💬 Add Message to Ticket

POST /v1/tickets/{projectId}/{slug}/messages

Add a message to an existing ticket. Public endpoint with rate limiting (10 req/min).

POST /v1/tickets/YOUR_PROJECT_ID/swift-bear-053/messages
Content-Type: application/json

{
  "author": "user",
  "content": "I tried clearing cache but still can't log in"
}

Response:
{
  "message": "Message added successfully"
}

✓ Mark Messages as Read

PATCH /v1/tickets/{projectId}/{slug}/messages/read

Mark all messages in a ticket as read by user. Rate limit: 10 req/min

PATCH /v1/tickets/abc123xyz/messages/read
Content-Type: application/json

{
  "reader": "user"
}

Response:
{
  "message": "Messages marked as read"
}

WebSocket Endpoints

Fleety provides real-time updates for tickets using WebSocket connections. This enables instant message delivery without polling, ensuring admin responses appear immediately.

🔄 Ticket Real-Time Updates

WebSocket wss://api.fleety.dev/v1/tickets/{projectId}/{slug}/ws

Connect to a ticket's WebSocket for real-time updates on new messages, atus changes, and read receipts. Includes automatic reconnection on disconnection.

// Connect to WebSocket
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsUrl = `${protocol}//api.fleety.dev/v1/tickets/${projectId}/${ticketSlug}/ws`;
const ws = new WebSocket(wsUrl);

// Handle connection
ws.onopen = () => {
  console.log('Connected to ticket WebSocket');
};

// Handle incoming messages
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
  
  // Handle different message types
  switch (message.type) {
    case 'subscribed':
      // Successfully subscribed to ticket updates
      break;
    case 'new_message':
      // New message added to ticket
      // message.payload contains the message data
      break;
    case 'status_change':
      // Ticket status changed
      // message.payload contains new status
      break;
    case 'ticket_update':
      // Other ticket updates
      break;
    case 'error':
      // Error occurred
      console.error('WebSocket error:', message.payload);
      break;
  }
};

// Handle errors
ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

// Handle disconnection
ws.onclose = () => {
  console.log('WebSocket closed');
};

📡 Message Types

subscribed: Confirmation that you're subscribed to ticket updates
new_message: A new message was added to the ticket (includes message data in payload)
status_change: The ticket status changed (includes new status in payload)
ticket_update: Other ticket property updates
error: An error occurred (includes error details in payload)

💡 Best Practices: The WebSocket connection is automatically established when viewing a ticket and closed when navigating away. Implement automatic reconnection logic with exponential backoff for production use.

Error Responses

All endpoints return errors in this format:

{
  "error": "Description of what went wrong"
}

Common HTTP Status Codes:
- 400: Bad Request (invalid input)
- 401: Unauthorized (missing/invalid token)
- 403: Forbidden (insufficient permissions)
- 404: Not Found (resource doesn't exist)
- 429: Too Many Requests (rate limited)
- 500: Internal Server Error

Rate Limiting

Public endpoints (ticket creation, get ticket, add message) have rate limiting to prevent abuse:

Limited to 10 requests per minute per IP
Rate limit headers: Check X-RateLimit-Remaining in responses

💡 Tip: Use anonymous session tokens for the chat widget to bypass rate limits on chat endpoints.

CORS Configuration

The API validates requests against your project's allowed origins. Make sure to:

Add all domains where you'll embed the widgets to your project's allowed origins
Include both with and without www if applicable
Include http://localhost:3000 (or your dev port) for development
The Origin header is automatically sent by browsers

Next Steps

Continue exploring Fleety's features using the sidebar navigation.