OpenAPI Specification

Documentation Index

Fetch the complete documentation index at: https://haiprotocol.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Interactive Documentation

​

Key Components

​

Transport Endpoints

• WebSocket: /haip/websocket - Primary real-time communication
• Server-Sent Events: /haip/sse - HTTP-based streaming
• HTTP Streaming: /haip/stream - Chunked transfer encoding

​

Message Structure

{
  "id": "uuid",
  "session": "session-id",
  "transaction": "transaction-id",
  "seq": "sequence-number",
  "ts": "timestamp",
  "channel": "USER|AGENT|SYSTEM",
  "type": "event-type",
  "payload": {} or "string",
  "bin_len": 0,
  "bin_mime": "mime-type"
}

​

Event Types

​

Core Events

• HAI - Initial Message To Open Connection
• PING/PONG - Keep alive messages
• INFO - Info messages
• ERROR - Error message
• FLOW_UPDATE - Flow control
• TRANSACTION_START - Start a new transaction
• TRANSACTION_END - End transaction
• TRANSACTION_JOIN - Join an existing transaction
• REPLAY_REQUEST - replay messages
• MESSAGE - Send a message that will be validated against the tool schema
• MESSAGE_UPDATE - Edit/delete messages
• AUDIO - Send audio to a tool
• TOOL_LIST - List out all the tools
• TOOL_SCHEMA - Get the schema for a tool

​

Authentication

{
  "id": "users primary key",
  "permissions": {"MESSAGE": ["*"], ...},
  "credits": 10000
}

​

Binary Frames

1. Envelope: JSON message with bin_len and bin_mime
2. Binary Data: Raw binary data following the envelope
3. Fragmentation: Large files split into multiple frames

​

Flow Control

• Initial Credits: Configurable per user
• Credit Thresholds: Automatic credit requests
• Back-Pressure Detection: Automatic channel pausing
• Adaptive Adjustment: Performance-based credit tuning

​

Implementation Examples

​

WebSocket Client

const ws = new WebSocket(
  "wss://api.haiprotocol.com/haip/websocket?token=jwt-token"
);

ws.onopen = () => {
  // Send handshake
  ws.send(
    JSON.stringify({
      id: crypto.randomUUID(),
      session: sessionId,
      seq: "1",
      ts: Date.now().toString(),
      channel: "SYSTEM",
      type: "HAI",
      payload: {
        haip_version: "1.1.2",
        accept_major: [1],
        accept_events: ["HAI", "MESSAGE"],
      },
    })
  );
};

​

Server-Sent Events Client

const eventSource = new EventSource("/haip/sse?token=jwt-token");

eventSource.onmessage = (event) => {
  const message = JSON.parse(event.data);
  handleHAIPMessage(message);
};

​

HTTP Streaming Client

const response = await fetch("/haip/stream?token=jwt-token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(handshakeMessage),
});

const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  handleChunk(value);
}

​

Error Handling

• 1000: Normal closure
• 1001: Going away
• 1002: Protocol error
• 1003: Unsupported data
• 1006: Abnormal closure
• 1007: Invalid frame payload
• 1008: Policy violation
• 1009: Message too big
• 1011: Internal error

​

Best Practices

​

Client Implementation

1. Connection Management
   • Implement automatic reconnection
   • Handle connection timeouts gracefully
   • Use exponential backoff for retries
2. Message Handling
   • Validate message structure
   • Handle binary frames correctly
   • Implement proper error recovery
3. Flow Control
   • Respect credit limits
   • Implement back-pressure handling
   • Monitor performance metrics

​

Server Implementation

1. Authentication
   • Validate credentials
   • Check permissions
   • Implement proper error responses
2. Message Processing
   • Validate message schemas
   • Handle binary data efficiently
   • Implement proper flow control
3. Error Handling
   • Provide meaningful error messages
   • Implement proper cleanup
   • Log errors for debugging

​

Testing

# Generate test cases
openapi-generator generate -i openapi.json -g typescript-fetch

# Validate against specification
curl -X POST http://localhost:8080/haip/websocket \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{"type":"HAI","payload":{"haip_version":"1.1.2"}}'

​

Compliance

1. Schema Validation: Validate all messages against the OpenAPI schemas
2. Event Handling: Implement all required event types
3. Flow Control: Respect credit-based flow control
4. Error Handling: Use standard error codes and messages
5. Authentication: Implement JWT token validation