API Reference

API Reference

ZAO OS API routes follow consistent patterns. This page documents the conventions and lists all route families.

---

Conventions

Route Structure

src/app/api/[feature]/[action]/route.ts

Every route exports named functions for HTTP methods: GET, POST, PUT, DELETE, PATCH.

Standard Pattern

Every API route follows this structure:

import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { getSession } from '@/lib/auth/session';

const InputSchema = z.object({
  // Define expected input
});

export async function POST(req: NextRequest) {
  try {
    // 1. Check auth
    const session = await getSession();
    if (!session?.fid) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    }

    // 2. Validate input
    const body = await req.json();
    const result = InputSchema.safeParse(body);
    if (!result.success) {
      return NextResponse.json({ error: result.error.flatten() }, { status: 400 });
    }

    // 3. Business logic
    const data = await doSomething(result.data);

    // 4. Return response
    return NextResponse.json({ data });
  } catch (error) {
    console.error('Route error:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

Key Rules

1. Always validate with Zod — safeParse on all inputs, return 400 with error details
2. Always check session — return 401 if missing for authenticated routes
3. Always return NextResponse.json() — never plain Response or raw strings
4. Always wrap in try/catch — log errors server-side, return sanitized 500 to client
5. Never expose secrets — no API keys, service role keys, or private keys in responses
6. Use Promise.allSettled — for parallel operations that should be fault-tolerant

---

Route Families

Auth (/api/auth/)

Route	Method	Purpose
/api/auth/register	POST	Register new user via SIWF
/api/auth/session	GET	Get current session
/api/auth/logout	POST	Clear session cookie
/api/auth/verify	POST	Verify signed message
/api/auth/siwe	POST	Sign In With Ethereum
/api/auth/signer	POST	Request Neynar signer
/api/auth/signer/save	POST	Save approved signer
/api/auth/signer/status	GET	Check signer approval status

Platform OAuth:

Route	Method	Purpose
/api/auth/lastfm	GET	Last.fm OAuth start
/api/auth/lastfm/callback	GET	Last.fm OAuth callback
/api/auth/lastfm/disconnect	POST	Disconnect Last.fm
/api/auth/listenbrainz	POST	Connect ListenBrainz
/api/auth/twitch	GET	Twitch OAuth start
/api/auth/twitch/callback	GET	Twitch OAuth callback
/api/auth/youtube	GET	YouTube OAuth start
/api/auth/youtube/callback	GET	YouTube OAuth callback
/api/auth/kick	GET	Kick OAuth start
/api/auth/kick/callback	GET	Kick OAuth callback
/api/auth/facebook	GET	Facebook OAuth start
/api/auth/facebook/callback	GET	Facebook OAuth callback

Chat (/api/chat/)

Route	Method	Purpose
/api/chat/messages	GET	Fetch channel messages (paginated)
/api/chat/send	POST	Send a cast to channel
/api/chat/react	POST	Like or recast
/api/chat/thread/[hash]	GET	Get thread replies
/api/chat/search	GET	Search casts
/api/chat/hide	POST	Hide a message (admin)
/api/chat/schedule	GET, POST, PUT, DELETE	Scheduled posts CRUD
/api/chat/trending	GET	Trending casts

Music (/api/music/)

Route	Method	Purpose
/api/music/metadata	GET	Fetch track metadata by URL
/api/music/resolve	GET	Detect platform + resolve metadata
/api/music/search	GET	Search tracks
/api/music/library	GET, POST	User's saved tracks
/api/music/library/like	POST	Like a track
/api/music/library/react	POST	React to a track
/api/music/library/play	POST	Record a play
/api/music/playlists	GET, POST	User playlists
/api/music/playlists/[id]	GET, PUT, DELETE	Single playlist
/api/music/playlists/[id]/tracks	POST, DELETE	Playlist tracks
/api/music/submissions	GET, POST	Song submissions
/api/music/submissions/vote	POST	Vote on submission
/api/music/submissions/review	POST	Review submission (curator)
/api/music/trending-weighted	GET	Respect-weighted trending
/api/music/radio	GET	Radio playlists
/api/music/track-of-day	GET	Current track of the day
/api/music/track-of-day/vote	POST	Vote for track of day
/api/music/track-of-day/select	POST	Select winner (admin)
/api/music/lyrics	GET	Fetch lyrics
/api/music/comments	GET, POST	Track comments
/api/music/history	GET	Play history
/api/music/scrobble	POST	Scrobble to Last.fm/ListenBrainz
/api/music/artists	GET	Artist directory
/api/music/permaweb	POST	Upload to Arweave
/api/music/mint	POST	Mint track as NFT
/api/music/collect	POST	Collect a minted track
/api/music/wallet	GET	Music wallet (collected NFTs)
/api/music/share-card	GET	Generate share card image
/api/music/frame	GET	Farcaster frame embed

Members (/api/members/)

Route	Method	Purpose
/api/members/directory	GET	Member directory (paginated)
/api/members/me	GET	Current user's profile
/api/members/profile	GET, PUT	Profile read/update
/api/members/[username]	GET	Public profile by username

Admin (/api/admin/)

Route	Method	Purpose
/api/admin/allowlist	GET, POST	Allowlist CRUD
/api/admin/users	GET	User management
/api/admin/users/import	POST	Bulk CSV import
/api/admin/member-health	GET	Data quality report
/api/admin/search-users	GET	Search members
/api/admin/hidden	GET	Hidden members
/api/admin/respect-import	POST	Backfill Respect data
/api/admin/backfill	POST	General backfill operations
/api/admin/discord-link	POST	Link Discord accounts
/api/admin/poll-config	GET, PUT	Poll configuration
/api/admin/upload	POST	Admin file upload
/api/admin/ens-subnames	GET, POST	ENS subname management

Governance

Route	Method	Purpose
/api/snapshot/polls	GET	Snapshot poll data
/api/fractals/sessions	GET, POST	Fractal session management
/api/fractals/proposals	GET, POST	Fractal proposals
/api/fractals/analytics	GET	Participation metrics
/api/fractals/member/[wallet]	GET	Member fractal stats
/api/fractals/webhook	POST	Fractal event webhook
/api/zounz/proposals	GET	ZOUNZ DAO proposals
/api/zounz/proposals/list	GET	Proposal list

Respect (/api/respect/)

Route	Method	Purpose
/api/respect/leaderboard	GET	Ranked member list
/api/respect/leaderboard/embed	GET	Embeddable widget
/api/respect/member	GET	Individual balance
/api/respect/sync	POST	Sync from on-chain
/api/respect/transfers	GET	Transfer history
/api/respect/event	POST	Alchemy webhook
/api/respect/fractal	GET	Fractal integration data

Publishing (/api/publish/)

Route	Method	Purpose
/api/publish/farcaster	POST	Publish to Farcaster
/api/publish/x	POST	Publish to X/Twitter
/api/publish/bluesky	POST	Publish to Bluesky
/api/publish/telegram	POST	Publish to Telegram
/api/publish/discord	POST	Publish to Discord
/api/publish/lens	POST	Publish to Lens
/api/publish/hive	POST	Publish to Hive
/api/publish/status	GET	Check publish status
/api/broadcast/targets	GET, POST	Broadcast target config
/api/broadcast/start	POST	Start broadcast
/api/broadcast/status	GET	Broadcast status

Other Routes

Route	Method	Purpose
/api/100ms/token	POST	Voice room auth token
/api/100ms/rooms	GET, POST	Room management
/api/stream/token	POST	Stream.io auth token
/api/livepeer/stream	POST	Create Livepeer stream
/api/livepeer/clip	POST	Clip from stream
/api/search	GET	Global search
/api/search/users	GET	User search
/api/upload	POST	File upload
/api/hats/check	GET	Hat ownership check
/api/hats/tree	GET	Hat tree structure
/api/ens	GET	ENS resolution
/api/notifications	GET	User notifications
/api/notifications/send	POST	Send notification
/api/notifications/status	GET	Notification status
/api/users/profile	GET, PUT	User profile
/api/users/wallet	PUT	Update wallet
/api/users/wallet-visibility	PUT	Toggle wallet display
/api/users/solana-wallet	PUT	Link Solana wallet
/api/users/messaging-prefs	GET, PUT	XMTP preferences
/api/users/xmtp-address	GET	Resolve XMTP address
/api/moderation/queue	GET	Moderation queue
/api/activity/feed	GET	Activity feed
/api/wavewarz/sync	POST	WaveWarZ data sync
/api/wavewarz/artists	GET	WaveWarZ artists
/api/miniapp/auth	POST	Mini app auth
/api/miniapp/webhook	POST	Mini app webhook

---

Rate Limiting

All API routes are rate limited per IP via middleware (src/middleware.ts). Limits are configured per route family using Upstash Redis.

If you hit a rate limit, you'll receive:

{ "error": "Rate limit exceeded", "status": 429 }

---

Error Responses

All errors follow this format:

{
  "error": "Human-readable error message"
}

Status	Meaning
400	Invalid input (Zod validation failed)
401	Not authenticated
403	Not authorized (missing role/hat)
404	Resource not found
429	Rate limited
500	Server error (details logged server-side)