Developer API

One API for the website and the mobile apps

JSON over HTTPS with cursor pagination (?cursor&limit → { items, nextCursor }) plus Socket.IO for live chat, presence and reactions.

Authentication

Send Authorization: Bearer <accessToken>. Access tokens last 7 days; exchange the 30-day refresh token at /api/auth/refresh. Website requests use the signed-in session cookie automatically.

Real-time

Connect with io(origin, { path: '/api/socketio', auth: { token } }). Requests are limited to 5 messages per 10 seconds.

Authentication

  • POST/api/auth/register

    Create account → { user, accessToken, refreshToken }

  • POST/api/auth/login

    { email, password } → { user, accessToken (7d), refreshToken (30d) }

  • POST/api/auth/refresh

    { refreshToken } → new token pair

  • GET/api/auth/token

    Web session → bearer token (used by the website socket)

  • GET/api/auth/me

    Current account, profile and settings

Radio

  • GET/api/stations

    All stations with now playing, listeners and stream URL

  • GET/api/stations/{id}

    Station detail, up next and song history

  • GET / POST/api/reactions

    Song reactions ❤️ 🔥 🙌 ✡️ for the current track

  • POST/api/listening/heartbeat

    Send every 60s while listening { stationId } (18h/day cap)

  • GET/api/listening/stats

    Own listening hours, level and progress

  • GET/api/listening/leaderboard

    ?period=week|month|all

Chat rooms

  • GET/api/chat/rooms

    Station rooms and The Gathering Place

  • GET/api/chat/rooms/{id}/messages

    Newest first · ?cursor&limit

  • POST/api/chat/rooms/{id}/messages

    { content, type? } · text, prayer_request, voice_note_url, song_reaction

  • DELETE/api/chat/rooms/{id}/messages/{messageId}

    Own message or staff

Direct messages

  • GET / POST/api/dm/conversations

    List or start 1:1 / group (max 25) { memberIds, name? }

  • GET / POST/api/dm/conversations/{id}/messages

    Thread history and send

  • POST/api/dm/conversations/{id}/read

    Mark read (read receipts)

Prayer Wall

  • GET / POST/api/prayer-wall

    ?status=ACTIVE|ANSWERED|ARCHIVED&mine=1 · create { title, body, isAnonymous }

  • GET / PATCH / DELETE/api/prayer-wall/{id}

    Detail, mark answered, remove

  • POST / DELETE/api/prayer-wall/{id}/pray

    Toggle “Praying”

  • POST/api/prayer-wall/{id}/replies

    Encouragement reply (replies come with GET /api/prayer-wall/{id})

  • POST/api/prayer-wall/{id}/renew

    Extend another 30 days

Profiles & community

  • GET/api/profiles

    ?search= member search

  • GET / PUT/api/profiles/me

    Own profile and settings (DM privacy, language…)

  • GET/api/profiles/{id}

    Public profile

  • GET/api/profiles/{id}/stats

    Listening stats

  • POST / DELETE/api/follow/{userId}

    Follow / unfollow

  • POST / DELETE/api/block/{userId}

    Block / unblock

  • GET/api/blocked

    Blocked members

  • POST/api/report

    { reason, details?, userId? | messageId? | directMessageId? | prayerId? }

  • POST/api/upload/presigned

    { purpose: avatar|voice_note|artist_image, fileName, contentType, size }

Gatherings & circles

  • GET/api/gatherings

    ?kind=STUDY_GROUP|CHAVURAH|PRAYER_CIRCLE|SCRIPTURE_ROOM&mine=1&q= · ?cursor&limit

  • POST/api/gatherings

    { kind, name, description?, topic?, isPrivate?, stationId?, bookSlug?, bookName?, chapter?, maxSize? }

  • GET / PATCH / DELETE/api/gatherings/{id}

    Detail with members and chat room · owner edits / closes

  • POST / DELETE/api/gatherings/{id}/join

    Join or leave a gathering

  • POST/api/gatherings/circles/match

    Auto-match into the smallest open prayer circle (≤5) or start one

Daily & Scripture

  • GET/api/daily

    ?lang=en → Sacred Name of the Day, Torah Command of the Day and { roomId } for the discussion

  • GET/api/scripture/books

    ?lang=en → book list for the Scripture Reading Room picker

Testimonies & encouragement

  • GET/api/testimonies

    ?mine=1 · ?cursor&limit — the Testimony Wall

  • POST/api/testimonies

    { title, body }

  • DELETE/api/testimonies/{id}

    Remove own testimony (or staff)

  • POST/api/testimonies/{id}/praise

    Toggle a HalleluYah reaction

  • GET/api/encouragements

    ?userId= → Beraḵah (blessing) wall for a member

  • POST/api/encouragements

    { toUserId, message, scriptureRef? } → send a Beraḵah (blessing)

  • DELETE/api/encouragements/{id}

    Remove a Beraḵah you sent

Song Stories & local connections

  • GET/api/song-stories

    ?mine=1&songKey= · ?cursor&limit

  • POST/api/song-stories

    { title, story, trackTitle?, artist?, stationId? }

  • DELETE/api/song-stories/{id}

    Remove own song story (or staff)

  • GET/api/connect

    ?country=&region= → opt-in Keepers near you (city-level, requires shareLocation)

Content

  • GET/api/announcements

    Active announcements · ?language

  • GET/api/events

    Upcoming events and feast days

  • GET/api/artists

    Artist Corner · ?search

  • GET/api/artists/{id}

    Artist with tracks and fan wall

  • POST/api/artists/{id}/messages

    Post on the fan wall

  • POST / PUT / DELETE/api/announcements · /api/events · /api/artists

    Admin · create, edit ({id}) and remove ({id})

Moderation & admin (staff)

  • GET/api/reports

    ?status=OPEN|RESOLVED|DISMISSED

  • PATCH/api/reports/{id}

    { status, note? }

  • POST/api/moderate/mute

    { userId, minutes, reason? }

  • POST/api/moderate/ban

    { userId, reason?, unban? }

  • POST/api/moderate/role

    Admin · { userId, role }

  • GET / POST / DELETE/api/moderate/banned-words

    Word filter

  • GET/api/admin/users

    ?search&role&banned=1

  • GET/api/admin/stats

    Analytics payload

  • GET/api/admin/monitor

    Live chat monitor · room heat, cross-room firehose with flagged words, moderation log

  • GET/api/admin/monitor/dm

    Admin · ?userId= direct-message safety review (every lookup is logged)

Socket events

Client → server

  • join_room { roomId }
  • leave_room { roomId }
  • send_message { roomId, content, type? } with ack
  • typing_start / typing_stop { roomId }
  • heartbeat { stationId } listening time

Server → client

new_messagemessage_deleteduser_joineduser_leftuser_typingpresence_updatenew_direct_messagedm_readconversation_createdprayer_requestannouncementreaction