Complete API Reference

This page provides a quick overview of all available API endpoints. For detailed documentation on each endpoint, see the dedicated API reference pages.

API Documentation

• API Overview - Authentication, rate limiting, response formats
• Agents API - Create, manage, and chat with AI agents
• Streaming API - Livestreaming endpoints

Quick Endpoint Reference

AI Agents

Method	Endpoint	Description
GET	/api/agents	List agents
POST	/api/agents	Create agent
GET	/api/agents/:id	Get agent details
PATCH	/api/agents/:id	Update agent
DELETE	/api/agents/:id	Delete agent
POST	/api/agents/:id/chat	Chat with agent
GET	/api/agents/:id/chat	Get chat history
DELETE	/api/agents/:id/chat	Clear chat history
GET	/api/agents/:id/knowledge	Get knowledge base
POST	/api/agents/:id/knowledge	Add knowledge URL
DELETE	/api/agents/:id/knowledge	Remove knowledge URL
POST	/api/agents/:id/knowledge/index	Index knowledge
GET	/api/agents/discover	Discover public agents
GET	/api/agents/favorites	Get favorites
POST	/api/agents/favorites	Add favorite
DELETE	/api/agents/favorites	Remove favorite
GET	/api/agents/:id/embed	Get embed code
POST	/api/public/agents/:id/chat	Public agent chat (x402)

Livestreaming

Method	Endpoint	Description
GET	/api/streams	List streams
POST	/api/streams	Create stream
GET	/api/streams/:id	Get stream
PATCH	/api/streams/:id	Update stream (action, title, description; go live / end)
DELETE	/api/streams/:id	Delete stream
GET	/api/streams/:id/assets	Get recordings
GET	/api/streams/:id/chat	Get stream chat messages (optional since)
POST	/api/streams/:id/chat	Send chat message
POST	/api/streams/:id/viewers	Join stream
DELETE	/api/streams/:id/viewers	Leave stream

Authentication

Method	Endpoint	Description
GET	/api/auth/verify?address=0x...	Get SIWE message and nonce for signing
POST	/api/auth/verify	Verify SIWE signature and create session
POST	/api/auth/verify-solana	Verify SIWS signature
GET	/api/auth/session	Get current session
POST	/api/auth/logout	Logout
POST	/api/auth/world-id	Verify World ID
POST	/api/auth/alien-id	Verify Alien ID (SSO & Mini App flows)

Passkeys

Method	Endpoint	Description
POST	/api/passkey/register/options	Get registration options
POST	/api/passkey/register/verify	Verify registration
POST	/api/passkey/login/options	Get login options
POST	/api/passkey/login/verify	Verify login
GET	/api/passkey/credentials	List passkeys
DELETE	/api/passkey/credentials?id=	Remove passkey (query: credential DB id)

Wallet

Method	Endpoint	Description
GET	/api/wallet/balances?address=0x...	Get token balances (address required)
GET	/api/wallet/transactions	Get transaction history
POST	/api/wallet/smart-wallet	Get/create smart wallet
GET	/api/wallet/safe-status	Get Safe deployment status
GET	/api/wallet/recovery-signer	Get recovery signer status
POST	/api/wallet/recovery-signer	Add recovery signer
POST	/api/wallet/onramp/session	Generate Coinbase Onramp session

Username

Method	Endpoint	Description
GET	/api/username	Get username for address
POST	/api/username	Claim/update username
DELETE	/api/username	Remove username
GET	/api/username/resolve	Resolve username to address

Friends & Social

Method	Endpoint	Description
GET	/api/friends	List friends
GET	/api/profile/widgets	Get profile widgets
POST	/api/profile/widgets	Update profile widgets
GET	/api/profile/theme	Get profile theme
POST	/api/profile/theme	Update profile theme

User (Email & Preferences)

Method	Endpoint	Description
GET	/api/user/email-updates	Get email updates opt-in status (auth)
PATCH	/api/user/email-updates	Update email updates opt-in (auth; verify email required to opt in)

Upload (Encrypted Media - DMs)

Method	Endpoint	Description
POST	/api/upload/image	Upload encrypted image (multipart: file, conversationId, originalType; auth)
POST	/api/upload/voice	Upload encrypted voice memo (multipart: file, conversationId, duration; auth)

Client encrypts media with the DM conversation key before upload. See Encrypted Media for format and crypto.

User Moderation (Mute, Block, Report)

