@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Clubhouse API
@community true
@base https://www.clubhouseapi.com/api/
@version 1
@endpoints 41
@hint download_for_search
@toc start_phone_number_auth(1), call_phone_number_auth(1), resend_phone_number_auth(1), complete_phone_number_auth(1), check_waitlist_status(1), me(1), get_release_notes(1), get_all_topics(1), get_topic(1), get_clubs_for_topic(1), get_profile(1), get_users_for_topic(1), get_channels(1), join_channel(1), leave_channel(1), update_username(1), follow(1), refresh_token(1), get_suggested_invites(1), get_suggested_club_invites(1), get_club(1), check_for_update(1), invite_to_app(1), invite_from_waitlist(1), get_following(1), get_suggested_follows_friends_only(1), get_suggested_follows_all(1), update_notifications(1), get_online_friends(1), get_events(1), get_settings(1), get_welcome_channel(1), record_action_trails(1), get_notifications(1), get_actionable_notifications(1), get_create_channel_targets(1), create_channel(1), get_suggested_speakers(1), search_users(1), get_suggested_follows_similar(1), search_clubs(1)

@group start_phone_number_auth
@endpoint POST /start_phone_number_auth
@desc Starts phone number auth.
@returns(200) success
@example_request {"phone_number":"+11234567890"}

@endgroup

@group call_phone_number_auth
@endpoint POST /call_phone_number_auth
@desc Call phone number auth.
@returns(200) success

@endgroup

@group resend_phone_number_auth
@endpoint POST /resend_phone_number_auth
@desc Resend phone number auth.
@returns(200) success

@endgroup

@group complete_phone_number_auth
@endpoint POST /complete_phone_number_auth
@desc Call phone number auth.
@returns(200) success
@example_request {"verification_code":"1234","phone_number":"+1234567890"}

@endgroup

@group check_waitlist_status
@endpoint POST /check_waitlist_status
@desc checks waitlist status.
@returns(200) got waitlist status
@errors {401: authorization not provided}

@endgroup

@group me
@endpoint POST /me
@desc gets user
@returns(200) the response
@errors {403: error response - happens if account is banned (is_blocked)}
@example_request {"return_blocked_ids":true,"timezone_identifier":"America/Los_Angeles","return_following_ids":true}

@endgroup

@group get_release_notes
@endpoint POST /get_release_notes
@desc gets release notes.
@returns(200) the response

@endgroup

@group get_all_topics
@endpoint GET /get_all_topics
@desc gets all topics.
@returns(200) a list of topics

@endgroup

@group get_topic
@endpoint POST /get_topic
@desc looks up topic by ID.
@returns(200) returns topic info
@example_request {"topic_id":140}

@endgroup

@group get_clubs_for_topic
@endpoint POST /get_clubs_for_topic
@desc looks up clubs by topic.
@returns(200) returns list of clubs with pagination
@example_request {"topic_id":140}

@endgroup

@group get_profile
@endpoint POST /get_profile
@desc looks up user profile by ID.
@returns(200) returns user profile info
@example_request {"user_id":4075733}

@endgroup

@group get_users_for_topic
@endpoint GET /get_users_for_topic
@desc looks up users by topic.
@optional {topic_id: int, page_size: int, page: int}
@returns(200) returns list of users with pagination. Bios truncated to 80 chars.

@endgroup

@group get_channels
@endpoint GET /get_channels
@desc get all channels
@returns(200) list of channels

@endgroup

@group join_channel
@endpoint POST /join_channel
@desc join a channel.
@returns(200) stuff needed to actually join a channel
@errors {400: cannot join}
@example_request {"channel":"abcdefgh","attribution_source":"feed","attribution_details":"eyJpc19leHBsb3JlIjpmYWxzZSwicmFuayI6MX0="}

@endgroup

@group leave_channel
@endpoint POST /leave_channel
@desc leave a channel.
@returns(200) left the channel
@example_request {"channel":"abcdefgh"}

@endgroup

@group update_username
@endpoint POST /update_username
@desc edits username.
@returns(200) username successfully set
@errors {400: invalid/taken username (eg empty string)}
@example_request {"username":"hipsterhouse"}

@endgroup

@group follow
@endpoint POST /follow
@desc follows a user
@errors {401: waitlisted}
@example_request {"user_id":1234}

@endgroup

@group refresh_token
@endpoint POST /refresh_token
@desc gets an access_token from a refresh_token.
@returns(200) returns new access and refresh token
@errors {401: invalid refresh token}
@example_request {"refresh":"<refresh_token>"}

@endgroup

@group get_suggested_invites
@endpoint POST /get_suggested_invites
@desc find users to invite based on phone number.
@returns(200) returns list of users that can be invited.
@example_request {"club_id":null,"upload_contacts":false,"contacts":[{"phone_number":"+11234567890"}]}

