Stop Stream

Endpoint

POST /api/ai/chat/:chatId/stop

Request

curl -X POST BOX_URL/api/ai/chat/my-chat-id/stop \
  -H "x-api-key: YOUR_API_KEY"

Replace my-chat-id with the id you used in the chat request.

Response

{
  "success": true,
  "message": "Stream stopped successfully"
}

Or if no active stream:

{
  "success": false,
  "message": "No active stream found"
}

Check Stream Status

You can also check if a stream is still active:

GET /api/ai/chat/:chatId/stream-status

curl BOX_URL/api/ai/chat/my-chat-id/stream-status \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "active",
  "isActive": true,
  "startTime": "2024-01-15T10:30:00Z",
  "lastActivity": "2024-01-15T10:30:05Z",
  "messageCount": 42
}

Status Values

JavaScript Example

const BOX_URL = 'https://your-box.intelligencebox.it'; // Your server URL

async function chatWithTimeout(message, timeoutMs = 30000) {
  const chatId = 'chat-' + Date.now();

  // Start the chat
  const chatPromise = fetch(`${BOX_URL}/api/ai/chat`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      id: chatId,
      messages: [{ role: 'user', content: message }],
      boxAddress: BOX_URL
    })
  });

  // Set up timeout
  const timeoutId = setTimeout(async () => {
    console.log('Timeout - stopping stream...');
    await fetch(`${BOX_URL}/api/ai/chat/${chatId}/stop`, {
      method: 'POST',
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    });
  }, timeoutMs);

  try {
    const response = await chatPromise;
    // Parse response...
    clearTimeout(timeoutId);
    return response;
  } catch (e) {
    clearTimeout(timeoutId);
    throw e;
  }
}

When to Stop

There are several common scenarios where stopping a stream programmatically is the right approach. Understanding these will help you build a more responsive and resource-efficient integration.

• User cancellation: The user clicks a "Stop" or "Cancel" button in your UI. This is the most common scenario and should trigger an immediate stop request.
• Timeout enforcement: You set a maximum response time (e.g., 30 seconds) and automatically stop the stream if it exceeds that limit, as shown in the JavaScript example above.
• Sufficient content received: Your application only needs the first portion of a response, such as extracting a summary or the first paragraph, and can discard the rest.
• Off-topic detection: Your application monitors the stream content and determines the AI has drifted away from the intended topic.
• Error recovery: An error occurs elsewhere in your application and continuing the stream is no longer meaningful.

Partial Responses

When you stop a stream, any text that was already generated and sent to the client remains available. The AI does not "take back" content that was already streamed. This means your application can still use the partial response that was received before the stop signal. Keep in mind that the partial content may end mid-sentence or mid-word, so you may want to trim the last incomplete sentence before displaying it to the user.

Error Handling Tips

Calling stop on a stream that has already completed or does not exist will not cause an error -- it simply returns success: false with a descriptive message. This makes it safe to call stop defensively without first checking stream status. However, if you need to distinguish between a stream that was already finished and one that was never started, use the stream-status endpoint before issuing the stop call.

If you receive a network error when calling the stop endpoint, the stream may still be running. In that case, retry the stop request or check the stream status after a brief delay. Always ensure your client-side code handles both successful and failed stop attempts gracefully.