1x1.im API

HTTP and WebSocket reference for the 1x1.im messenger at https://1x1.im

Effective: August 23, 2026

1. Transport

Base origin: https://1x1.im

Protocols: HTTPS JSON (registration and health) + one persistent WebSocket per device/tab (wss://1x1.im/ws).

Each WebSocket message includes an Ed25519 signature, a unique nonce, and a timestamp. The signed text uses a fixed 1x1:v1 string format (see API.md for templates).

2. HTTP methods

Public HTTP endpoints on 1x1.im:

  • GET /api/health — relay status ({ status: "ok" | "degraded" }).
  • POST /api/register — create a new 1x1 number; body includes publicKey and signed registration payload.
  • POST /api/register-with-code — register with an operator-issued invitation code.
  • GET /api/call/ice-servers — ICE list for media calls; requires a short-lived ticket minted only for an authenticated session (official 1x1.im PWA). Anonymous access refused.

3. WebSocket — session

On connect the server sends nothing. The client must send the first message:

  • presence:online (signed) → server auth:ok, contact roster, offline queue flush.
  • presence:heartbeat — keep session alive.
  • presence:offline — graceful teardown.
  • Server → client: presence:update, presence:server_offline, error.

4. WebSocket — contacts

  • contact:request → contact:incoming (to recipient).
  • contact:accept | contact:reject | contact:ignore.
  • contact:accepted, contact:established (bilateral sync).
  • contact:pending:get → contact:pending:list.

5. WebSocket — messaging

  • message:send — encrypted blob to a bilateral contact.
  • message:receive — relay delivery to recipient.
  • message:delivered, message:receipt:delivered — delivery acknowledgements.
  • message:pending:get — pull offline RAM queue after auth:ok.

6. WebSocket — audio and video calls

  • call:offer, call:answer, call:ice-candidate, call:end — opaque SDP/ICE relay on the same socket.
  • Media streams are WebRTC (separate RTCPeerConnection from messaging DataChannel).
  • Third-party clients should use their own STUN/TURN; 1x1.im signaling only.

7. WebSocket — P2P messaging (DataChannel)

  • webrtc:offer, webrtc:answer, webrtc:ice-candidate — E2EE DataChannel setup for text path.
  • webrtc:signaling-complete — cleanup after channel open.

8. Cryptography and identity

  • Ed25519 — API signatures (base64url raw 32-byte public keys, 64-byte signatures).
  • X25519 + AES-GCM — per-message E2EE inside encryptedBlob.
  • Recovery — 12-word BIP39 seed phrase; message history is local-only on the device.

9. Third-party clients

The official 1x1.im client is the PWA at https://1x1.im. Other apps may use this API at their own risk without official support.

For unofficial clients, 1x1.im applies stricter limits and restrictions on various actions than for the official PWA.

10. Full specification

Wire formats, canonical string templates, and error codes are documented in API.md (1x1.im project sources).

The official 1x1.im PWA is the reference implementation for client behavior.