Skip to content

Instantly share code, notes, and snippets.

@vitosamson

vitosamson/index.md Secret

Forked from rsms/index.md
Last active August 29, 2015 14:08
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save vitosamson/6c596975c68122f95f38 to your computer and use it in GitHub Desktop.
Save vitosamson/6c596975c68122f95f38 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
index.md

Zulip HTTP API endpoints

Documents endpoints that have been found around the zulip codebase.

ZCURL='curl -u rasmus@dropbox.com:umaVjwb5l3CR5sIzVquUwiR3JvUKFJ1r https://staging.zulip.com/api/v1'

GET users/me

?

$ZCURL/users/me
{ "msg":"",
  "max_message_id":24839271,
  "pointer":24806706,
  "result":"success",
  "client_id":"43b353a9147c9f9193288237e4c6c5d4" }

GET /users/me/pointer

?

$ZCURL/users/me/pointer
{"msg":"","pointer":24806706,"result":"success"}

Can also PUT with the pointer value as form encoded pointer=VALUE

GET /users

All people "me" knows?

$ZCURL/users
{"msg":"","result":"success","members":[
  { "is_admin":false,"is_active":false,"is_bot":false,
    "email":"lfaraone+zz1@zulip.com","full_name":"Hello World"},
  { "is_admin":false,"is_active":false,"is_bot":false,
    "email":"lfaraone+zz2@zulip.com","full_name":"Bonjour Le Monde"},
  ...
]}

POST /users/me/presence

Set and/or retrieve presence?

$ZCURL/users/me/presence -d status=active -d new_user_input=true
{ "msg":"",
  "server_timestamp":1405522574.6721460819,
  "result":"success",
  "presences":{
    "nathan@dropbox.com":{
      "website":{"status":"active","timestamp":1405040386,"client":"website","pushable":false}
    },
    "vishal@dropbox.com":{
      "website":{"status":"idle","timestamp":1405522573,"client":"website","pushable":false}
    },
    ...
  }
}

GET /messages

Get messages within the range of a known message id

$ZCURL/messages -G \
  -d anchor=24851786 \
  -d num_before=1 \
  -d num_after=2 \
  -d apply_markdown=false
{ "msg":"",
  "result":"success",
  "messages":[
    { "recipient_id":34897,
      "sender_email":"rasmus@dropbox.com",
      "timestamp":1405523428,
      "display_recipient":[
        {"full_name":"Nathan Borror","domain":"zulip.com","email":"nathan@dropbox.com","short_name":"nathan","id":6106},
        {"full_name":"Rasmus Andersson","domain":"zulip.com","email":"rasmus@dropbox.com","short_name":"rasmus","id":6134}
      ],
      "sender_id":6134,
      "last_edit_timestamp":1405523879,
      "sender_full_name":"Rasmus Andersson",
      "content":"<p>Hello test<\/p>",
      "gravatar_hash":"0a8caa60c1b4547786d803d6904ca833",
      "avatar_url":"https:\/\/humbug-user-avatars.s3.amazonaws.com\/3a24a7522117f6d941d79b1b6417ffdbfd808485?x=x",
      "sender_short_name":"rasmus",
      "client":"curl",
      "content_type":"text\/html",
      "subject_links":[],
      "id":24852038,
      "flags":["read"],
      "sender_domain":"zulip.com",
      "type":"private",
      "edit_history":[
        {"prev_content":"Hello","timestamp":1405523879,"prev_rendered_content":"<p>Hello<\/p>","prev_rendered_content_version":1}
      ],
      "subject":""
    },
    ...
  ]
}

Like above, but only get messages for a particular room

$ZCURL/messages -G \
  -d anchor=0 \
  -d narrow='[{"operator":"stream","operand":"chat-hack"}]' \
  -d num_before=0 \
  -d num_after=3 \
  -d apply_markdown=false

Like above, but only get messages for a private conversation

$ZCURL/messages -G \
  -d anchor=18446744073709551615 \
  -d narrow='[{"operator":"pm-with","operand":"wdaher@dropbox.com"}]' \
  -d num_before=3 \
  -d num_after=0 \
  -d apply_markdown=false

By passing either 0 or 18446744073709551615 (UINT64_MAX) to anchor, you can jump to the oldest or most recent message, respectively.

POST /messages

Send a message

$ZCURL/messages \
  -d "type=stream" \
  -d "to=Denmark" \
  -d "subject=Castle" \
  -d "content=Something is rotten in the state of Denmark."
{"msg":"","result":"success","id":24851786}
OR
{"msg":"Stream does not exist","result":"error"}

$ZCURL/messages \
  -d "type=private" \
  -d "to=nathan@dropbox.com" \
  -d "content=Hello"
{"msg":"","result":"success","id":24852038}

POST /register

