UBNet Public API
HTTP endpoints currently mounted by the UBNet backend. Paths are relative to the deployed API origin, for example https://my.eth-ub.net.
2.2.0
SDK version: 3.1.0
Docs version: 3.1.0
Authentication
Public read routes require no challenge authentication. Write flows use signed SPASM events or a route-specific wallet challenge.
Base, health, and settings
| Method | Path | Use |
|---|---|---|
| GET | /health | API/database health, API version, and indexer source metadata. |
| GET | /api/version | Stable API, SDK, and docs compatibility versions. |
| GET | /api/settings | Public settings currently exposed to clients. |
| GET | /api/uploads/<relativePath> | Static uploaded files such as profile and advertisement images. |
Posts and reactions
| Method | Path | Use |
|---|---|---|
| GET | /api/posts/feed | Public Feed. Supports limit, cursor, author, post_type, keyword, schema_name, schema_version, media_type, has_cid, and source_instance_host. Rows include server-derived title, preview, complete content, preview_truncated, and card_preview.media. |
| GET | /api/posts/wallet/:wallet | Top-level posts by wallet. Supports limit, cursor, visibility, and include_private=true for posts hidden from browsing. |
| GET | /api/posts/:id | Post detail and first reply page. |
| GET | /api/posts/:id/replies | Cursor-paged replies for a post. |
| POST | /api/posts/:id/access | Compatibility access endpoint. Current post reads are open. |
| GET | /api/reactions/:id | Reaction counts for a post or list target. |
The Feed ignores caller-supplied category filters and uses the server Feed category allow list. Use GET /api/events for category-scoped event discovery, or GET /api/events/top-by-category to rank categorized posts and lists by indexed likes.
Signed top-level post shape
{
"action": "post",
"schema": { "name": "ubnet-post", "version": "1.0.0" },
"categories": [{ "name": "example-category" }],
"post_type": "text",
"content": "Hello UBNet",
"post_visibility": "public"
}At least one explicit category is required. No category is inferred or defaulted. Edit events use edit_of and must not attempt to replace the original categories.
Post media and thumbnails are immutable after creation. Edit events may change content and visibility while the indexer preserves the original media identity.
Profiles and social network
| Method | Path | Use |
|---|---|---|
| GET | /api/users/search | Search profiles with keyword and limit. |
| GET | /api/users/:wallet | Profile fields, social links, aggregate counts, messaging metadata, and token-access refresh metadata. Use ?profile=business-profile or ?profile_name=business-profile to select a named profile. |
| GET | /api/users/:wallet/following | Wallets followed by this wallet. |
| GET | /api/users/:wallet/followers | Followers for this wallet. |
| GET | /api/users/:wallet/follow-export | Export follower/following data. |
Named profile values are normalized to lowercase and must match [a-z0-9][a-z0-9_-]{0,63}. Dashes and underscores are accepted. An omitted name selects personal; an invalid value returns HTTP 400 with invalid_profile_name.
Messages and chats
| Method | Path | Use |
|---|---|---|
| GET | /api/messages/chats/:wallet | Cursor-paged chat list for a wallet. Supports limit, cursor, and search. |
| GET | /api/messages/activity | Incoming chat activity for a wallet. |
| GET | /api/messages/chat-id | Resolve the deterministic direct-chat ID for two wallets. |
| GET | /api/messages/profile/:wallet | Canonical messaging profile route. |
| GET | /api/messages/profiles/:wallet | Compatibility alias for the messaging profile route. |
| GET | /api/messages/key-backup/:wallet | Encrypted messaging-key recovery backup. |
| GET | /api/messages/chat/:chat_id/state | Chat state for participant/visibility checks. |
| GET | /api/messages/chat/:chat_id | Chat metadata. |
| GET | /api/messages/chats/:chat_id/messages | Messages in a chat. |
Current messaging protocol: ubnet-e2ee-v2.
Current public-key prefix: ubnet-ecdh-p256-v2:.
Accepted indexed message encodings: aes-gcm-v2 and group-aes-gcm-v2. Plaintext and legacy message encodings are ignored by the current indexer.
Message rows expose signed created_at and unsigned indexer metadata server_received_at. Message ordering uses server_received_at first, with created_at as the legacy fallback.
Lists
The same router is mounted at both /api/lists and /api/collections. Use “Lists” in user-facing copy; the collection path remains a compatibility route.
| Method | Path | Use |
|---|---|---|
| GET | /api/collections or /api/lists | Public list index. Supports limit, cursor, and keyword. |
| GET | /api/collections/owner/:wallet | Owner list view with visibility filtering. |
| GET | /api/collections/wallet/:wallet | Public lists for a wallet. |
| GET | /api/collections/:id | List detail metadata. |
| GET | /api/collections/:id/items | Items for a list. |
| GET | /api/collections/:id/items/:itemId | One list item. |
| POST | /api/collections/:id/unlock-challenge | Request the wallet message required to unlock a token-gated list. |
| POST | /api/collections/:id/unlock | Verify token access and unlock a list. |
| POST | /api/collections/:id/items/:itemId/unlock-challenge | Request the wallet message required to unlock private item media. |
| POST | /api/collections/:id/items/:itemId/unlock | Verify token access and return a temporary private-media URL. |
NFT galleries
| Method | Path | Use |
|---|---|---|
| GET | /api/nft-galleries/editor/:wallet | Editor data for a wallet NFT gallery. |
| GET | /api/nft-galleries/profile/:wallet | Public NFT gallery for a profile. |
Uploads
| Method | Path | Use |
|---|---|---|
| POST | /api/uploads/avatar/challenge/:wallet | Create a wallet challenge for avatar upload. |
| POST | /api/uploads/avatar/:wallet | Upload an avatar after challenge signing. |
| POST | /api/uploads/banner/challenge/:wallet | Create a wallet challenge for banner upload. |
| POST | /api/uploads/banner/:wallet | Upload a banner after challenge signing. |
| POST | /api/uploads/pinata/presigned-url | Open public Pinata URL route. Current backend intentionally returns a disabled error. |
| POST | /api/uploads/pinata/token-gated-access | Check token-gated upload access. |
| POST | /api/uploads/pinata/token-gated-challenge | Create a wallet challenge for gated upload. |
| POST | /api/uploads/pinata/token-gated-presigned-url | Create a signed upload URL after wallet and token checks. |
Public event queries
| Method | Path | Use |
|---|---|---|
| GET | /api/events | List public events using a query object or a numeric limit. |
| GET | /api/events/:id | Read one public event. |
| GET | /api/events/summary | Read the public event summary. |
| GET | /api/events/top-by-category | Rank categorized posts and lists by indexed likes. |
Use /api/events?category=example-category&latest=true&wallet=0x... for filtered discovery. Supported query fields are limit, cursor, action, author, wallet, category, category_mode, schema_name, schema_version, post_type, source_instance_host, and latest=true.
Support, domain registration, ads, and reserved names
| Method | Path | Use |
|---|---|---|
| POST | /api/support/contact | Create a support request. |
| GET | /api/reserved-subdomains/check | Check whether a normalized subdomain label is reserved. |
| POST | /api/registrations/domain_registration | Submit a signed domain-registration request. |
| GET | /api/ads | Read active ads where enabled. |