API RPC Reference

Overview • Stream Message Reference

RPC Calls

API RPC calls take the form of an API method and a payload object.

WebSocket

For authenticated POST requests only, if you're using the WebSocket stream endpoint, send the payload encoded as JSON along the same socket, with the method encoded in the payload object as the _method value.

You should also send a request id as the _reqid value so you can handle the response when it arrives. This should be unique per socket session and can be any string that will be returned as the _reqid value in the response object. It's easiest to just generate an auto incrementing integer from your application.

HTTPS

If you're just using HTTPS, each API method has its own endpoint:

https://www.irccloud.com/chat/<api_method>

Send the payload as key value pairs, encoded with content-type: application/x-www-form-urlencoded.

There's no need for _reqid or _method payload values for API calls made over HTTPS.

GET / UNAUTH POST

GET and UNAUTH POST calls MUST be sent as separate HTTPS requests rather than via an existing WebSocket.

Authenticated POST

Authenticated POST requests SHOULD be sent over WebSocket. If sent over HTTPS, a session value MUST be present in the payload that matches the authentication key. This is to protect against CSRF attacks.

General Errors

An UNAUTH POST with an authenticated cookie included:

400 {"success":false, "message":"already_signed_in"}

An authenticated POST or stream request for a user whose process isn't running:

503 {"success":false, "message":"temp_unavailable"}

Unrecognised URL/method:

404 {"success":false, "message":"not_found"}

All calls can potentially throw an unhandled internal server error:

500 {"success":false, "message":"server_error"}

A call that requires a valid cid when one isn't supplied:

400 {"success":false, "message":"invalid_cid"}

A call that requires authentication when none is supplied

401 {"success":false, "message":"auth"}

A call that requires a valid form token when none is supplied:

401 {"success":false, "message":"invalid_form_token"}

A call that requires an active connection, with a cid for an inactive connection:

400 {"success":false, "message":"connection_down"}

A call that requires an active connection, with a cid for an unavailable connection:

400 {"success":false, "message":"connection_unavailable"}

# plans GET

Get list mapping of subscription plans and currency

• currency - (str) currency for unit price
• org - (obj) team plan
  • per_seat (int) unit price per seat
• solo - (obj) individual plan
  • amount (int) unit price
• solo_paypal - (obj) individual plan
  • cost (int) unit price
  • btn - (str) paypal button id (only if authed)
  • custom - (str) paypal validation token (only if authed)

-> GET /chat/plans
<- {"currency":"usd", "org":{"per_seat":500}, "solo":{"amount":500}, "solo_paypal":{"cost":500,"btn":"ADLKJASD97978","custom":"8|10|1379061498|111da6c975ae5482f5e6c63b6dfbbb5a"}}

# backlog GET

Request backlog for a buffer

• cid - (int) connection id
• bid - (int) buffer id
• num - (int) [optional] number of events to request (default: 50, max: 1000)
• beforeid - (int eid) scope results prior to this eid (exclusive) not needed for deferred buffers.

-> GET /chat/backlog?cid=1&bid=1&num=100
<- [… events …]

Errors:

-> GET /chat/backlog?cid=1
<- 400 {"success":false, "message":"invalid_bid"}

# request-invite UNAUTH POST

Request an account invite.

• email - (str) requested email address
• comments - (str) How are you currently using IRC?, e.g. what software, how many channels, work use, etc…

-> POST /chat/request-invite email=example@example.com&comments=Currently%20using%20irssi,%20want%20a%20web%20version
<- {"success":true, "email":"example@example.com"}

Errors:

-> POST /chat/request-invite email=invalid.email.address
<- 400 {"success":false, "message":"email"}

# auth-formtoken UNAUTH POST

Request a form token for login, signup and request-password-reset calls. Note, you need to send a content-length header with this request

-> POST /chat/auth-formtoken --header "content-length: 0"
<- {"success":true, "token":"1397241172970.e07910a06a086c83ba41827aa00b26ed"}

# signup UNAUTH POST

Signup for an account with an invite key.

• token - (str) auth-formtoken to prevent CSRF
• email - (str) account email. if this differs from the requested email the account will be unverified
• password - (str) account password
• realname - (str) real name
• invite - (str) invite key acquired from email triggered request-invite flow.
  Headers
• x-auth-formtoken - (str) same value as auth-formtoken in token postdata

-> POST /chat/signup token=1397241172970.e07910a06a086c83ba41827aa00b26ed email=example@example.com&password=password1&realname=Joe%20Bloggs
<- {"success":true, "session":"e07910a06a086c83ba41827aa00b26ed", "uid":1}

Errors:

-> POST /chat/login token=bad_or_missing_token email=example@example.com&password=password1&realname=Joe%20Bloggs
<- 401 {"success":false, "message":"invalid_form_token"}

-> POST /chat/signup token=139... email=invalid.email.address
<- 400 {"success":false, "message":"email"}

-> POST /chat/signup token=139... email=example@example.com
<- 400 {"success":false, "message":"password"}