Method	Endpoint	Description
GET	/api/users/mute	Get muted conversations
POST	/api/users/mute	Mute a conversation
DELETE	/api/users/mute	Unmute a conversation
GET	/api/users/block	Get blocked users
POST	/api/users/block	Block a user
DELETE	/api/users/block	Unblock a user
GET	/api/users/report	Get reports (user/admin)
POST	/api/users/report	Submit a report
PATCH	/api/users/report	Update report status (admin)

Channels

Method	Endpoint	Description
GET	/api/channels	List channels (optional: ?poapEventId= for channel by POAP event)
POST	/api/channels	Create channel (supports POAP: poapEventId, poapEventName, poapImageUrl)
GET	/api/channels/:id	Get channel by ID or slug (:id can be UUID or slug e.g. alien, ethereum)
POST	/api/channels/:id/join	Join channel (POAP channels require holding the POAP; Smart Wallet checked for passkey users)
POST	/api/channels/:id/leave	Leave channel
GET	/api/channels/:id/messages	Get messages
POST	/api/channels/:id/messages	Send message
GET	/api/channels/:id/agents	Get official agents in channel
POST	/api/channels/agent-response	Process @mentions
GET	/api/channels/:id/polls	List polls in channel
POST	/api/channels/:id/polls	Create a poll in channel
PATCH	/api/channels/:id/polls/:pid	Update poll (vote, edit, close)
DELETE	/api/channels/:id/polls/:pid	Delete a poll

Token-Gated Chats (Token Chats)

Method	Endpoint	Description
GET	/api/token-chats?userAddress=&mode=&search=&chainId=	List/browse token chats (mode: browse | my)
POST	/api/token-chats	Create token chat (token + chain + min balance, auth; optional messagingType: waku | standard)
POST	/api/token-chats/:id/join	Join token chat (body: userAddress; must hold min balance)
POST	/api/token-chats/:id/leave	Leave token chat (body: userAddress)
GET	/api/token-chats/:id/settings	Get token chat settings (public)
PATCH	/api/token-chats/:id/settings	Update name, description, emoji (creator or admin)
POST	/api/token-chats/:id/icon	Upload custom icon (multipart: file, userAddress; 2MB max, JPEG/PNG/GIF/WebP; creator/admin/mod)
GET	/api/token-chats/:id/messages	Get messages
POST	/api/token-chats/:id/messages	Send message
DELETE	/api/token-chats/:id/messages?messageId=&userAddress=	Delete message (sender or creator/admin/mod)
GET	/api/token-chats/:id/members	Get members
GET	/api/token-chats/token-info?address=&chainId=	Get token metadata for a contract
GET	/api/token-chats/suggest-tokens?userAddress=0x...	Suggest tokens from user's balances (EOA + Spritz Wallet + vaults via Graph API); optional q to filter
GET	/api/public/token-chats/:id	Get public token chat info (no auth; for invite/share pages)

Token chats are gated by holding a minimum balance of an ERC-20 token on a given chain. Join checks the user's EOA, Spritz Wallet, and vaults for sufficient balance. Creators and members with admin/moderator roles can update settings, upload a custom icon, and manage chat rules (use chatType: "token", chatId: token chat id).

Location Chats

Method	Endpoint	Description
GET	/api/location-chats	List nearby location chats
POST	/api/location-chats	Create a location chat room
GET	/api/location-chats/:id	Get location chat details
POST	/api/location-chats/:id/join	Join a location chat
DELETE	/api/location-chats/:id/join	Leave a location chat
GET	/api/location-chats/:id/messages	Get messages in a location chat
POST	/api/location-chats/:id/messages	Send message in a location chat
GET	/api/location-chats/:id/members	Get members of a location chat
GET	/api/location-chats/joined	Get user's joined location chats

Message Deletion

Method	Endpoint	Description
POST	/api/messages/delete	Soft delete a DM message (sender or global admin)
DELETE	/api/channels/:id/messages/:messageId	Soft delete a channel message (sender, creator, or admin)
DELETE	/api/location-chats/:id/messages?messageId=	Hard delete a location chat message (sender or admin)
GET	/api/moderation?action=permissions	Get user's moderation permissions for a channel
GET	/api/moderation?action=moderators	List moderators for a channel
GET	/api/moderation?action=muted	List muted users in a channel
GET	/api/moderation?action=mod-log	View moderation audit log
POST	/api/moderation	Moderation action (promote, demote, mute, delete, pin)

Admin

Method	Endpoint	Description
POST	/api/admin/ban	Ban or unban a user (admin only, logged)
GET	/api/admin/broadcast	Get friend count for broadcast (signed admin headers)
POST	/api/admin/broadcast	Send DM to all friends (admin, signed; max 2000 chars)
GET	/api/admin/analytics	Platform analytics (period=24h|7d|30d; paginated)
GET	/api/admin/analytics/v2?section=&period=	Richer analytics by section (overview, etc.)