Creates a new queue over which a client receives all updates for the authed user

$ZCURL/register -d 'event_types=["message"]'
{ "msg":"",
  "max_message_id":24852242,
  "last_event_id":-1,
  "result":"success",
  "queue_id":"1405480996:1537"}

GET /events

Long-poll for any events

$ZCURL/events -G -d "queue_id=1405480996:1537" -d "last_event_id=-1"
{ "result":"success",
  "queue_id":"1405480996:1537",
  "msg":"",
  "events": [
    { "flags":["read"],
      "type":"message",
      "id":0,
      "message":{
        "content_type":"text\/x-markdown",
        "avatar_url":"https:\/\/humbug-user-...",
        "timestamp":1405523884,
        "display_recipient":[
          { "full_name":"Nathan Borror",
            "domain":"zulip.com",
            "email":"nathan@dropbox.com",
            "short_name":"nathan",
            "id":6106
          },
          { "domain":"zulip.com",
            "short_name":"rasmus",
            "email":"rasmus@dropbox.com",
            "full_name":"Rasmus Andersson",
            "id":6134
          }
        ],
        "sender_id":6134,
        "sender_full_name":"Rasmus Andersson",
        "sender_domain":"zulip.com",
        "content":"Test ",
        "gravatar_hash":"0a8caa60c1b4547786d803d6904ca833",
        "recipient_id":34897,
        "client":"website",
        "sender_email":"rasmus@dropbox.com",
        "subject_links":[],
        "subject":"",
        "type":"private",
        "id":24852431,
        "sender_short_name":"rasmus"
      } // message
    },
    { "type": "presence",
      "email": "zev@dropbox.com",
      "id": 17, "presence": {
        "website": {"client": "website", "pushable": null, "status": "active", "timestamp": 1405962487}
      },
      "server_timestamp": 1405962487.9641471
    },
    ...
  ] // events
}

GET /streams

List all public rooms

$ZCURL/streams
{ "msg":"",
  "result":"success",
  "streams":[
    { "stream_id":25383,
      "invite_only":false,
      "description":"",
      "name":"Dropbox NYC"
    }, ...
  ]
}

GET /users/me/subscriptions

List joined rooms

$ZCURL/users/me/subscriptions
{ "msg":"",
  "result":"success",
  "subscriptions":[
    { "desktop_notifications":true,
      "stream_id":24806,
      "name":"social",
      "subscribers":["stein@dropbox.com","kenp@dropbox.com",...],
      "invite_only":false,
      "color":"#76ce90",
      "audible_notifications":true,
      "description":"Topics of general interest (e.g. news, weather, etc.)",
      "email_address":"social+34a76ad3c436a33cc99f7f0e9039820c@streams.staging.zulip.com",
      "in_home_view":true
    },
    ...
  ]
}

PATCH /users/me/subscriptions

Join a new or existing room, and/or leave a room

$ZCURL/users/me/subscriptions -X PATCH -d 'add=[{"name":"lolcathd123"}]'
{ "result":"success",
  "msg":"",
  "subscribed":{"rasmus@dropbox.com":["lolcathd123"]},
  "not_subscribed":[],
  "already_subscribed":{},
  "removed":[]
}
OR when already joined:
{ "result":"success",
  "msg":"",
  "subscribed":{},
  "not_subscribed":[],
  "already_subscribed":{"rasmus@dropbox.com":["lolcathd123"]},
  "removed":[]
}

$ZCURL/users/me/subscriptions -X PATCH -d 'add=[{"name":"lolcathd123"}]' -d 'delete=["lolcathd"]'
{ "result":"success",
  "msg":"",
  "subscribed":{},
  "not_subscribed":[],
  "already_subscribed":{"rasmus@dropbox.com":["lolcathd123"]},
  "removed":["lolcathd"]
}

GET /streams/{name}/members

List members of a room

$ZCURL/streams/tuckshop/members
{ "msg":"",
  "result":"success",
  "subscribers":["stein@dropbox.com","rasmus@dropbox.com", ...]
}

To be documented

From the Python API code

Client._register('send_message', url='messages', make_request=(lambda request: request))
Client._register('update_message', method='PATCH', url='messages', make_request=(lambda request: request))
Client._register('get_messages', method='GET', url='messages/latest', longpolling=True)
Client._register('get_events', url='events', method='GET', longpolling=True, make_request=(lambda **kwargs: kwargs))
Client._register('register', make_request=_mk_events)
Client._register('deregister', url="events", method="DELETE", make_request=_mk_deregister)
Client._register('get_profile', method='GET', url='users/me')
Client._register('get_streams', method='GET', url='streams', make_request=_kwargs_to_dict)
Client._register('get_members', method='GET', url='users')
Client._register('render_message', method='GET', url='messages/render')
Client._register('create_user', method='POST', url='users')
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment