JSON API Reference

Register a new user. No request body required. Returns a generated user ID and an auth token.

Response 200

{
  "object": "User",
  "userId": "<generated-hex-id>",
  "name": "",
  "authToken": "<generated-token>"
}

Generate a new group ID. Caller must authenticate.

Request body

{
  "object": "User",
  "userId": "<userId>",
  "name": "",
  "authToken": "<authToken>"
}

Response 200

{
  "object": "Group",
  "groupId": "<generated-group-id>",
  "name": ""
}

Poll for pending notifications (friend requests, friend responses, group invites, direct messages) since a given timestamp.

Request body

{
  "object": "User",
  "userId": "<userId>",
  "name": "",
  "authToken": "<authToken>",
  "lastMessageTimestamp": 1712345678000
}

Response 200

{
  "object": "Notifications",
  "friendRequests": [
    {
      "object": "FriendRequest",
      "fromUserId": "<id>",
      "toUserId": "<id>",
      "protocol": "DH_AND_AES",
      "cryptoData": "<base64-key-exchange>",
      "timestamp": 1712345678000
    }
  ],
  "friendResponses": [
    {
      "object": "FriendResponse",
      "fromUserId": "<id>",
      "toUserId": "<id>",
      "cryptoData": "<base64-key-exchange>",
      "timestamp": 1712345678000
    }
  ],
  "groupInvites": [
    {
      "object": "GroupInvite",
      "fromUserId": "<id>",
      "toUserId": "<id>",
      "groupId": "<groupId>",
      "algorithm": "AES_256",
      "cryptoData": "<encrypted-group-key>",
      "timestamp": 1712345678000
    }
  ],
  "messages": [
    {
      "object": "SendMessage",
      "fromUserId": "<id>",
      "toId": "<id>",
      "encContent": "<encrypted-message>",
      "timestamp": 1712345678000
    }
  ]
}

Send a friend request. Initiates the key exchange by delivering the caller's Diffie-Hellman public key to the target user's notification queue.

Request body

{
  "object": "FriendRequest",
  "fromUserId": "<userId>",
  "authToken": "<authToken>",
  "toUserId": "<targetUserId>",
  "protocol": "DH_AND_AES",
  "cryptoData": "<base64-dh-public-key>"
}

Reply to a friend request. Completes the key exchange by delivering the responder's Diffie-Hellman public key to the original sender.

Request body

{
  "object": "FriendResponse",
  "fromUserId": "<userId>",
  "authToken": "<authToken>",
  "toUserId": "<targetUserId>",
  "cryptoData": "<base64-dh-public-key>"
}

Send an encrypted direct message to another user.

Request body

{
  "object": "SendMessage",
  "fromUserId": "<userId>",
  "authToken": "<authToken>",
  "toId": "<targetUserId>",
  "encContent": "<encrypted-message-payload>"
}

Invite a user to a group. Delivers the AES-256 encrypted group key to the recipient's notification queue. Both the target user and the group must already exist.

Request body

{
  "object": "GroupInvite",
  "fromUserId": "<userId>",
  "authToken": "<authToken>",
  "toUserId": "<targetUserId>",
  "groupId": "<groupId>",
  "algorithm": "AES_256",
  "cryptoData": "<encrypted-group-key>"
}

Send an encrypted message to a group. Uses the same schema as /postmsg with toId set to the group ID.

Request body

{
  "object": "SendMessage",
  "fromUserId": "<userId>",
  "authToken": "<authToken>",
  "toId": "<groupId>",
  "encContent": "<encrypted-message-payload>"
}

Poll for new messages in a single group since a given timestamp.

Request body

{
  "object": "PollGroup",
  "userId": "<userId>",
  "authToken": "<authToken>",
  "groupId": "<groupId>",
  "lastMessageTimestamp": 1712345678000
}

Response 200

{
  "object": "GroupNotifications",
  "messages": [
    {
      "object": "SendMessage",
      "fromUserId": "<id>",
      "toId": "<groupId>",
      "encContent": "<encrypted-message>",
      "timestamp": 1712345678000
    }
  ]
}

Poll for new messages across multiple groups at once since a given timestamp.

Request body

{
  "object": "PollGroups",
  "userId": "<userId>",
  "authToken": "<authToken>",
  "groupIds": ["<groupId1>", "<groupId2>"],
  "lastMessageTimestamp": 1712345678000
}

Response 200

Same GroupNotifications schema as /pollgroup.

Long-poll across multiple groups. Blocks server-side until a new message arrives for the user in any of the listed groups, then returns immediately.

Request body

{
  "object": "PollGroups",
  "userId": "<userId>",
  "authToken": "<authToken>",
  "groupIds": ["<groupId1>", "<groupId2>"],
  "lastMessageTimestamp": 1712345678000
}

Response 200

Plain text: the group ID that received a new message, or empty string if the wait timed out.