API Reference

Zentalk provides a REST API for client-server communication. All endpoints require authentication unless otherwise noted.

Authentication

Zentalk uses JWT-based authentication tied to your wallet address.

How it works

1. Client signs a challenge message with their wallet private key
2. Server verifies the signature against the claimed address
3. Server issues a JWT token for subsequent requests
4. Include the token in the Authorization header: Bearer <token>

Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json

Endpoints

Messages

End-to-end encrypted message operations.

POST /api/messages

Send an encrypted message to a recipient.

{
  "to": "0x...",
  "ciphertext": "base64_encoded_ciphertext",
  "nonce": "base64_encoded_nonce",
  "timestamp": 1704067200
}

GET /api/messages

Retrieve messages. Supports pagination.

GET /api/messages?limit=50&offset=0

Keys (E2EE)

Key bundle management for end-to-end encryption using the X3DH protocol.

POST /api/keys

Publish your identity and prekeys for X3DH key exchange.

{
  "identityKey": "base64_public_key",
  "signedPreKey": "base64_public_key",
  "signature": "base64_signature",
  "oneTimePreKeys": ["base64_key1", "base64_key2"]
}

GET /api/keys/:address

Fetch another user’s KeyBundle to initiate encrypted communication.

GET /api/keys/0x1234...abcd

Media

File upload and download for attachments.

POST /api/v1/upload-media

Upload media as multipart form data. Files should be encrypted client-side.

Content-Type: multipart/form-data

file: <binary>
metadata: {"type": "image", "encrypted": true}

GET /api/v1/media/:id

Download a previously uploaded file.

GET /api/v1/media/abc123

Calls

Voice and video call logging and history.

GET /api/v1/calls/history

Retrieve call history for the authenticated user.

GET /api/v1/calls/history?limit=20

POST /api/v1/calls/log

Log call metadata after a call ends.

{
  "peer": "0x...",
  "duration": 120,
  "type": "video",
  "timestamp": 1704067200
}

Links

URL preview generation.

GET /api/v1/links/preview

Fetch OpenGraph metadata for a URL.

GET /api/v1/links/preview?url=https://example.com

Response:

{
  "title": "Example Domain",
  "description": "This domain is for examples.",
  "image": "https://example.com/og-image.png",
  "url": "https://example.com"
}

Error Responses

All endpoints return standard error responses:

{
  "error": "error_code",
  "message": "Human readable description"
}