API Reference

Talon provides a WebSocket-based remote control API for programmatic access to chat, configuration, and agent tools. You can connect over the internet via our relay server or directly on your local network.

WebSocket Connection

Endpoints

Relay (Internet): wss://talon.aieduapp.com/ws
Direct LAN: ws://[your-machine-ip]:5000/ws

Authentication

After establishing the WebSocket connection, immediately send an authentication message with your API token:

{
  "type": "auth",
  "token": "your-auth-token-here"
}

Once authenticated, you can send commands through the same connection and receive JSON responses.

Commands

chat

Send a message to the AI and receive a response.

Request:

{
  "type": "chat",
  "message": "What is the weather today?",
  "conversation_id": "conv-123"
}

Response:

{
  "status": "ok",
  "data": {
    "response": "I don't have access to real-time weather data...",
    "conversation_id": "conv-123"
  }
}

get_config

Read the current configuration.

Request:

{
  "type": "get_config"
}

Response:

{
  "status": "ok",
  "data": {
    "provider": "claude",
    "model": "claude-opus-4-6",
    "temperature": 0.7
  }
}

update_config

Write configuration settings.

Request:

{
  "type": "update_config",
  "config": {
    "temperature": 0.8,
    "model": "claude-sonnet"
  }
}

Response:

{
  "status": "ok",
  "data": {
    "updated_fields": ["temperature", "model"]
  }
}

list_conversations

Retrieve all conversations.

Request:

{
  "type": "list_conversations"
}

Response:

{
  "status": "ok",
  "data": {
    "conversations": [
      {
        "id": "conv-123",
        "title": "Project Discussion",
        "created_at": "2026-03-04T10:30:00Z"
      },
      {
        "id": "conv-456",
        "title": "API Design",
        "created_at": "2026-03-03T15:22:00Z"
      }
    ]
  }
}

get_messages

Retrieve messages from a specific conversation.

Request:

{
  "type": "get_messages",
  "conversation_id": "conv-123",
  "limit": 50
}

Response:

{
  "status": "ok",
  "data": {
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "What is the weather today?",
        "timestamp": "2026-03-04T10:30:00Z"
      },
      {
        "id": "msg-2",
        "role": "assistant",
        "content": "I don't have access to real-time weather data...",
        "timestamp": "2026-03-04T10:30:15Z"
      }
    ]
  }
}

list_tools

List all available agent tools.

Request:

{
  "type": "list_tools"
}

Response:

{
  "status": "ok",
  "data": {
    "tools": [
      {
        "name": "web_search",
        "description": "Search the web for information",
        "parameters": {
          "query": "string"
        }
      },
      {
        "name": "file_read",
        "description": "Read local files",
        "parameters": {
          "path": "string"
        }
      }
    ]
  }
}

HTTP Endpoints

POST /auth

Authenticate and obtain a session token.

Request:

curl -X POST https://talon.aieduapp.com/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

Response:

{
  "status": "ok",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

POST /ws/register

Request:

curl -X POST https://talon.aieduapp.com/ws/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"machine_name": "my-machine", "public_key": "..."}'

Response:

{
  "status": "ok",
  "data": {
    "machine_id": "mach-123",
    "relay_url": "wss://talon.aieduapp.com/ws?machine_id=mach-123"
  }
}

GET /health

Check the health status of the API.

Request:

curl https://talon.aieduapp.com/health

Response:

{
  "status": "ok",
  "uptime_seconds": 86400
}

Response Format

All API responses follow a consistent format:

{
  "status": "ok|error",
  "data": { /* command-specific data */ },
  "error": "error message" /* only present if status is 'error' */
}

status: Either ok for success or error for failures
data: Contains the result of the command
error: Only present when status is error; describes what went wrong

Error Handling

Errors are returned as JSON responses with a non-success status:

{
  "status": "error",
  "error": "Invalid authentication token"
}

Common error codes:

invalid_token — Authentication failed
unauthorized — Token valid but lacks permission
not_found — Resource (conversation, message) not found
invalid_request — Malformed command or missing required fields
server_error — Internal server error