OpenAPI Specification

Complete HAI Protocol API reference

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.