API RPC 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 protected]&comments=Currently%20using%20irssi,%20want%20a%20web%20version
<- {"success":true, "email":"[email protected]"}

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 protected]&password=password1&realname=Joe%20Bloggs
<- {"success":true, "session":"e07910a06a086c83ba41827aa00b26ed", "uid":1}

Errors:

-> POST /chat/login token=bad_or_missing_token [email protected]&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 protected]
<- 400 {"success":false, "message":"password"}

-> POST /chat/signup token=139... [email protected]&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 protected]
<- 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 protected] password=correct_pass
<- {"success":true, "session":"e07910a06a086c83ba41827aa00b26ed", "uid":1}

Errors:

-> POST /chat/login token=bad_or_missing_token [email protected] password=pass
<- 401 {"success":false, "message":"invalid_form_token"}

-> POST /chat/login token=139... [email protected] 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 protected]
<- {"success":true}

Errors:

-> POST /chat/login token=bad_or_missing_token [email protected]
<- 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":"[email protected]", "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

API RPC Reference

RPC Calls

WebSocket

HTTPS

GET / UNAUTH POST

Authenticated POST

General Errors

# plans GET

# backlog GET

# request-invite UNAUTH POST

# auth-formtoken UNAUTH POST

# signup UNAUTH POST

# login UNAUTH POST

# request-password-reset UNAUTH POST

# heartbeat POST

# say POST

# user-settings POST

# set-prefs POST

# resend-verify-email POST

# add-server POST

# edit-server POST

# add-default-server POST

# change-password POST

# send-invite POST

# ignore POST

# unignore POST

# set-ignores POST

# nick POST

# delete-connection POST

# disconnect POST

# reconnect POST

# ns-help-register POST

# set-nspass POST

# join POST

# part POST

# topic POST

# unarchive-buffer POST

# archive-buffer POST

# delete-buffer POST

# whois POST

# pastebins GET

# paste POST

# edit-pastebin POST

# delete-paste POST

Clone this wiki locally

# `plans` GET

# `backlog` GET

# `request-invite` UNAUTH POST

# `auth-formtoken` UNAUTH POST

# `signup` UNAUTH POST

# `login` UNAUTH POST

# `request-password-reset` UNAUTH POST

# `heartbeat` POST

# `say` POST

# `user-settings` POST

# `set-prefs` POST

# `resend-verify-email` POST

# `add-server` POST

# `edit-server` POST

# `add-default-server` POST

# `change-password` POST

# `send-invite` POST

# `ignore` POST

# `unignore` POST

# `set-ignores` POST

# `nick` POST

# `delete-connection` POST

# `disconnect` POST

# `reconnect` POST

# `ns-help-register` POST

# `set-nspass` POST

# `join` POST

# `part` POST

# `topic` POST

# `unarchive-buffer` POST

# `archive-buffer` POST

# `delete-buffer` POST

# `whois` POST

# `pastebins` GET

# `paste` POST

# `edit-pastebin` POST

# `delete-paste` POST