Linkd API DocumentationRelease 0.1
Eric Barch
May 01, 2013
CONTENTS
1 API 31.1 Auth Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Connection Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 IRC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Events 132.1 registered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2 motd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4 topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5 join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6 part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.7 quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.8 kick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.9 kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.10 message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.11 notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.12 nick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.13 pm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.14 invite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.15 +mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.16 -mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.17 whois . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.18 error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.19 channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.20 channel_details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3 Indices and tables 21
i
ii
Linkd API Documentation, Release 0.1
Contents:
CONTENTS 1
Linkd API Documentation, Release 0.1
2 CONTENTS
CHAPTER
ONE
API
1.1 Auth Commands
1.1.1 fb_auth
Authenticates with Linkd via Facebook token. If the user does not yet exist in the system, an account isautomatically generated. This is the first call that must be made to the API before any subsequent requests.
Example Request Payload:
{"token": "AAACEdEose0cBAIfGQIZAqjPN1gGMTdIvYyHGRbpOHqArQUKE1PAFZA5uy0FMn08ZAyRo1GHo83GV6FgD51yPWJslC7CxwDDO2s5sP8M5QZDZD"
}
Example Successful Response Payload:
{"success": true,"id": 835910294,"first_name": "Mop","last_name": "Squeegee"
}
Example Failed Response Payload:
{"success": false,"reason": "invalid_token"
}
Fail Reasons:
invalid_token: Facebook token could not be used to login or is malformedno_fb_token: A token was not included in the request payload
1.2 Connection Commands
1.2.1 create_connection
Creates a new IRC connection linked to the authenticated account.
Example Request Payload:
3
Linkd API Documentation, Release 0.1
{"label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"server_password": "","nickserv_password": "","nickserv_enabled": false,"real_name": "Skrillex, Bro"
}
Example Successful Response Payload:
{"success": true,"connId": "50d68a2b7bf23fc51f000001"
}
Fail Reasons:
not_authed: You must first authenticate with the APIinvalid_connection: Invalid details were provided for the connection
1.2.2 edit_connection
Edits an existing IRC connection linked to the authenticated account.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"server_password": "","nickserv_password": "","nickserv_enabled": false,"real_name": "Skrillex, Bro"
}
Example Successful Response Payload:
{"success": true,"connId": "50d68a2b7bf23fc51f000001"
}
Fail Reasons:
not_authed: You must first authenticate with the APIinvalid_connection: Invalid details were provided for the connection or the connection could not befound
4 Chapter 1. API
Linkd API Documentation, Release 0.1
1.2.3 remove_connection
Removes an existing IRC connection linked to the authenticated account.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001"
}
Example Successful Response Payload:
{"success": true,"connId": "50d68a2b7bf23fc51f000001"
}
Fail Reasons:
not_authed: You must first authenticate with the APIinvalid_connection: The connection could not be found
1.2.4 connection_go_online
Requests that an IRC connection be brought online.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001"
}
Example Successful Response Payload:
{"success": true,"connId": "50d68a2b7bf23fc51f000001"
}
Fail Reasons:
not_authed: You must first authenticate with the APIinvalid_connection: The connection could not be found
1.2.5 connection_go_offline
Requests that an IRC connection be brought offline (and disabled).
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001"
}
Example Successful Response Payload:
1.2. Connection Commands 5
Linkd API Documentation, Release 0.1
{"success": true,"connId": "50d68a2b7bf23fc51f000001"
}
Fail Reasons:
not_authed: You must first authenticate with the APIinvalid_connection: The connection could not be found
1.2.6 get_all_connections
Returns the connection details of all connections linked to this account.
Example Request Payload:
{}
Example Successful Response Payload:
{"success": true,"connections": [
{"connId": "50d68a2b7bf23fc51f000001","label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"online": true,"away": "Being chased by some scary monsters and nice sprites","server_password": "","nickserv_password": "","nickserv_enabled": false,"sasl_enabled": false,"real_name": "Skrillex, Bro","channels": [{"name":"#dubstep","chanserv_enabled": false,"chanserv_password": ""
},{"name":"#hipsters","chanserv_enabled": false,"chanserv_password": ""
},{"name":"#bacon","chanserv_enabled": false,"chanserv_password": ""
}],"creation": 1356237355929,"disabled": false,"disabled_timeout": 1356237355929,"disabled_reason": "User initiated.",
6 Chapter 1. API
Linkd API Documentation, Release 0.1
"online": false}
]}
Fail Reasons:
not_authed: You must first authenticate with the APIserver_error: Something went horribly wrong, ABORT
1.3 IRC Commands
1.3.1 join
Join an IRC channel. Any join errors will be received as events rather than a direct callback. If the joinwas successful, Linkd will add this channel to the user’s channel list.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#lolcats"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.2 part
Part an IRC channel. Any part errors will be received as events rather than a direct callback. If the partwas successful, Linkd will remove this channel from the user’s channel list.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#lolcats"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3. IRC Commands 7
Linkd API Documentation, Release 0.1
1.3.3 say
Send a message to a user or channel. Any say errors will be received as events rather than a direct callback.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","text": "omg cats"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.4 action
Perform an action in a channel or private message. Any action errors will be received as events rather thana direct callback.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","text": "hugs cats"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.5 whois
Request a whois of a user. Whois data will be returned as another event if successful.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","to": "thatonecreepydude",
}
Example Successful Response Payload:
8 Chapter 1. API
Linkd API Documentation, Release 0.1
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.6 topic
Change the topic of a channel. Any topic errors will be received as events rather than a direct callback.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","topic": "LOLCATS: the other, other white meat"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.7 nick
Change your nick. Any nick errors will be received as events rather than a direct callback.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","nick": "theNEWguy"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3. IRC Commands 9
Linkd API Documentation, Release 0.1
1.3.8 command
Send a raw IRC command. Any command errors will be received as events rather than a direct callback.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","command": "PRIVMSG","args": "#irchacks :Hello everybody!"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.9 get_log
Get the transcripts (backlog) for a particular channel. Currently returns up to 200 messages.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#lava",
}
Example Successful Response Payload:
{"success": true,"log": [
{"ts":1356237355929,"from":"thedude","text":"what’s up guys"
},{
"ts":1356237355933,"from":"theotherdude","text":"not much bro"
}]
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
10 Chapter 1. API
Linkd API Documentation, Release 0.1
1.3.10 get_private_messages
Get all recent private messages.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","markRead": true
}
Example Successful Response Payload:
{"success": true,"messages": [
{"ts":1356237355966,"from":"thedude","text":"omg you need to reply to me ASAP"
},{
"ts":1356237355980,"from":"theotherdude","text":"i miss you, bro"
}]
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.11 get_channels
Get all channels that are currently joined in this IRC session.
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
1.3.12 get_channel_details
Get all channel details (topic, mode, userlist) for a joined channel.
1.3. IRC Commands 11
Linkd API Documentation, Release 0.1
Example Request Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats"
}
Example Successful Response Payload:
{"success": true
}
Fail Reasons:
not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection
12 Chapter 1. API
CHAPTER
TWO
EVENTS
2.1 registered
Emitted when the server sends the initial 001 line, indicating you’ve connected to the IRC server.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","message": "REG MESSAGE FROM SERVER"
}
Fields:
connId: The ID of the IRC connectionmessage: The registered message from the server
2.2 motd
Emitted when the server sends the message of the day to clients.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","motd": "SERVER MOTD"
}
Fields:
connId: The ID of the IRC connectionmotd: The server’s motd
2.3 names
Emitted when the server sends a list of nicks for a channel (which happens immediately after joining andon request. The nicks object passed to the callback is keyed by nick names, and has values ‘’, ‘+’, or ‘@’depending on the level of that nick in the channel.
Event Payload:
13
Linkd API Documentation, Release 0.1
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","nicks":{
"someone": "@","someoneelse": ""
}}
Fields:
connId: The ID of the IRC connectionchannel: The channel of this userlistnicks: dict of usernames and their privilege level on the channel
2.4 topic
Emitted when the server sends the channel topic on joining a channel, or when a user changes the topicon a channel.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","topic": "omg cats!","nick": "somedude"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel of this topictopic: The topic of the channelnick: Who set the topic
2.5 join
Emitted when a user joins a channel (including when the client itself joins a channel).
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "cats","nick": "thatcatguy"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel that a user joinednick: The nick of the user that joined the channel
14 Chapter 2. Events
Linkd API Documentation, Release 0.1
2.6 part
As per ‘join’ event but only emits for the subscribed channel.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "cats","nick": "thatcatguy","reason": "off to the cat store"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel that a user joinednick: The nick of the user that joined the channelreason: The reason for parting the channel
2.7 quit
Emitted when a user disconnects from the IRC, leaving the specified array of channels.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","nick": "thatcatguy","reason": "too many cats""channels":
["#cats","#moarcats"
]}
Fields:
connId: The ID of the IRC connectionnick: The nick of the user that quitreason: The reason the user has quitchannels: Array of channels the user was in
2.8 kick
Emitted when a user is kicked from a channel.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats""nick": "verydesperate""by": "justheretomod"
2.6. part 15
Linkd API Documentation, Release 0.1
"reason": "not as desperate as you’d think"}
Fields:
connId: The ID of the IRC connectionchannel: The channel the user was kicked fromnick: The nick of the user that was kickedby: Who kicked this userreason: Why the user was kicked
2.9 kill
Emitted when a user is killed from the IRC server. channels is an array of channels the killed user was inwhich are known to the client.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","nick": "lollerskatesmcgee","reason": "i don’t like you","channels":
["#cats","#moarcats"
]}
Fields:
connId: The ID of the IRC connectionnick: The nick of the user that was killedreason: The reason the user was killedchannnels: Array of channels the user was killed from
2.10 message
Emitted when a message is sent to any channel.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","from": "lollerskatesmcgee","to": "#bacon","text": "omg bacon! i’m you’re biggest fan"
}
Fields:
connId: The ID of the IRC connectionfrom: The nick of the user that sent the messageto: The target channel this message was sent to
16 Chapter 2. Events
Linkd API Documentation, Release 0.1
text: The body of the message
2.11 notice
Emitted when a notice is sent. to can be either a nick (which is most likely this clients nick and means aprivate message), or a channel (which means a message to that channel). nick is either the senders nick ornull which means that the notice comes from the server.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","nick": "freeipods","to": "omgme32","text": "yo dawg...i heard you like affordable and legitimate goods",
}
Fields:
connId: The ID of the IRC connectionnick: The nick of the user, channel name, or null (from server) that has sent this noticeto: Who the notice was sent totext: The text of the notice
2.12 nick
Emitted when a user changes nick along with the channels the user is in.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","oldNick": "probablynotadude","newNick": "definitelynotadude","channels":
["#cats","#moarcats","#casual"
]}
Fields:
connId: The ID of the IRC connectionoldNick: The user’s old nicknewNick: The user’s new nickchannels: Array of channels the user is in (that we know of)
2.13 pm
As per ‘message’ event but only emits when the message is direct to the client.
2.11. notice 17
Linkd API Documentation, Release 0.1
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","nick": "lolskrillex","text": "yo bro you hear my new album"
}
Fields:
connId: The ID of the IRC connectionnick: The nick of the user sending the PMtext: The body of the message
2.14 invite
Emitted when the client recieves an /invite.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#thebeach","from": "definitelynotadude"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel this client has been invited tofrom: Who is sending the invite
2.15 +mode
Emitted when a mode is added to a user or channel. channel is the channel which the mode is being seton/in. by is the user setting the mode. mode is the single character mode indentifier. If the mode is beingset on a user, argument is the nick of the user. If the mode is being set on a channel, argument is theargument to the mode. If a channel mode doesn’t have any arguments, argument will be ‘undefined’.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","by": "oneOPtoRULE","mode": "v","argument": "currentlyMUTE"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel the event has occurred inby: Who has set the modemode: The mode being set
18 Chapter 2. Events
Linkd API Documentation, Release 0.1
argument: As per description: nick, channel, or undefined
2.16 -mode
Emitted when a mode is removed from a user or channel. channel is the channel which the mode is beingset on/in. by is the user setting the mode. mode is the single character mode indentifier. If the mode isbeing set on a user, argument is the nick of the user. If the mode is being set on a channel, argument is theargument to the mode. If a channel mode doesn’t have any arguments, argument will be ‘undefined’.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","by": "oneOPtoRULE","mode": "v","argument": "currentlyMUTE"
}
Fields:
connId: The ID of the IRC connectionchannel: The channel the event has occurred inby: Who has set the modemode: The mode being setargument: As per description: nick, channel, or undefined
2.17 whois
Emitted whenever the server finishes outputting a WHOIS response.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","info":{
nick: "Ned",user: "martyn",host: "10.0.0.18",realname: "Unknown",channels: ["@#purpledishwashers", "#blah", "#mmmmbacon"],server: "*.dollyfish.net.nz",serverinfo: "The Dollyfish Underworld",operator: "is an IRC Operator"
}}
Fields:
connId: The ID of the IRC connectioninfo: Whois data being returned
2.16. -mode 19
Linkd API Documentation, Release 0.1
2.18 error
Emitted when ever the server responds with an error-type message.
Event Payload:
{"connId": "50d68a2b7bf23fc51f000001","message": "Server Error: Not Enough Love"
}
Fields:
connId: The ID of the IRC connectionmessage: The raw message from the server
2.19 channels
Emitted when ever the server responds with an error-type message.
Event Payload:
{"channels": ["#cats", "#omgcats", "#soomanycats"]
}
Fields:
channels: Array of all channels that this IRC session is joined to
2.20 channel_details
Emitted when ever the server responds with channel details for a particular channel
Event Payload:
{"channel": "#cats","topic": "cats :: pretty cool, eh?","topic_by": "thatcatguy","modes": ["p"],"userlist": {"someguy": "vo", "someotherguy": "v"}
}
Fields:
channel: The channel that details are being returned fortopic: The topic of this channeltopic_by: Who set the topicmodes: The modes currently set on this channeluserlist: All of the users in this channel and their corresponding modes
20 Chapter 2. Events
CHAPTER
THREE
INDICES AND TABLES
• genindex
• modindex
• search
21