Convos API specification

About

This document describes the API for Convos, a multiuser persistent IRC proxy with web interface.

Terms of service

SSL (HTTPS) is highly suggested, since login credentials and session cookies are transmitted over this API.

Resources

checkForUpdates

GET /api/check-for-updates
Operation ID: checkForUpdates

Check if a new update is available

Parameters

This resource has no input parameters.

Response 200

Version information

{"properties":{"available":{"type":"number"},"running":{"type":"number"}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

connectionMessages

GET /api/connection/{connection_id}/messages
Operation ID: connectionMessages

Get a list of messages. Note: this resource require the user to be authenticated first.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier
after	query	string	No	Find messages after a given ISO 8601 timestamp
around	query	string	No	Find messages around a given ISO 8601 timestamp
before	query	string	No	Find messages before a given ISO 8601 timestamp
limit	query	integer	No	Max number of messages to retrieve
match	query	string	No	Messages must match this string

Response 200

List of messages.

{"properties":{"after":{"format":"date-time","type":"string"},"before":{"format":"date-time","type":"string"},"messages":{"items":{"$ref":"#\/definitions\/Message"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

conversationMessages

GET /api/connection/{connection_id}/conversation/{conversation_id}/messages
Operation ID: conversationMessages

Get a list of messages. Note: this resource require the user to be authenticated first.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier
conversation_id	path	string	Yes	The name of the person or room
after	query	string	No	Find messages after a given ISO 8601 timestamp
around	query	string	No	Find messages around a given ISO 8601 timestamp
before	query	string	No	Find messages before a given ISO 8601 timestamp
limit	query	integer	No	Max number of messages to retrieve
match	query	string	No	Messages must match this string

Response 200

List of messages.

{"properties":{"after":{"format":"date-time","type":"string"},"before":{"format":"date-time","type":"string"},"messages":{"items":{"$ref":"#\/definitions\/Message"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

createConnection

POST /api/connections
Operation ID: createConnection

Add a connection.

Parameters

Name	In	Type	Required	Description
body	body	object	Yes

Body

{"properties":{"conversation_id":{"description":"Example: #convos","type":"string"},"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"}},"url":{"description":"Example: irc:\/\/user:[email protected]?nick=superman","type":"string"},"wanted_state":{"description":"Connection state","enum":["connected","disconnected"],"type":"string"}},"required":["url"],"type":"object"}

Response 200

Connection information.

{"$ref":"#\/definitions\/Connection"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

deleteFiles

DELETE /api/files/{uid}/{fid}
Operation ID: deleteFiles

Delete one (or more) uploaded file.

Parameters

Name	In	Type	Required	Description
fid	path	string	Yes
uid	path	string	Yes

Response 200

Successfully deleted.

{"properties":{"deleted":{"type":"integer"}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

deleteUser

DELETE /api/user/{email}
Operation ID: deleteUser

Delete a user.

Parameters

Name	In	Type	Required	Description
email	path	string	Yes	User email

Response 200

Successfully deleted.

{"$ref":"#\/definitions\/Success"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

embed

GET /api/embed
Operation ID: embed

Get information from a URL

Parameters

Name	In	Type	Required	Description
url	query	string	Yes	URL to resource

Response 200

Information about resource.

null

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getDictionary

GET /api/i18n/{lang}
Operation ID: getDictionary

Retrieve translations.

Parameters

Name	In	Type	Required	Description
lang	path	string	Yes

Response 200

Dictionary.

{"properties":{"dictionary":{"type":"object"}},"required":["dictionary"],"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getFile

GET /api/files/{uid}/{fid}
Operation ID: getFile

Retrieve uploaded file.

Parameters

Name	In	Type	Required	Description
fid	path	string	Yes
uid	path	string	Yes

Response 200

File found and served.

{"type":"string"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getFiles

GET /api/files
Operation ID: getFiles

Retrieve list of uploaded files.

Parameters

Name	In	Type	Required	Description
after	query	string	No	Find files after a file ID, can be "after", "prev" or the last file ID from the response
limit	query	integer	No	Max number of files to retrieve

Response 200

Files found

{"properties":{"after":{"description":"Can be used as \"after\" query param to get the current page","type":"string"},"files":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"saved":{"format":"date-time","type":"string"},"size":{"type":"integer"}},"required":["id","name","saved","size"],"type":"object"},"type":"array"},"next":{"description":"Indicates if there is a next page","type":"string"},"prev":{"description":"Can be used as \"after\" query param to go to the previous page","type":"string"}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getSettings

GET /api/settings
Operation ID: getSettings

Get settings for Convos.

Parameters

This resource has no input parameters.

Response 200

ServerSettings.

{"$ref":"#\/definitions\/ServerSettings"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getUser

GET /api/user
Operation ID: getUser

Get user data.

Parameters

Name	In	Type	Required	Description
connections	query	boolean	No	Retrieve connection list.
conversations	query	boolean	No	Retrieve conversation list.

Response 200

User profile.

{"$ref":"#\/definitions\/User"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

getUsers

GET /api/users
Operation ID: getUsers

List Convos users

Parameters

Name	In	Type	Required	Description
after	query	string	No	Find users after in pagination

Response 200

List of users.

{"properties":{"users":{"items":{"$ref":"#\/definitions\/User"},"type":"array"}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

inviteUser

POST /api/user/{email}/invite
Operation ID: inviteUser

Generate invite link for an existing / new user.

Parameters

Name	In	Type	Required	Description
email	path	string	Yes	User email

Response 200

User profile.

{"properties":{"existing":{"type":"boolean"},"expires":{"format":"date-time","type":"string"},"url":{"type":"string"}},"required":["url"],"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

listConnectionProfiles

GET /api/connection-profiles
Operation ID: listConnectionProfiles

List all connection profiles.

Parameters

This resource has no input parameters.

Response 200

List of profiles.

{"properties":{"profiles":{"items":{"$ref":"#\/definitions\/ConnectionProfile"},"type":"array"}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

listConnections

GET /api/connections
Operation ID: listConnections

Get all the connections for a user.

Parameters

This resource has no input parameters.

Response 200

List of connections.

{"properties":{"connections":{"items":{"$ref":"#\/definitions\/Connection"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

listConversations

GET /api/conversations
Operation ID: listConversations

Get a list of all conversations.

Parameters

This resource has no input parameters.

Response 200

List of conversations.

{"properties":{"conversations":{"items":{"$ref":"#\/definitions\/Conversation"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

POST /api/user/login
Operation ID: loginUser

Parameters

Name	In	Type	Required	Description
body	body	object	Yes

Body

{"properties":{"email":{"description":"User email","format":"email","type":"string"},"password":{"description":"User password","type":"string"}},"required":["email","password"],"type":"object"}

Response 200

User profile.

{"$ref":"#\/definitions\/User"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

logoutUser

GET /api/user/logout
Operation ID: logoutUser

Logout a user.

This resource will delete any sessions cookies that might be stored in the client.

Parameters

Name	In	Type	Required	Description
csrf	query	string	Yes

Response 302

Successfully logged out.

null

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

markConnectionAsRead

POST /api/connection/{connection_id}/read
Operation ID: markConnectionAsRead

Clears unread for a connection.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier

Response 200

Successful response.

{"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

markConversationAsRead

POST /api/connection/{connection_id}/conversation/{conversation_id}/read
Operation ID: markConversationAsRead

Clears unread for a conversation.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier
conversation_id	path	string	Yes	The name of the person or room

Response 200

Successful response.

{"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

markNotificationsAsRead

POST /api/notifications/read
Operation ID: markNotificationsAsRead

Mark notications as read.

Parameters

This resource has no input parameters.

Response 200

Successful response.

{"properties":{},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

notificationMessages

GET /api/notifications
Operation ID: notificationMessages

Get list of notications.

A notification is added once your name is mentioned in a chat.

Parameters

This resource has no input parameters.

Response 200

List of notifications.

{"properties":{"messages":{"items":{"$ref":"#\/definitions\/Notification"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

registerUser

POST /api/user/register
Operation ID: registerUser

Parameters

Name	In	Type	Required	Description
body	body	object	Yes

Body

{"properties":{"email":{"description":"User email","format":"email","type":"string"},"exp":{"description":"Expire time for a token","type":"string"},"password":{"$ref":"#\/definitions\/Password"},"token":{"description":"Checksum generated by inviteUser","type":"string"}},"required":["email","password"],"type":"object"}

Response 200

User profile.

{"$ref":"#\/definitions\/User"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

removeConnection

DELETE /api/connection/{connection_id}
Operation ID: removeConnection

Delete a connection and all assosiated data.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier

Response 200

Remove a connection.

{"$ref":"#\/definitions\/Success"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

removeConnectionProfile

DELETE /api/connection-profiles/{id}
Operation ID: removeConnectionProfile

Remove a connection profile.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	A unique profile identifier

Response 200

Success.

{"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

saveConnectionProfile

POST /api/connection-profiles
Operation ID: saveConnectionProfile

Update or create a profile.

Parameters

Name	In	Type	Required	Description
body	body		Yes

Body

{"$ref":"#\/definitions\/ConnectionProfile"}

Response 200

Success.

{"$ref":"#\/definitions\/ConnectionProfile"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

searchMessages

GET /api/search
Operation ID: searchMessages

Search for historic messages.

Parameters

Name	In	Type	Required	Description
connection_id	query	string	No	An ID for a connection
conversation_id	query	string	No	An ID for a conversation
after	query	string	No	Find messages after a given ISO 8601 timestamp
before	query	string	No	Find messages before a given ISO 8601 timestamp
from	query	string	No	Sender must match this string
limit	query	integer	No	Max number of messages to retrieve
match	query	string	No	Messages must match this string

Response 200

List of messages.

{"properties":{"after":{"format":"date-time","type":"string"},"before":{"format":"date-time","type":"string"},"messages":{"items":{"$ref":"#\/definitions\/Message"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

updateConnection

POST /api/connection/{connection_id}
Operation ID: updateConnection

Update a connection.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	Yes	A unique connection identifier
body	body	object	Yes

Body

{"properties":{"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"}},"url":{"description":"Example: irc:\/\/user:[email protected]?nick=superman","format":"uri","type":"string"},"wanted_state":{"description":"Connection state","enum":["connected","disconnected"],"type":"string"}},"type":"object"}

Response 200

Update a connection.

{"$ref":"#\/definitions\/Connection"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

updateSettings

POST /api/settings
Operation ID: updateSettings

Update settings for Convos.

Parameters

Name	In	Type	Required	Description
body	body		Yes

Body

{"$ref":"#\/definitions\/ServerSettings"}

Response 200

User profile.

{"$ref":"#\/definitions\/ServerSettings"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

updateUser

POST /api/user/{email}
Operation ID: updateUser

Update an existing user.

Parameters

Name	In	Type	Required	Description
email	path	string	Yes	User email
body	body	object	Yes

Body

{"properties":{"highlight_keywords":{"description":"Extra keywords to highlight on","items":{"type":"string"}},"password":{"$ref":"#\/definitions\/Password"},"roles":{"description":"User roles, such as admin and bot.","items":{"type":"string"},"type":"array"}},"type":"object"}

Response 200

User profile.

{"$ref":"#\/definitions\/User"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

uploadFile

POST /api/files
Operation ID: uploadFile

Upload file.

Parameters

Name	In	Type	Required
file	formData	file	Yes
id	formData	string	No
write_only	formData	boolean	No

Response 200

Successfully uploaded.

{"properties":{"files":{"items":{"properties":{"ext":{"type":"string"},"filename":{"type":"string"},"id":{"type":"string"},"saved":{"format":"date-time","type":"string"},"uid":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["ext","filename","id","saved","uid","url"],"type":"object"}}},"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

webhook

POST /api/webhook/{provider_name}
Operation ID: webhook

Forwards the webhook payload to the Convos bot

Parameters

Name	In	Type	Required	Description
provider_name	path	string	Yes	Provider name
body	body	object	Yes	Any webhook payload

Body

{"type":"object"}

Response 200

Webhook response

{"type":"object"}

Response 400

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.

{"$ref":"#\/definitions\/DefaultResponse"}

Parameters

after

{"description":"Find messages after a given ISO 8601 timestamp","format":"date-time","in":"query","name":"after","type":"string"}

around

{"description":"Find messages around a given ISO 8601 timestamp","format":"date-time","in":"query","name":"around","type":"string"}

before

{"description":"Find messages before a given ISO 8601 timestamp","format":"date-time","in":"query","name":"before","type":"string"}

connection_id

{"description":"A unique connection identifier","in":"path","name":"connection_id","required":true,"type":"string"}

conversation_id

{"default":"","description":"The name of the person or room","in":"path","name":"conversation_id","required":true,"type":"string","x-mojo-placeholder":"#"}

email_in_path

{"description":"User email","format":"email","in":"path","name":"email","required":true,"type":"string","x-mojo-placeholder":"#"}

ident

{"description":"User email or server identity","in":"path","name":"ident","required":true,"type":"string"}

Definitions

Connection

{"properties":{"connection_id":{"description":"Unique identifier for this connection","type":"string"},"info":{"description":"Extra information about the connection","type":"object"},"name":{"description":"Name for this connection","type":"string"},"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"}},"state":{"description":"Actual connection state","enum":["connected","connecting","disconnected","disconnecting","queued"],"type":"string"},"url":{"description":"Example: irc:\/\/user:@irc.perl.org?nick=superman (Note: Without password)","format":"uri","type":"string"},"wanted_state":{"description":"Wanted connection state","enum":["connected","disconnected"],"type":"string"}},"required":["connection_id","url"],"type":"object"}

ConnectionProfile

{"properties":{"is_default":{"type":"boolean"},"is_forced":{"type":"boolean"},"max_bulk_message_size":{"maximum":32,"minimum":1,"type":"integer"},"max_message_length":{"maximum":2048,"minimum":32,"type":"integer"},"service_accounts":{"items":{"type":"string"},"type":"array"},"url":{"format":"uri","type":"string"},"webirc_password":{"type":"string"}},"required":["url"],"type":"object"}

Conversation

{"properties":{"connection_id":{"description":"Unique identifier for the connection this conversation is part of","type":"string"},"conversation_id":{"description":"Unique identifier for the conversation","type":"string"},"name":{"description":"Name of the room or person","type":"string"},"topic":{"description":"The subjec\/topic for this room","type":"string"},"unread":{"description":"Number of unread messages","type":"integer"}},"required":["connection_id","conversation_id","name","unread"],"type":"object"}

DefaultResponse

{"properties":{"errors":{"items":{"properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"type":"object"},"type":"array"}},"required":["errors"],"type":"object"}

Message

{"properties":{"from":{"description":"Identifier for who sent this message","type":"string"},"message":{"description":"The message","type":"string"},"ts":{"description":"Example: 2015-09-06T13:49:37Z","format":"date-time","type":"string"}},"required":["message","from","ts"],"type":"object"}

Notification

{"properties":{"connection_id":{"description":"Unique identifier for the connection this notification came from","type":"string"},"conversation_id":{"description":"Conversation ID","type":"string"},"from":{"description":"Identifier for who sent this message","type":"string"},"message":{"description":"The message","type":"string"},"ts":{"description":"Example: 2015-09-06T13:49:37Z","format":"date-time","type":"string"}},"required":["message","from","ts"],"type":"object"}

Password

{"description":"User password","minLength":10,"type":"string"}

ServerSettings

{"properties":{"contact":{"minLength":3,"type":"string"},"default_connection":{"format":"uri","type":"string"},"disk_usage":{"properties":{"block_size":{"type":"integer"},"blocks_free":{"type":"integer"},"blocks_total":{"type":"integer"},"blocks_used":{"type":"integer"},"inodes_free":{"type":"integer"},"inodes_total":{"type":"integer"},"inodes_used":{"type":"integer"}},"type":"object"},"forced_connection":{"type":"boolean"},"open_to_public":{"type":"boolean"},"organization_name":{"type":"string"},"organization_url":{"type":"string"},"video_service":{"type":"string"}},"type":"object"}

Success

{"properties":{"message":{"description":"Human readable description","type":"string"}},"type":"object"}

User

{"properties":{"connections":{"items":{"$ref":"#\/definitions\/Connection"}},"conversations":{"items":{"$ref":"#\/definitions\/Conversation"}},"default_connection":{"readOnly":true,"type":"string"},"email":{"description":"Unique email identifying a user in Convos","type":"string"},"forced_connection":{"readOnly":true,"type":"boolean"},"highlight_keywords":{"description":"Extra keywords to highlight on","items":{"type":"string"}},"registered":{"description":"Example: 2015-09-06T10:47:31Z","format":"date-time","type":"string"},"uid":{"type":"string"},"unread":{"description":"Number of unread notifications","type":"integer"},"video_service":{"type":"string"}},"required":["email","unread"],"type":"object"}