This guide provides accurate documentation for the Egroo API, including the REST authentication endpoints and the SignalR real-time hub.

The Egroo server exposes:

• REST endpoints for authentication under /api/v1/Auth
• REST endpoints for agents under /api/v1/Agent
• 1 SignalR hub at /chathub for real-time user, friend, channel, message, and call management
• Swagger UI in development at http://localhost:5175/swagger

All real-time features — user management, friends, channels, messages, and WebRTC calls — are handled exclusively over SignalR using WebSockets.

Base URL (development): http://localhost:5175
Base URL (production): https://api.egroo.org (or your own hosted URL)

Egroo uses JWT (JSON Web Tokens) for authentication. After signing in, include the token in the Authorization header for protected endpoints:

Authorization: Bearer <your-jwt-token>

For SignalR, pass the token via the access_token query string parameter (handled automatically by the client library).

POST /api/v1/Auth/signup
Access: Anonymous
Rate limit: 100 requests / minute

Request body:

{
  "username": "your_username",
  "password": "your_password"
}

Response (Operation.Response):

{
  "success": true,
  "message": "Account created successfully",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": null
}

POST /api/v1/Auth/signin
Access: Anonymous

Request body:

{
  "username": "your_username",
  "password": "your_password"
}

Response (Operation.Response):

{
  "success": true,
  "message": null,
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET /api/v1/Auth/refreshsession
Access: Requires JWT

Returns a new token to extend the session.

Response (Operation.Response):

{
  "success": true,
  "message": null,
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

PUT /api/v1/Auth/changepassword
Access: Requires JWT

Request body:

{
  "oldPassword": "current_password",
  "newPassword": "new_secure_password"
}

Response (Operation.Result):

{
  "success": true,
  "message": "Password updated successfully"
}

The hub endpoint is /chathub. It accepts WebSockets only (no HTTP fallback transports).

Connect with the JWT token:

var connection = new HubConnectionBuilder()
    .WithUrl("http://localhost:5175/chathub", options =>
    {
        options.AccessTokenProvider = () => Task.FromResult<string?>(jwtToken);
    })
    .Build();

await connection.StartAsync();

After connecting, call SendPendingMessages to receive any messages that arrived while offline.

The SignalR hub supports a maximum message size of 10 MB.

Message.Content is not stored in the Messages table. For encrypted delivery flows, the server carries recipient-specific ciphertext in pending-message tables until delivery and the recipient device decrypts locally with its private key.

Notes:

• a Message can carry plain Content or recipient-specific RecipientContents
• encrypted clients typically publish a device key before participating in encrypted delivery
• multi-device users can register more than one key; the server can emit a v2 envelope that contains multiple wrapped AES keys for the same ciphertext
• SendPendingMessages() replays undelivered ciphertext for the authenticated user after reconnect
• UpdatePendingMessage(messageId) deletes the authenticated user's pending ciphertext once the device has received and processed it
• agent replies can also include encrypted AgentRecipientContents for agent-side processing

Egroo uses hybrid encryption for message transport:

1. A sender-side encryption pipeline generates a fresh random AES key and IV for the message plaintext.
2. The plaintext is encrypted with AES-GCM.
3. The AES key is wrapped with RSA-OAEP-SHA256 for each recipient public key.
4. The resulting envelope is attached to RecipientContents or AgentRecipientContents.
5. The server stores ciphertext in pending-message tables until each recipient acknowledges delivery.
6. The recipient device decrypts the AES key with its local private key and then decrypts the message body locally.

Practical notes:

• v1 payloads contain one wrapped key for one recipient key
• v2 payloads contain multiple wrapped keys for one ciphertext so a user can decrypt on any registered device
• if a device loses its private key, that device can no longer decrypt old ciphertext sent to that key
• plaintext can still appear in memory on the sender or recipient client, but encrypted transport content is what the server persists for delivery

Example — send a message:

var message = new Message
{
    SenderId = currentUserId,
    ChannelId = channelId,
    ReferenceId = Guid.NewGuid(),
    Content = "Hello!"
};
bool ok = await connection.InvokeAsync<bool>("SendMessage", message);

The browser loads ICE server settings from the API before joining a channel call.

The SignalR hub acts as the membership and signaling plane for channel voice calls. Clients exchange WebRTC offers, answers, and ICE candidates through the hub after joining the same channel call.

Notes:

• JoinChannelCall succeeds only when the caller belongs to the channel.
• The joining client receives ExistingCallParticipants and is responsible for creating offers to those peers.
• Existing participants receive UserJoinedCall when a new user joins.
• ChannelCallParticipantsChanged is broadcast to all online channel members, not only the users already in the call.

These events are pushed from the server to connected clients.

Example listeners (C#):

connection.On<Message>("ReceiveMessage", (message) =>
{
    Console.WriteLine($"New message: {message.Content}");
});

connection.On<Guid, bool>("FriendStatusChanged", (userId, isOnline) =>
{
    Console.WriteLine($"User {userId} is now {(isOnline ? "online" : "offline")}");
});

connection.On<Guid>("ChannelChange", (channelId) =>
{
    // Refresh channel list or details
});

All agent endpoints are under /api/v1/Agent and require a valid JWT unless noted.

Example — add an agent to a channel:

POST /api/v1/Agent/channel/{channelId}/agents/{agentId}
Authorization: Bearer <jwt>

Example — search published agents:

GET /api/v1/Agent/published/search?query=assistant

Returned by REST authentication endpoints.

{
  "success": true,
  "message": "string or null",
  "userId": "guid or null",
  "token": "jwt-string or null"
}

Returned by the change password endpoint.

{
  "success": true,
  "message": "string or null"
}

{
  "id": "guid",
  "title": "string or null",
  "isPublic": false,
  "dateCreated": "2024-01-01T00:00:00Z",
  "dateUpdated": "2024-01-01T00:00:00Z or null"
}

content and displayName are transport-only fields — they are not stored in the Messages table. agentDefinitionId is set on messages produced by an AI agent.

{
  "id": "guid",
  "senderId": "guid",
  "channelId": "guid",
  "referenceId": "guid",
  "agentDefinitionId": "guid or null",
  "dateSent": "2024-01-01T00:00:00Z or null",
  "dateSeen": "2024-01-01T00:00:00Z or null",
  "displayName": "sender display name (not persisted)",
  "content": "message text (not persisted)"
}

{
  "id": "guid",
  "userId": "guid",
  "name": "My Assistant",
  "description": "string or null",
  "instructions": "You are a helpful assistant...",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "isActive": true,
  "isPublished": false,
  "temperature": 0.7,
  "maxTokens": 2048
}

{
  "id": "guid",
  "userId": "guid",
  "agentDefinitionId": "guid"
}

{
  "id": "guid",
  "username": "string",
  "role": "string",
  "lastLoginDate": "2024-01-01T00:00:00Z or null",
  "isOnline": false,
  "connectionId": "string or null",
  "avatarPreview": "data:image/png;base64,... or null",
  "userDetail": {
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  }
}

{
  "id": "guid",
  "userId": "guid",
  "friendUserId": "guid",
  "dateAcceptedOn": "2024-01-01T00:00:00Z or null"
}

{
  "contentType": "png",
  "imageBase64": "base64-encoded image string"
}

All REST endpoints use the Api fixed-window rate limiter:

Exceeding the limit returns 429 Too Many Requests.

Interactive API documentation is available in development only at:

http://localhost:5175/swagger

Bearer authentication is supported in the Swagger UI — paste your JWT token to test protected endpoints.

For more help, see the Troubleshooting Guide.