Behaviour shared by every endpoint, documented once.

Direct Server Routes

These endpoints are defined directly in server.js, not in route files.

Health Check

GET /api/health

• Authentication: None
• Description: Global health check endpoint
• Response:

{
  "status": "OK"
}

Get App Version

GET /api/version

• Authentication: None
• Description: Get the current application version (reads from package.json)
• Response:

{
  "version": "0.5.0"
}

Check for Updates

GET /api/updates/check

• Authentication: None
• Description: Check for application updates (proxies to agnt.gg)
• Response: Proxied response from update server

---

WebSocket / Socket.IO

AGNT uses Socket.IO for real-time bidirectional communication.

Connection

const socket = io('http://localhost:3333');
socket.emit('authenticate', { userId: 'user-id' });

Events

Event	Direction	Description
authenticate	Client → Server	Authenticate the socket connection
authenticated	Server → Client	Confirmation of successful authentication
disconnect	Bidirectional	Client disconnected
workflow:reverted	Server → Client	Broadcast when a workflow version is reverted
PLUGIN_INSTALLED	Server → Client	Broadcast when a plugin is installed

Real-time updates are broadcast via the global.io object throughout the backend.

---

Error Responses

All endpoints may return error responses in the following format:

{
  "success": false,
  "error": "Error message",
  "details": "Detailed error information",
  "code": "ERROR_CODE"
}

Common HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Authentication required or invalid
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

---

Rate Limiting

Some endpoints may have rate limiting applied. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers in responses.

---

Pagination

List endpoints that return multiple items support pagination via query parameters:

• page: Page number (default: 1)
• limit: Items per page (default: 20, max: 100)
• sort: Sort field
• order: Sort order (asc, desc)

Example: GET /api/agents?page=2&limit=10&sort=createdAt&order=desc

---

File Uploads

Endpoints that accept file uploads use multipart/form-data content type and typically have the following limits:

• Maximum file size: 20MB (varies by endpoint)
• Supported formats: Varies by endpoint (images, documents, audio, etc.)

---

Server-Sent Events (SSE)

Streaming endpoints use Server-Sent Events for real-time updates. Connect using EventSource in JavaScript or any SSE client.

Example:

const eventSource = new EventSource('/api/orchestrator/chat', {
  headers: {
    Authorization: 'Bearer your-token',
  },
});

eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);
  console.log(data);
};

---

WebSocket Support

Some endpoints may support WebSocket connections for real-time bidirectional communication. Check endpoint documentation for WebSocket availability.

---