Image Upload (Admin)

Method	Endpoint	Description
POST	/api/upload	Upload image for Alpha Chat (admin, 5MB max, JPEG/PNG/GIF/WebP)

Chat Room Rules & Bans

Method	Endpoint	Description
GET	/api/chat-rules?chatType=&chatId=	Get room rules for a chat
POST	/api/chat-rules	Update room rules (admin/mod)
GET	/api/chat-rules/ban?chatType=&chatId=	List active room bans
POST	/api/chat-rules/ban	Ban or unban a user from a room

See Room Rules & Moderation for the full moderation system documentation.

Blocked Words (Anti-Scam)

Method	Endpoint	Description
GET	/api/blocked-words?scope=global|room|all	List blocked words (optional chatType, chatId)
POST	/api/blocked-words	Add blocked word (word, scope, action, isRegex)
DELETE	/api/blocked-words	Remove blocked word (body: { id }, soft delete)

Starred Messages

Method	Endpoint	Description
GET	/api/messages/starred	Get starred messages for a user
POST	/api/messages/starred	Star a message
DELETE	/api/messages/starred	Unstar a message

Polls

Method	Endpoint	Description
GET	/api/channels/:id/polls	List polls in a channel
POST	/api/channels/:id/polls	Create a channel poll
PATCH	/api/channels/:id/polls/:pid	Vote, edit, or close a poll
DELETE	/api/channels/:id/polls/:pid	Delete a channel poll
GET	/api/groups/:id/polls	List polls in a group
POST	/api/groups/:id/polls	Create a group poll
PATCH	/api/groups/:id/polls/:pid	Vote, edit, or close a poll
DELETE	/api/groups/:id/polls/:pid	Delete a group poll
GET	/api/alpha/polls	List polls in alpha chat
POST	/api/alpha/polls	Create an alpha chat poll
PATCH	/api/alpha/polls/:pid	Vote, edit, or close a poll

Contact Notes

Method	Endpoint	Description
GET	/api/user/contact-notes	Get notes for a contact
PUT	/api/user/contact-notes	Create or update a contact note

Email Updates

Method	Endpoint	Description
GET	/api/user/email-updates	Get email update preferences
PATCH	/api/user/email-updates	Update email notification settings

POAP (Proof of Attendance) Channels

Method	Endpoint	Description
GET	/api/poap/scan?address=0x...	Fetch user's POAPs (deduplicated events)
GET	/api/poap/events-with-channels?address=... or ?addresses=0x1,0x2	User's POAP events with channel status (multi-address; optional memberAddress)
GET	/api/poap/collections?offset=0&limit=20&query=...	List or search POAP collections (paginated)
GET	/api/poap/collections/:id	Get POAP collection by ID (includes dropIds)
GET	/api/poap/collections-for-user?address=... or ?addresses=0x1,0x2	Collections user can join (holds POAP) with channel status (optional memberAddress)

See POAP Channels Technical Guide for full integration details.

Agent Channel Management (Admin)

Method	Endpoint	Description
GET	/api/agents/:id/channels	Get channels agent is in
POST	/api/agents/:id/channels	Add agent to channel
DELETE	/api/agents/:id/channels	Remove agent from channel

Rooms & Calls

Method	Endpoint	Description
POST	/api/rooms	Create instant room
GET	/api/rooms	List rooms
GET	/api/rooms/:code	Get room
DELETE	/api/rooms/:code	Delete room
POST	/api/rooms/:code/token	Get room token
GET	/api/calls	Get call history

Scheduling & Calendar

Method	Endpoint	Description
GET	/api/scheduling/list	List scheduled calls
POST	/api/scheduling/schedule	Schedule a call
GET	/api/scheduling/availability	Get availability
POST	/api/scheduling/settings	Update settings
GET	/api/calendar/connect	Connect Google Calendar
GET	/api/calendar/status	Get calendar status
POST	/api/calendar/disconnect	Disconnect calendar

Profile & Widgets

Method	Endpoint	Description
GET	/api/spotify/search?q=&type=	Search Spotify (track, album, playlist, artist; requires env)

Utility

Method	Endpoint	Description
GET	/api/leaderboard	Get leaderboard
GET	/api/points	Get user points
POST	/api/points/daily	Claim daily points
POST	/api/bug-reports	Submit bug report

Next Steps

• API Overview - Learn about authentication and error handling
• Agents API - Detailed agent endpoint documentation
• Streaming API - Livestreaming endpoint documentation
• POAP Channels - POAP integration (scan, events-with-channels, create channel)