API Reference

Documentation for the Kodey.ai API endpoints and usage

This document provides details on how to interact with the Kodey.ai API to manage and utilize your AI agents through HTTP requests. The API allows you to create and manage chats, handle messages, and administer teams within the Kodey platform.

Authentication

All API requests require authentication using an API key. The API key should be included in the x-api-key header of your requests.

x-api-key: your-api-key-here

Different endpoints require different levels of API keys:

  • Team-level API keys: Used for Chat operations
  • Tenant-level API keys: Used for Team management operations

Base URL

The base URL for all API endpoints is:

https://api.kodey.ai

Chat Operations

Chat operations allow you to create and manage conversations with your AI agents.

Create a New Chat

Creates a new chat session with an AI agent.

Endpoint: POST /chat

Headers:

  • x-api-key: Your team-level API key (required)

Request Body:

{
    "prompt": "Your initial message to the agent",
    "connectionId": "WebSocket connection ID for real-time updates"
}

Example Request:

{
    "prompt": "Help me build an e-commerce recommendation system",
    "connectionId": "Gs_DuevxIAMCEoA="
}

Response: The response will include a unique chat ID and initial message details.

List All Chats

Retrieves a list of all chat sessions associated with your team.

Endpoint: GET /chat

Headers:

  • x-api-key: Your team-level API key (required)

Response: Returns an array of chat objects with their IDs and metadata.

Update a Chat

Updates an existing chat session.

Endpoint: PUT /chat/{chatId}

Path Parameters:

  • chatId: The unique identifier of the chat to update

Headers:

  • x-api-key: Your team-level API key (required)

Add a Message to a Chat

Sends a new message to an existing chat session.

Endpoint: POST /chat/{chatId}/message

Path Parameters:

  • chatId: The unique identifier of the chat

Headers:

  • x-api-key: Your team-level API key (required)

Request Body:

{
    "prompt": "Your message to the agent",
    "connectionId": "WebSocket connection ID for real-time updates"
}

Example Request:

{
    "prompt": "How would I implement user-based collaborative filtering?",
    "connectionId": "Gs_DuevxIAMCEoA="
}

List Messages in a Chat

Retrieves all messages from a specific chat session.

Endpoint: GET /chat/{chatId}/message

Path Parameters:

  • chatId: The unique identifier of the chat

Headers:

  • x-api-key: Your team-level API key (required)

Response: Returns an array of message objects associated with the specified chat.

Team Operations

Team operations allow you to create and manage teams within your Kodey.ai organization.

Create a New Team

Creates a new team within your organization.

Endpoint: POST /team

Headers:

  • x-api-key: Your tenant-level API key (required)

Request Body:

{
    "name": "Team name",
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}

Example Request:

{
    "name": "Enterprise Solutions Team",
    "metadata": {
        "department": "Engineering",
        "focus": "Healthcare"
    }
}

List All Teams

Retrieves a list of all teams associated with your organization.

Endpoint: GET /team

Headers:

  • x-api-key: Your tenant-level API key (required)

Response: Returns an array of team objects with their IDs, names, and metadata.

Get Team by ID

Retrieves information about a specific team.

Endpoint: GET /team/{teamId}

Path Parameters:

  • teamId: The unique identifier of the team

Headers:

  • x-api-key: Your tenant-level API key (required)

Response: Returns detailed information about the specified team.

WebSocket Connections

For real-time interaction with your agents, Kodey.ai provides WebSocket connections. The connection ID should be included when creating chats or sending messages to enable real-time updates.

To establish a WebSocket connection:

  1. Connect to the WebSocket endpoint: wss://ws.kodey.ai
  2. Use the returned connectionId in your chat and message requests

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

  • 200 OK: The request was successful
  • 400 Bad Request: The request was invalid or improperly formatted
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: The API key doesn't have permission for the requested operation
  • 404 Not Found: The requested resource doesn't exist
  • 500 Internal Server Error: An error occurred on the server

Error responses include a JSON body with more details about the error.

Code Examples

JavaScript/Node.js

const fetch = require('node-fetch');

// Create a new chat
async function createChat(apiKey, prompt, connectionId) {
  const response = await fetch('https://api.kodey.ai/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      prompt: prompt,
      connectionId: connectionId
    })
  });
  
  return response.json();
}

// List all messages in a chat
async function listMessages(apiKey, chatId) {
  const response = await fetch(`https://api.kodey.ai/chat/${chatId}/message`, {
    method: 'GET',
    headers: {
      'x-api-key': apiKey
    }
  });
  
  return response.json();
}

Python

import requests

# Create a new chat
def create_chat(api_key, prompt, connection_id):
    url = "https://api.kodey.ai/chat"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": api_key
    }
    payload = {
        "prompt": prompt,
        "connectionId": connection_id
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# List all messages in a chat
def list_messages(api_key, chat_id):
    url = f"https://api.kodey.ai/chat/{chat_id}/message"
    headers = {
        "x-api-key": api_key
    }
    
    response = requests.get(url, headers=headers)
    return response.json()

Rate Limits

The Kodey.ai API implements rate limiting to ensure fair usage and optimal performance. Rate limits vary by endpoint and subscription tier. When a rate limit is exceeded, the API will return a 429 Too Many Requests status code.

For specific rate limit details and enterprise options, please contact our support team.

Webhook Notifications

Kodey.ai can send webhook notifications for various events such as new messages, agent status changes, and more. To configure webhooks, please use the developer portal or contact our support team.