convos-api.yaml

---
swagger: '2.0'
info:
  title: Convos API specification
  version: 8.7.0
  description: This document describes the API for Convos, a multiuser persistent IRC proxy with web interface.
  contact:
    name: Convos
    url: https://github.com/convos-chat/convos
  license:
    name: Artistic License version 2.0
    url: http://opensource.org/licenses/Artistic-2.0
  termsOfService: SSL (HTTPS) is highly suggested, since login credentials and session cookies are transmitted over this API.

host: convos.chat
basePath: /api
schemes: [ http ]

consumes: [ 'application/json' ]
produces: [ 'application/json' ]

paths:
  /check-for-updates:
    get:
      operationId: checkForUpdates
      summary: Check if a new update is available
      x-mojo-to: url#check_for_updates
      responses:
        '200':
          description: Version information
          schema:
            type: object
            properties:
              available:
                type: number
              running:
                type: number

  /connection/{connection_id}:
    delete:
      operationId: removeConnection
      summary: Delete a connection and all assosiated data.
      tags: [ connection ]
      x-mojo-to: connection#remove
      parameters:
      - $ref: '#/parameters/connection_id'
      responses:
        '200':
          description: Remove a connection.
          schema:
            $ref: '#/definitions/Success'
    post:
      operationId: updateConnection
      summary: Update a connection.
      tags: [ connection ]
      x-mojo-to: connection#update
      parameters:
      - $ref: '#/parameters/connection_id'
      - in: body
        name: body
        required: true
        schema:
          type: object
          properties:
            on_connect_commands:
              description: Commands to be run after the connection is established
              items:
                type: string
            url:
              description: 'Example: irc://user:pass@irc.perl.org?nick=superman'
              format: uri
              type: string
            wanted_state:
              description: Connection state
              enum: [ connected, disconnected ]
              type: string
      responses:
        '200':
          description: Update a connection.
          schema:
            $ref: '#/definitions/Connection'

  /connection/{connection_id}/conversation/{conversation_id}/messages:
    get:
      operationId: conversationMessages
      summary: 'Get a list of messages. Note: this resource require the user to be authenticated first.'
      tags: [ conversation ]
      x-mojo-to: conversation#messages
      parameters:
      - $ref: '#/parameters/connection_id'
      - $ref: '#/parameters/conversation_id'
      - $ref: '#/parameters/after'
      - $ref: '#/parameters/around'
      - $ref: '#/parameters/before'
      - description: Max number of messages to retrieve
        in: query
        name: limit
        type: integer
      - description: Messages must match this string
        in: query
        name: match
        type: string
      responses:
        '200':
          description: List of messages.
          schema:
            type: object
            properties:
              after:
                type: string
                format: date-time
              before:
                type: string
                format: date-time
              messages:
                items:
                  $ref: '#/definitions/Message'

  /connection/{connection_id}/conversation/{conversation_id}/read:
    post:
      operationId: markConversationAsRead
      summary: Clears unread for a conversation.
      tags: [ conversation ]
      x-mojo-to: conversation#mark_as_read
      parameters:
      - $ref: '#/parameters/connection_id'
      - $ref: '#/parameters/conversation_id'
      responses:
        '200':
          description: Successful response.
          schema:
            type: object

  /connection/{connection_id}/messages:
    get:
      operationId: connectionMessages
      summary: 'Get a list of messages. Note: this resource require the user to be authenticated first.'
      tags: [ conversation ]
      x-mojo-to: conversation#messages
      parameters:
      - $ref: '#/parameters/connection_id'
      - $ref: '#/parameters/after'
      - $ref: '#/parameters/around'
      - $ref: '#/parameters/before'
      - description: Max number of messages to retrieve
        in: query
        name: limit
        type: integer
      - description: Messages must match this string
        in: query
        name: match
        type: string
      responses:
        '200':
          description: List of messages.
          schema:
            type: object
            properties:
              after:
                type: string
                format: date-time
              before:
                type: string
                format: date-time
              messages:
                items:
                  $ref: '#/definitions/Message'

  /connection/{connection_id}/read:
    post:
      operationId: markConnectionAsRead
      summary: Clears unread for a connection.
      tags: [ connection ]
      x-mojo-to: conversation#mark_as_read
      parameters:
      - $ref: '#/parameters/connection_id'
      responses:
        '200':
          description: Successful response.
          schema:
            type: object

  /connections:
    get:
      operationId: listConnections
      summary: Get all the connections for a user.
      tags: [ connection ]
      x-mojo-to: connection#list
      responses:
        '200':
          description: List of connections.
          schema:
            type: object
            properties:
              connections:
                items:
                  $ref: '#/definitions/Connection'
    post:
      operationId: createConnection
      summary: Add a connection.
      tags: [ connection ]
      x-mojo-to: connection#create
      parameters:
      - in: body
        name: body
        required: true
        schema:
          required: [ url ]
          type: object
          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:pass@irc.perl.org?nick=superman'
              type: string
            wanted_state:
              description: Connection state
              enum: [ connected, disconnected ]
              type: string
      responses:
        '200':
          description: Connection information.
          schema:
            $ref: '#/definitions/Connection'

  /connection-profiles:
    get:
      operationId: listConnectionProfiles
      summary: List all connection profiles.
      tags: [ connection, connection-profile ]
      x-mojo-to: connection_profile#list
      responses:
        '200':
          description: List of profiles.
          schema:
            type: object
            properties:
              profiles:
                type: array
                items:
                  $ref: '#/definitions/ConnectionProfile'
    post:
      operationId: saveConnectionProfile
      summary: Update or create a profile.
      tags: [ connection, connection-profile ]
      x-mojo-to: connection_profile#save
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/ConnectionProfile'
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/ConnectionProfile'

  /connection-profiles/{id}:
    delete:
      operationId: removeConnectionProfile
      summary: Remove a connection profile.
      tags: [ connection, connection-profile ]
      x-mojo-to: connection_profile#remove
      parameters:
      - description: A unique profile identifier
        in: path
        name: id
        required: true
        type: string
      responses:
        '200':
          description: Success.
          schema:
            type: object

  /conversations:
    get:
      operationId: listConversations
      summary: Get a list of all conversations.
      tags: [ conversation ]
      x-mojo-to: conversation#list
      responses:
        '200':
          description: List of conversations.
          schema:
            type: object
            properties:
              conversations:
                items:
                  $ref: '#/definitions/Conversation'

  /embed:
    get:
      operationId: embed
      summary: Get information from a URL
      tags: [ 'misc' ]
      x-mojo-to: [ 'url#info', [ "format", [ html, json, jsonp ] ] ]
      parameters:
      - description: URL to resource
        in: query
        name: url
        required: true
        type: string
      responses:
        '200':
          description: Information about resource.

  /files:
    get:
      operationId: getFiles
      summary: Retrieve list of uploaded files.
      tags: [ files ]
      x-mojo-to: files#list
      parameters:
      - description: Find files after a file ID, can be "after", "prev" or the last file ID from the response
        in: query
        name: after
        type: string
      - description: Max number of files to retrieve
        in: query
        name: limit
        type: integer
      responses:
        '200':
          description: Files found
          schema:
            type: object
            properties:
              after:
                description: Can be used as "after" query param to get the current page
                type: string
              files:
                type: array
                items:
                  type: object
                  required: [id, name, saved, size]
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    saved:
                      type: string
                      format: date-time
                    size:
                      type: integer
              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
    post:
      consumes: [ 'application/x-www-form-urlencoded', 'multipart/form-data' ]
      operationId: uploadFile
      summary: Upload file.
      tags: [ files ]
      x-mojo-to: files#upload
      parameters:
      - in: formData
        name: file
        required: true
        type: file
      - in: formData
        name: id
        type: string
      - in: formData
        name: write_only
        type: boolean
      responses:
        '200':
          description: Successfully uploaded.
          schema:
            type: object
            properties:
              files:
                items:
                  type: object
                  required: [ ext, filename, id, saved, uid, url ]
                  properties:
                    ext:
                      type: string
                    filename:
                      type: string
                    id:
                      type: string
                    saved:
                      format: date-time
                      type: string
                    uid:
                      type: string
                    url:
                      format: uri
                      type: string

  /files/{uid}/{fid}:
    get:
      produces:
        - application/pdf
        - application/zip
        - audio/mpeg
        - audio/ogg
        - image/gif
        - image/jpeg
        - image/png
        - text/html
        - video/mp4
        - video/ogg
        - video/webm
      operationId: getFile
      summary: Retrieve uploaded file.
      tags: [ files ]
      x-mojo-to: files#get
      parameters:
      - in: path
        name: fid
        required: true
        type: string
      - in: path
        name: uid
        required: true
        type: string
      responses:
        '200':
          description: File found and served.
          schema:
            type: string
    delete:
      operationId: deleteFiles
      summary: Delete one (or more) uploaded file.
      tags: [ files ]
      x-mojo-to: files#remove
      parameters:
      - in: path
        name: fid
        required: true
        type: string
      - in: path
        name: uid
        required: true
        type: string
      responses:
        '200':
          description: Successfully deleted.
          schema:
            type: object
            properties:
              deleted:
                type: integer

  /i18n/{lang}:
    get:
      operationId: getDictionary
      summary: Retrieve translations.
      tags: [ i18n ]
      x-mojo-to: user#dictionary
      parameters:
      - in: path
        name: lang
        required: true
        type: string
      responses:
        '200':
          description: Dictionary.
          schema:
            type: object
            required: [ dictionary ]
            properties:
              dictionary:
                type: object

  /notifications:
    get:
      description: A notification is added once your name is mentioned in a chat.
      summary: Get list of notications.
      tags: [ chat ]
      x-mojo-to: notifications#messages
      operationId: notificationMessages
      responses:
        '200':
          description: List of notifications.
          schema:
            type: object
            properties:
              messages:
                items:
                  $ref: '#/definitions/Notification'

  /notifications/read:
    post:
      operationId: markNotificationsAsRead
      summary: Mark notications as read.
      tags: [ chat ]
      x-mojo-to: notifications#read
      responses:
        '200':
          description: Successful response.
          schema:
            type: object
            properties: {}

  /search:
    get:
      operationId: searchMessages
      summary: Search for historic messages.
      tags: [ search ]
      x-mojo-to: search#messages
      parameters:
      - description: An ID for a connection
        in: query
        name: connection_id
        type: string
      - description: An ID for a conversation
        in: query
        name: conversation_id
        type: string
      - description: Find messages after a given ISO 8601 timestamp
        format: date-time
        in: query
        name: after
        type: string
      - description: Find messages before a given ISO 8601 timestamp
        format: date-time
        in: query
        name: before
        type: string
      - description: Sender must match this string
        in: query
        name: from
        type: string
      - description: Max number of messages to retrieve
        in: query
        name: limit
        type: integer
      - description: Messages must match this string
        in: query
        name: match
        type: string
      responses:
        '200':
          description: List of messages.
          schema:
            type: object
            properties:
              after:
                type: string
                format: date-time
              before:
                type: string
                format: date-time
              messages:
                items:
                  $ref: '#/definitions/Message'

  /settings:
    get:
      operationId: getSettings
      summary: Get settings for Convos.
      tags: [ settings ]
      x-mojo-to: admin#settings_get
      responses:
        '200':
          description: ServerSettings.
          schema:
            $ref: '#/definitions/ServerSettings'
    post:
      operationId: updateSettings
      summary: Update settings for Convos.
      tags: [ settings ]
      x-mojo-to: admin#settings_update
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/ServerSettings'
      responses:
        '200':
          description: User profile.
          schema:
            $ref: '#/definitions/ServerSettings'

  /user:
    get:
      operationId: getUser
      summary: Get user data.
      tags: [ user ]
      x-mojo-to: user#get
      parameters:
      - description: Retrieve connection list.
        in: query
        name: connections
        type: boolean
      - description: Retrieve conversation list.
        in: query
        name: conversations
        type: boolean
      responses:
        '200':
          description: User profile.
          schema:
            $ref: '#/definitions/User'

  /user/login:
    post:
      operationId: loginUser
      summary: Log in a user based on email and password.
      tags: [ user ]
      x-mojo-to: user#login
      parameters:
      - in: body
        name: body
        required: true
        schema:
          type: object
          required: [ email, password ]
          properties:
            email:
              description: User email
              format: email
              type: string
            password:
              description: User password
              type: string
      responses:
        '200':
          description: User profile.
          schema:
            $ref: '#/definitions/User'

  /user/logout:
    get:
      description: This resource will delete any sessions cookies that might be stored in the client.
      operationId: logoutUser
      summary: Logout a user.
      tags: [ user ]
      x-mojo-to: ["user#logout", ["format", ["html", "json"]]]
      parameters:
        - in: query
          name: csrf
          required: true
          type: string
      responses:
        '302':
          description: Successfully logged out.

  /user/register:
    post:
      operationId: registerUser
      summary: Register a new user.
      tags: [ user ]
      x-mojo-to: user#register
      parameters:
      - in: body
        name: body
        required: true
        schema:
          type: object
          required: [ email, password ]
          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
      responses:
        '200':
          description: User profile.
          schema:
            $ref: '#/definitions/User'

  /user/{email}:
    delete:
      operationId: deleteUser
      summary: Delete a user.
      tags: [ user ]
      x-mojo-to: user#remove
      parameters:
      - $ref: '#/parameters/email_in_path'
      responses:
        '200':
          description: Successfully deleted.
          schema:
            $ref: '#/definitions/Success'
    post:
      operationId: updateUser
      summary: Update an existing user.
      tags: [ user ]
      x-mojo-to: user#update
      parameters:
      - $ref: '#/parameters/email_in_path'
      - in: body
        name: body
        required: true
        schema:
          type: object
          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.
              type: array
              items:
                type: string
      responses:
        '200':
          description: User profile.
          schema:
            $ref: '#/definitions/User'

  /user/{email}/invite:
    post:
      operationId: inviteUser
      summary: Generate invite link for an existing / new user.
      tags: [ user ]
      x-mojo-to: ["user#generate_invite_link", ["format", ["html", "json"]]]
      parameters:
      - $ref: '#/parameters/email_in_path'
      responses:
        '200':
          description: User profile.
          schema:
            type: object
            required: [ url ]
            properties:
              existing:
                type: boolean
              expires:
                format: date-time
                type: string
              url:
                type: string

  /users:
    get:
      operationId: getUsers
      summary: List Convos users
      tags: [ user ]
      x-mojo-to: user#list
      parameters:
      - description: Find users after in pagination
        in: query
        name: after
        type: string
      responses:
        '200':
          description: List of users.
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  $ref: '#/definitions/User'

  /webhook/{provider_name}:
    post:
      operationId: webhook
      summary: Forwards the webhook payload to the Convos bot
      tags: [ webhook ]
      x-mojo-to: events#webhook
      parameters:
      - description: Provider name
        in: path
        name: provider_name
        type: string
        required: true
      - description: Any webhook payload
        in: body
        name: body
        required: true
        schema:
          type: object
      responses:
        '200':
          description: Webhook response
          schema:
            type: object

parameters:
  after:
    name: after
    description: Find messages after a given ISO 8601 timestamp
    format: date-time
    in: query
    type: string
  around:
    name: around
    description: Find messages around a given ISO 8601 timestamp
    format: date-time
    in: query
    type: string
  before:
    name: before
    description: Find messages before a given ISO 8601 timestamp
    format: date-time
    in: query
    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:
    type: object
    required: [ connection_id, url ]
    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

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

  Conversation:
    type: object
    required: [ connection_id, conversation_id, name, unread ]
    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

  Message:
    type: object
    required: [ message, from , ts ]
    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

  Notification:
    type: object
    required: [ message, from , ts ]
    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

  Password:
    description: User password
    minLength: 10
    type: string

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

  Success:
    type: object
    properties:
      message:
        description: Human readable description
        type: string

  User:
    type: object
    required: [ email, unread ]
    properties:
      connections:
        items:
          $ref: '#/definitions/Connection'
      conversations:
        items:
          $ref: '#/definitions/Conversation'
      default_connection:
        type: string
        readOnly: true
      forced_connection:
        type: boolean
        readOnly: true
      email:
        description: Unique email identifying a user in Convos
        type: string
      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