-> POST /chat/signup token=139... email=example@example.com&password=password1
<- 400 {"success":false, "message":"realname"}

-> POST /chat/signup token=139... invite=invalid_invite_key
<- 400 {"success":false, "message":"invalid_invite"}

-> POST /chat/signup token=139... email=existing_email@example.com
<- 400 {"success":false, "message":"email_exists"}

# login UNAUTH POST

Request an authenticated session key.

• token - (str) auth-formtoken to prevent CSRF
• email - (str) account email address
• password - (str) account password
  Headers
• x-auth-formtoken - (str) same value as auth-formtoken in token postdata

-> POST /chat/login token=1397241172970.e07910a06a086c83ba41827aa00b26ed email=example@example.com password=correct_pass
<- {"success":true, "session":"e07910a06a086c83ba41827aa00b26ed", "uid":1}

Errors:

-> POST /chat/login token=bad_or_missing_token email=example@example.com password=pass
<- 401 {"success":false, "message":"invalid_form_token"}

-> POST /chat/login token=139... email=example@example.com password=wrong_pass
<- 401 {"success":false, "message":"auth"}

# request-password-reset UNAUTH POST

Request a password reset email.

• token - (str) auth-formtoken to prevent CSRF
• email - (str) account email address
  Headers
• x-auth-formtoken - (str) same value as auth-formtoken in token postdata

-> POST /chat/request-password-request token=1397241172970.e07910a06a086c83ba41827aa00b26ed email=example@example.com
<- {"success":true}

Errors:

-> POST /chat/login token=bad_or_missing_token email=example@example.com
<- 401 {"success":false, "message":"invalid_form_token"}

# heartbeat POST

Inform the server of unread/selected state. These values will be echoed to all stream clients as the heartbeat_echo message

• selectedBuffer - (int bid) last select buffer id
• seenEids - (str JSON map cid => bid => eid) maximum seen eid for a buffer. should only be set if it's changed since the last_seen_eid value in the makebuffer message

-> {"_reqid":1, "_method":"heartbeat", "selectedBuffer":2, "seenEids":"{\\"3\":{\\"4\\":1343825583263721}}"} 
<- {"_reqid":1, "success":true}

Errors:

-> {"_reqid":1, "_method":"heartbeat", "selectedBuffer":1, "seenEids":<invalid_json>} 
<- {"_reqid":1, "success":false, "message":"invalid_json"}

# say POST

Send a message to a buffer.

