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.

API Conventions