​
Overview

The HAI Protocol is fully specified using OpenAPI 3.1.0. This specification defines all endpoints, message schemas, and protocol components for implementing HAIP-compliant clients and servers.

​
Interactive Documentation

You can explore the complete HAI Protocol specification using the interactive OpenAPI documentation below:

​
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

All HAIP messages follow a consistent envelope 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

HAIP allows the user to bring their own authentication. Which is converted into a HAIPUser: 
{
  "id": "users primary key",
  "permissions": {"MESSAGE": ["*"], ...},
  "credits": 10000
}
The permissions restricts what the user has access to. In the above example the user can send messages to all transactions they have joined/created. If you wanted to only use a specific transaction you could set {"MESSAGE": ["46ec7297-399c-40c5-bf5a-28503a3899b1"]} Often you will want to give admins permissions to join all transactions and edit all messages.

​
Binary Frames

For audio, video, and file transmission, HAIP supports 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

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

​
Implementation Examples

These are examples that don’t use the existing SDK. We reccomend using the SDK, for most applications.

​
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

HAIP defines standard error codes and recovery strategies:
  • 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

Use the provided OpenAPI specification to generate test cases and validate your implementation: 
# 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

To ensure HAI Protocol 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
The complete OpenAPI specification provides all the details needed to build fully compliant HAIP implementations.