API Reference

Integrate with Aethyr programmatically. Our API supports both REST and WebSocket protocols for real-time streaming.

Base URL

Self-hosted: https://your-instance.com/api

Authentication

All API requests require authentication via Bearer token. Generate API keys from the Console under Settings → API Keys.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Security Note

Never expose API keys in client-side code. Use server-side requests or environment variables.

REST Endpoints

Agents

GET/api/agentsList all agents

POST/api/agentsCreate agent

GET/api/agents/:idGet agent details

PUT/api/agents/:idUpdate agent

DELETE/api/agents/:idDelete agent

Conversations

POST/api/conversationsCreate conversation

POST/api/conversations/:id/messagesSend message

GET/api/conversations/:id/messagesGet messages

Knowledge Base

POST/api/knowledge/ingestUpload document

POST/api/knowledge/searchSemantic search

WebSocket API

Use WebSocket for real-time streaming responses. Connect to receive token-by-token output as the model generates.

WebSocket Connection

// Connect to WebSocket
const ws = new WebSocket('wss://your-instance.com/api/ws');

// Authenticate
ws.send(JSON.stringify({
  type: 'auth',
  token: 'YOUR_API_KEY'
}));

// Send message and stream response
ws.send(JSON.stringify({
  type: 'message',
  conversationId: 'conv_123',
  content: 'Hello!'
}));

// Receive streaming tokens
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'token') {
    process.stdout.write(data.content);
  } else if (data.type === 'done') {
    console.log('\nComplete!');
  }
};