• cid - (int) connection id
• to - (str) buffer name (we don't use bid here because it could be a new buffer
• msg - (str) message text

If msg starts with a forward slash / it will be parsed as a special command which could change the response format. You should always be able to check for success: true though.

-> {"_reqid":1, "_method":"say", "cid":2, "to":"#channel", "msg":"hello world"} 
<- {"_reqid":1, "success":true, "type":"open_buffer", "cid":2, "name":"#channel"}

open_buffer mainly exists for the case where you send a pm to another user from a different channel with /msg their_nick message, in which case, the to request value and name response value will be different. In this case, the client should switch views to the buffer indicated by name. The stream should already have sent makebuffer by this point. This is one of the reasons WebSocket is preferred, as separate HTTPS requests may introduce some awkward synchronicity issues here.

Here's an example to illustrate, where a message is directed at the server console by using * as the to value.

-> {"_reqid":1, "_method":"say", "cid":2, "to":"*", "msg":"/msg friend hello world"} 
<- {"_reqid":1, "success":true, "type":"open_buffer", "cid":2, "name":"friend"}

If request: to and response: name are the same, as in the first example, then the correct buffer should already be selected, so the open_buffer directive can be ignored.

# user-settings POST

Save account settings. Not to be confused with set-prefs.

After a successful call to this method, the stream will receive a stat_user message with the updated values.

• email - (str) account email address. if this is changed the account will be marked as unverified.
• realname - (str) real name
• hwords - (str) highlight words, delimited by any white space or comma
• autoaway - (str bool) should we mark them away after they close their last session? set to the string "1" for true, anything else is false

-> {"_reqid":1, "_method":"user-settings", "email":"example@example.com", "realname":"Billy Keys", "hwords":"pub, lunch", "autoaway":"1"} 
<- {"_reqid":1, "success":true}

Errors:

-> {"_reqid":1, "_method":"user-settings", "email":"invalid_email"} 
<- {"_reqid":1, "success":false, "message":"email_invalid"}

-> {"_reqid":1, "_method":"user-settings", "email":"unavailable_email"} 
<- {"_reqid":1, "success":false, "message":"email_not_unique"}

# set-prefs POST

Store ad-hoc client preferences. Not to be confused with user-settings.

These are for preferences only used by the client and can contain any arbitrary JSON encoded key value. They correspond to prefs in the stat_user message.

IMPORTANT The full prefs object must be passed back with each call to this method to avoid wiping existing prefs. The value is stored in the database without processing.

• prefs - (str JSON) key value map of preferences

-> {"_reqid":1, "_method":"set-prefs", "prefs":"{\\"client-pref\\":\\"client-pref-value\\"}"} 
<- {"_reqid":1, "success":true}

Errors:

-> {"_reqid":1, "_method":"set-prefs"} 
<- {"_reqid":1, "success":false, "message":"missing_prefs_field"}

# resend-verify-email POST

Re-send a verification email for unverified accounts

-> {"_reqid":1, "_method":"resend-verify-email"} 
<- {"_reqid":1, "success":true}

# add-server POST

Add a new connection. On success, the stream will start receiving messages for the connection, starting with a makeserver message.

• hostname - (str) connection hostname
• port - (int) connection port
• ssl - (str bool) is this connection using ssl? set to the string "1" for true, anything else is false
• netname - (str) connection display name
• nickname - (str) nickname for this connection
• realname - (str) real name for this connection
• server_pass - (str) connection password
• nspass - (str) nickserv password in use on this connection
• joincommands - (str) IRC commands to execute on connect, delimited by new lines
• channels - (str) channels to join on connect, delimited by new lines or commas. separate channel names from channel keys with a space

TODO examples

# edit-server POST

Edit a connection's details. On successful edit, the stream will receive a server_details_changed message.

Note: The values are mostly the same as add-server with the addition of cid. Also channels isn't supported. Auto channels are edited by joining/parting them individually.

IMPORTANT All values must be sent with this call to avoid blanking them out.

• cid - (int) connection id
• hostname - (str) connection hostname
• port - (int) connection port
• ssl - (str bool) is this connection using ssl? set to the string "1" for true, anything else is false
• netname - (str) connection display name
• nickname - (str) nickname for this connection
• realname - (str) real name for this connection
• server_pass - (str) connection password
• nspass - (str) nickserv password in use on this connection
• joincommands - (str) IRC commands to execute on connect, delimited by new lines

TODO examples

# add-default-server POST

Add the default server connection, only nickname and realname and needed for this call, the other details are provided by the server. On success, the stream will start receiving messages for the connection, starting with a makeserver message.

• nickname - (str) nickname
• realname - (str) real name

TODO examples

# change-password POST

Change an account password.

• password - (str) current password. needed for extra security
• newpassword - (str) desired new password

TODO examples

# send-invite POST

Send an invite to one or more email addresses.

• emails - (str) list of email addresses to invite delimited by any white space or comma

TODO examples

# ignore POST

Add a usermask to the ignore list for a connection.

• cid - (int) connection id
• mask - (str) usermask to ignore

TODO examples

# unignore POST

Remove a usermask from the ignore list for a connection.

• cid - (int) connection id
• mask - (str) usermask to unignore

TODO examples

# set-ignores POST

Replace the ignore list for a connection.

• cid - (int) connection id
• ignores - (str JSON) list of usermasks

TODO examples

# nick POST

Change nick on a connection.

• cid - (int) connection id
• nick - (str) desired nickname

TODO examples

# delete-connection POST

Remove a connection permanently.

• cid - (int) connection id

TODO examples

# disconnect POST

Disconnect a connection.

• cid - (int) connection id
• msg - (str) quit message

TODO examples

# reconnect POST

Reconnect a connection.

• cid - (int) connection id

TODO examples

# ns-help-register POST

Request NickServ help pages. (the NickServ bot will respond with a series of notice messages if available).

• cid - (int) connection id

TODO examples

# set-nspass POST

Set NickServ password for a connection.

• cid - (int) connection id
• nspass - (str) nickserv password

TODO examples

# join POST

Join a channel (with an optional key).

• cid - (int) connection id
• channel - (str) channel name
• key - (str) [optional] channel key

TODO examples

# part POST

Leave a channel (with an optional message).

• cid - (int) connection id
• channel - (str) channel name
• msg - (str) part message

TODO examples

# topic POST

Update a channel topic.

• cid - (int) connection id
• channel - (str) channel name
• topic - (str) topic text

TODO examples

# unarchive-buffer POST

Unarchive a buffer.

• cid - (int) connection id
• id - (int) buffer id

TODO examples

# archive-buffer POST

Archive a buffer.

• cid - (int) connection id
• id - (int) buffer id

TODO examples

# delete-buffer POST

Remove a buffer permanently.

• cid - (int) connection id
• id - (int) buffer id

TODO examples

# whois POST

Request whois information for a nick. This will result in a whois_response message.

• cid - (int) connection id
• nick - (str) nickname to query
• server - (str) [optional] if the ircserver for this nick is know, provide it for more detailed results

TODO examples

# pastebins GET

List a page of text snippets.

• page - (int) page number

TODO examples

# paste POST

Create a text snippet.

• name - (str) [optional] snippet filename
• contents - (str) snippet text
• extension - (str) snippet file extension

TODO examples

# edit-pastebin POST

Edit a text snippet.

• id - (str) snippet id
• name - (str) [optional] snippet filename
• body - (str) snippet text
• extension - (str) snippet file extension

TODO examples

# delete-paste POST

Delete a text snippet.

• id - (str) snippet id

TODO examples