@endgroup

@group get_suggested_club_invites
@endpoint POST /get_suggested_club_invites
@desc find users to invite to clubs based on phone number
@returns(200) returns list of suggested invites.
@example_request {"upload_contacts":true,"contacts":[{"name":"aaa","phone_number":"+11234567890"}]}

@endgroup

@group get_club
@endpoint POST /get_club
@desc gets club by id
@returns(200) returns club object
@example_request {"club_id":1234}

@endgroup

@group check_for_update
@endpoint GET /check_for_update
@desc Clubhouse uses this to check for updates when app is not installed from App Store (eg TestFlight)
@optional {is_testflight: int}
@returns(200) successful response

@endgroup

@group invite_to_app
@endpoint POST /invite_to_app
@desc invite a user to the app, using one of your invites
@errors {400: your own account doesn't have an invite either}
@example_request {"name":"John Smith","message":null,"phone_number":"+11234567890"}

@endgroup

@group invite_from_waitlist
@endpoint POST /invite_from_waitlist
@desc wave to another user on the waitlist to give them access
@errors {400: your own account is waitlisted, or some other error occurred}
@example_request {"user_id":1234}

@endgroup

@group get_following
@endpoint POST /get_following
@desc get a list of the users and clubs that this user is following. Returned users have bios truncated to ~80 characters.
@returns(200) returns list of users and clubs
@example_request {"user_id":1234}

@endgroup

@group get_suggested_follows_friends_only
@endpoint POST /get_suggested_follows_friends_only
@desc find people to follow by uploading contacts during signup
@returns(200) returns list of users and clubs
@example_request {"club_id":null,"upload_contacts":true,"contacts":[]}

@endgroup

@group get_suggested_follows_all
@endpoint GET /get_suggested_follows_all
@desc gets suggested follows during signup
@optional {in_onboarding: bool, page_size: int, page: int}
@returns(200) a list of users to follow. bios truncated to 80 chars.

@endgroup

@group update_notifications
@endpoint POST /update_notifications
@desc updates notification during signup.
@errors {400: waitlisted}
@example_request {"enable_trending":-1,"pause_till":-1,"is_sandbox":false,"apn_token":null,"system_enabled":2,"frequency":-1}

@endgroup

@group get_online_friends
@endpoint POST /get_online_friends
@desc gets online friends on the app homepage.
@returns(200) a list of online clubs and users.

@endgroup

@group get_events
@endpoint GET /get_events
@desc the Upcoming for You page
@optional {is_filtered: bool, page_size: int, page: int}
@returns(200) a list of events

@endgroup

@group get_settings
@endpoint GET /get_settings
@desc get notification settings
@returns(200) notification settings

@endgroup

@group get_welcome_channel
@endpoint GET /get_welcome_channel
@desc called during signup
@returns(200) empty???

@endgroup

@group record_action_trails
@endpoint POST /record_action_trails
@desc analytics
@returns(200) always empty
@example_request {"action_trails":[{"blob_data":{},"trail_type":"app_opened","client_time_created":1612971962}]}

@endgroup

@group get_notifications
@endpoint GET /get_notifications
@desc get notifications (the bell icon)
@optional {page_size: int, page: int}
@returns(200) Returns a list of notifications.

@endgroup

@group get_actionable_notifications
@endpoint GET /get_actionable_notifications
@desc get actionable notifications (the bell again)
@returns(200) Returns a list of actionable notifications.

@endgroup

@group get_create_channel_targets
@endpoint POST /get_create_channel_targets
@desc is fetched when you tap Create Room
@errors {400: waitlisted}

@endgroup

@group create_channel
@endpoint POST /create_channel
@desc creates a channel
@errors {400: waitlisted}
@example_request {"is_social_mode":false,"club_id":null,"user_ids":[],"is_private":false,"event_id":null,"topic":null}

@endgroup

@group get_suggested_speakers
@endpoint POST /get_suggested_speakers
@desc gets suggested users when you start a private room
@returns(200) Returns a list of actionable notifications.
@example_request {"channel":null}

@endgroup

@group search_users
@endpoint POST /search_users
@desc search for users
@returns(200) Returns a list of users.
@example_request {"cofollows_only":false,"following_only":false,"followers_only":false,"query":"johnsmith"}

@endgroup

@group get_suggested_follows_similar
@endpoint POST /get_suggested_follows_similar
@desc find similar users. (The Sparkles button on Clubhouse's profile page)
@returns(200) Returns a list of users. Bios truncated to 80 chars.
@example_request {"user_id":4}

@endgroup

@group search_clubs
@endpoint POST /search_clubs
@desc search clubs.
@returns(200) Returns a list of clubs.
@example_request {"cofollows_only":false,"following_only":false,"followers_only":false,"query":"rohan"}

@endgroup

@end