SimpleCloudNotifier/scnserver/swagger/swagger.yaml

basePath: /
definitions:
  ginresp.apiError:
    properties:
      errhighlight:
        type: integer
      error:
        type: integer
      message:
        type: string
      success:
        type: boolean
    type: object
  ginresp.compatAPIError:
    properties:
      errid:
        type: integer
      message:
        type: string
      success:
        type: boolean
    type: object
  handler.Ack.response:
    properties:
      message:
        type: string
      new_ack:
        type: integer
      prev_ack:
        type: integer
      success:
        type: boolean
    type: object
  handler.AddClient.body:
    properties:
      agent_model:
        type: string
      agent_version:
        type: string
      client_type:
        type: string
      fcm_token:
        type: string
    required:
    - agent_model
    - agent_version
    - client_type
    - fcm_token
    type: object
  handler.CreateChannel.body:
    properties:
      name:
        type: string
      subscribe:
        type: boolean
    type: object
  handler.CreateSubscription.body:
    properties:
      channel_id:
        type: integer
      channel_internal_name:
        type: string
      channel_owner_user_id:
        type: integer
    type: object
  handler.CreateUser.body:
    properties:
      agent_model:
        type: string
      agent_version:
        type: string
      client_type:
        type: string
      fcm_token:
        type: string
      no_client:
        type: boolean
      pro_token:
        type: string
      username:
        type: string
    type: object
  handler.DatabaseTest.response:
    properties:
      libVersion:
        type: string
      libVersionNumber:
        type: integer
      sourceID:
        type: string
      success:
        type: boolean
    type: object
  handler.Expand.response:
    properties:
      data:
        $ref: '#/definitions/models.CompatMessage'
      message:
        type: string
      success:
        type: boolean
    type: object
  handler.Health.response:
    properties:
      status:
        type: string
    type: object
  handler.Info.response:
    properties:
      fcm_token_set:
        type: boolean
      is_pro:
        type: integer
      message:
        type: string
      quota:
        type: integer
      quota_max:
        type: integer
      success:
        type: boolean
      unack_count:
        type: integer
      user_id:
        type: integer
      user_key:
        type: string
    type: object
  handler.ListChannelMessages.response:
    properties:
      messages:
        items:
          $ref: '#/definitions/models.MessageJSON'
        type: array
      next_page_token:
        type: string
      page_size:
        type: integer
    type: object
  handler.ListChannelSubscriptions.response:
    properties:
      subscriptions:
        items:
          $ref: '#/definitions/models.SubscriptionJSON'
        type: array
    type: object
  handler.ListChannels.response:
    properties:
      channels:
        items:
          $ref: '#/definitions/models.ChannelWithSubscriptionJSON'
        type: array
    type: object
  handler.ListClients.response:
    properties:
      clients:
        items:
          $ref: '#/definitions/models.ClientJSON'
        type: array
    type: object
  handler.ListMessages.response:
    properties:
      messages:
        items:
          $ref: '#/definitions/models.MessageJSON'
        type: array
      next_page_token:
        type: string
      page_size:
        type: integer
    type: object
  handler.ListUserSubscriptions.response:
    properties:
      subscriptions:
        items:
          $ref: '#/definitions/models.SubscriptionJSON'
        type: array
    type: object
  handler.Register.response:
    properties:
      is_pro:
        type: integer
      message:
        type: string
      quota:
        type: integer
      quota_max:
        type: integer
      success:
        type: boolean
      user_id:
        type: integer
      user_key:
        type: string
    type: object
  handler.Requery.response:
    properties:
      count:
        type: integer
      data:
        items:
          $ref: '#/definitions/models.CompatMessage'
        type: array
      message:
        type: string
      success:
        type: boolean
    type: object
  handler.SendMessage.combined:
    properties:
      chan_key:
        example: qhnUbKcLgp6tg
        type: string
      channel:
        example: test
        type: string
      content:
        example: This is a message
        type: string
      msg_id:
        example: db8b0e6a-a08c-4646
        type: string
      priority:
        enum:
        - 0
        - 1
        - 2
        example: 1
        type: integer
      sender_name:
        example: example-server
        type: string
      timestamp:
        example: 1669824037
        type: number
      title:
        example: Hello World
        type: string
      user_id:
        example: 7725
        type: integer
      user_key:
        example: P3TNH8mvv14fm
        type: string
    type: object
  handler.Sleep.response:
    properties:
      duration:
        type: number
      end:
        type: string
      start:
        type: string
    type: object
  handler.Update.response:
    properties:
      is_pro:
        type: integer
      message:
        type: string
      quota:
        type: integer
      quota_max:
        type: integer
      success:
        type: boolean
      user_id:
        type: integer
      user_key:
        type: string
    type: object
  handler.UpdateSubscription.body:
    properties:
      confirmed:
        type: boolean
    type: object
  handler.Upgrade.response:
    properties:
      is_pro:
        type: boolean
      message:
        type: string
      quota:
        type: integer
      quota_max:
        type: integer
      success:
        type: boolean
      user_id:
        type: integer
    type: object
  handler.pingResponse:
    properties:
      info:
        $ref: '#/definitions/handler.pingResponseInfo'
      message:
        type: string
    type: object
  handler.pingResponseInfo:
    properties:
      addr:
        type: string
      headers:
        additionalProperties:
          items:
            type: string
          type: array
        type: object
      method:
        type: string
      request:
        type: string
      uri:
        type: string
    type: object
  handler.sendMessageInternal.response:
    properties:
      errhighlight:
        type: integer
      error:
        type: integer
      is_pro:
        type: boolean
      message:
        type: string
      messagecount:
        type: integer
      quota:
        type: integer
      quota_max:
        type: integer
      scn_msg_id:
        type: integer
      success:
        type: boolean
      suppress_send:
        type: boolean
    type: object
  models.ChannelWithSubscriptionJSON:
    properties:
      channel_id:
        type: integer
      description_name:
        type: string
      display_name:
        type: string
      internal_name:
        type: string
      messages_sent:
        type: integer
      owner_user_id:
        type: integer
      send_key:
        description: can be nil, depending on endpoint
        type: string
      subscribe_key:
        description: can be nil, depending on endpoint
        type: string
      subscription:
        $ref: '#/definitions/models.SubscriptionJSON'
      timestamp_created:
        type: string
      timestamp_lastsent:
        type: string
    type: object
  models.ClientJSON:
    properties:
      agent_model:
        type: string
      agent_version:
        type: string
      client_id:
        type: integer
      fcm_token:
        type: string
      timestamp_created:
        type: string
      type:
        type: string
      user_id:
        type: integer
    type: object
  models.CompatMessage:
    properties:
      body:
        type: string
      priority:
        type: integer
      scn_msg_id:
        type: integer
      timestamp:
        type: integer
      title:
        type: string
      trimmed:
        type: boolean
      usr_msg_id:
        type: string
    type: object
  models.MessageJSON:
    properties:
      channel_id:
        type: integer
      channel_internal_name:
        type: string
      content:
        type: string
      owner_user_id:
        type: integer
      priority:
        type: integer
      scn_message_id:
        type: integer
      sender_ip:
        type: string
      sender_name:
        type: string
      sender_user_id:
        type: integer
      timestamp:
        type: string
      title:
        type: string
      trimmed:
        type: boolean
      usr_message_id:
        type: string
    type: object
  models.SubscriptionJSON:
    properties:
      channel_id:
        type: integer
      channel_internal_name:
        type: string
      channel_owner_user_id:
        type: integer
      confirmed:
        type: boolean
      subscriber_user_id:
        type: integer
      subscription_id:
        type: integer
      timestamp_created:
        type: string
    type: object
  models.UserJSON:
    properties:
      admin_key:
        type: string
      default_channel:
        type: string
      is_pro:
        type: boolean
      messages_sent:
        type: integer
      quota_max:
        type: integer
      quota_remaining:
        type: integer
      quota_used:
        type: integer
      read_key:
        type: string
      send_key:
        type: string
      timestamp_created:
        type: string
      timestamp_lastread:
        type: string
      timestamp_lastsent:
        type: string
      user_id:
        type: integer
      username:
        type: string
    type: object
  models.UserJSONWithClients:
    properties:
      admin_key:
        type: string
      clients:
        items:
          $ref: '#/definitions/models.ClientJSON'
        type: array
      default_channel:
        type: string
      is_pro:
        type: boolean
      messages_sent:
        type: integer
      quota_max:
        type: integer
      quota_remaining:
        type: integer
      quota_used:
        type: integer
      read_key:
        type: string
      send_key:
        type: string
      timestamp_created:
        type: string
      timestamp_lastread:
        type: string
      timestamp_lastsent:
        type: string
      user_id:
        type: integer
      username:
        type: string
    type: object
host: scn.blackforestbytes.com
info:
  contact: {}
  description: API for SCN
  title: SimpleCloudNotifier API
  version: "2.0"
paths:
  /:
    post:
      description: All parameter can be set via query-parameter or the json body.
        Only UserID, UserKey and Title are required
      parameters:
      - example: qhnUbKcLgp6tg
        in: query
        name: chan_key
        type: string
      - example: test
        in: query
        name: channel
        type: string
      - example: This is a message
        in: query
        name: content
        type: string
      - example: db8b0e6a-a08c-4646
        in: query
        name: msg_id
        type: string
      - enum:
        - 0
        - 1
        - 2
        example: 1
        in: query
        name: priority
        type: integer
      - example: example-server
        in: query
        name: sender_name
        type: string
      - example: 1669824037
        in: query
        name: timestamp
        type: number
      - example: Hello World
        in: query
        name: title
        type: string
      - example: 7725
        in: query
        name: user_id
        type: integer
      - example: P3TNH8mvv14fm
        in: query
        name: user_key
        type: string
      - description: ' '
        in: body
        name: post_body
        schema:
          $ref: '#/definitions/handler.SendMessage.combined'
      - example: qhnUbKcLgp6tg
        in: formData
        name: chan_key
        type: string
      - example: test
        in: formData
        name: channel
        type: string
      - example: This is a message
        in: formData
        name: content
        type: string
      - example: db8b0e6a-a08c-4646
        in: formData
        name: msg_id
        type: string
      - enum:
        - 0
        - 1
        - 2
        example: 1
        in: formData
        name: priority
        type: integer
      - example: example-server
        in: formData
        name: sender_name
        type: string
      - example: 1669824037
        in: formData
        name: timestamp
        type: number
      - example: Hello World
        in: formData
        name: title
        type: string
      - example: 7725
        in: formData
        name: user_id
        type: integer
      - example: P3TNH8mvv14fm
        in: formData
        name: user_key
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.sendMessageInternal.response'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: The user_id was not found or the user_key is wrong
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "403":
          description: The user has exceeded its daily quota - wait 24 hours or upgrade
            your account
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: An internal server error occurred - try again later
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Send a new message
      tags:
      - External
  /api/ack.php:
    get:
      deprecated: true
      operationId: compat-ack
      parameters:
      - description: the user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: the message id
        in: query
        name: scn_msg_id
        required: true
        type: string
      - description: the user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: formData
        name: user_key
        required: true
        type: string
      - description: the message id
        in: formData
        name: scn_msg_id
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Acknowledge that a message was received
      tags:
      - API-v1
  /api/db-test:
    post:
      operationId: api-common-dbtest
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.DatabaseTest.response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Check for a working database connection
      tags:
      - Common
  /api/expand.php:
    get:
      deprecated: true
      operationId: compat-expand
      parameters:
      - description: The user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: The user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: The message-id
        in: query
        name: scn_msg_id
        required: true
        type: string
      - description: The user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: The user_key
        in: formData
        name: user_key
        required: true
        type: string
      - description: The message-id
        in: formData
        name: scn_msg_id
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Get a whole (potentially truncated) message
      tags:
      - API-v1
  /api/health:
    get:
      operationId: api-common-health
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.Health.response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Server Health-checks
      tags:
      - Common
  /api/info.php:
    get:
      deprecated: true
      operationId: compat-info
      parameters:
      - description: the user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: the user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: formData
        name: user_key
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Get information about the current user
      tags:
      - API-v1
  /api/messages:
    get:
      description: |-
        The next_page_token is an opaque token, the special value "@start" (or empty-string) is the beginning and "@end" is the end
        Simply start the pagination without a next_page_token and get the next page by calling this endpoint with the returned next_page_token of the last query
        If there are no more entries the token "@end" will be returned
        By default we return long messages with a trimmed body, if trimmed=false is supplied we return full messages (this reduces the max page_size)
      operationId: api-messages-list
      parameters:
      - in: query
        name: filter
        type: string
      - in: query
        name: next_page_token
        type: string
      - in: query
        name: page_size
        type: integer
      - description: TODO more filter (sender-name, channel, timestamps, prio, )
        in: query
        name: trimmed
        type: boolean
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListMessages.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List all (subscribed) messages
      tags:
      - API-v2
  /api/messages/{mid}:
    delete:
      description: The user must own the message and request the resource with the
        ADMIN Key
      operationId: api-messages-delete
      parameters:
      - description: SCNMessageID
        in: path
        name: mid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.MessageJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: message not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Delete a single message
      tags:
      - API-v2
    patch:
      description: |-
        The user must either own the message and request the resource with the READ or ADMIN Key
        Or the user must subscribe to the corresponding channel (and be confirmed) and request the resource with the READ or ADMIN Key
        The returned message is never trimmed
      operationId: api-messages-get
      parameters:
      - description: SCNMessageID
        in: path
        name: mid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.MessageJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: message not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Get a single message (untrimmed)
      tags:
      - API-v2
  /api/ping:
    delete:
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.pingResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Simple endpoint to test connection (any http method)
      tags:
      - Common
    get:
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.pingResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Simple endpoint to test connection (any http method)
      tags:
      - Common
    patch:
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.pingResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Simple endpoint to test connection (any http method)
      tags:
      - Common
    post:
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.pingResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Simple endpoint to test connection (any http method)
      tags:
      - Common
    put:
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.pingResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Simple endpoint to test connection (any http method)
      tags:
      - Common
  /api/register.php:
    get:
      deprecated: true
      operationId: compat-register
      parameters:
      - description: the (android) fcm token
        in: query
        name: fcm_token
        required: true
        type: string
      - description: if the user is a paid account
        enum:
        - "true"
        - "false"
        in: query
        name: pro
        required: true
        type: string
      - description: the (android) IAP token
        in: query
        name: pro_token
        required: true
        type: string
      - description: the (android) fcm token
        in: formData
        name: fcm_token
        required: true
        type: string
      - description: if the user is a paid account
        enum:
        - "true"
        - "false"
        in: formData
        name: pro
        required: true
        type: string
      - description: the (android) IAP token
        in: formData
        name: pro_token
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Register a new account
      tags:
      - API-v1
  /api/requery.php:
    get:
      deprecated: true
      operationId: compat-requery
      parameters:
      - description: the user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: the user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: formData
        name: user_key
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Return all not-acknowledged messages
      tags:
      - API-v1
  /api/sleep/{secs}:
    post:
      operationId: api-common-sleep
      parameters:
      - description: sleep delay (in seconds)
        in: path
        name: secs
        required: true
        type: number
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.Sleep.response'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Return 200 after x seconds
      tags:
      - Common
  /api/update.php:
    get:
      deprecated: true
      operationId: compat-update
      parameters:
      - description: the user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: the (android) fcm token
        in: query
        name: fcm_token
        required: true
        type: string
      - description: the user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: formData
        name: user_key
        required: true
        type: string
      - description: the (android) fcm token
        in: formData
        name: fcm_token
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Set the fcm-token (android)
      tags:
      - API-v1
  /api/upgrade.php:
    get:
      deprecated: true
      operationId: compat-upgrade
      parameters:
      - description: the user_id
        in: query
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: query
        name: user_key
        required: true
        type: string
      - description: if the user is a paid account
        enum:
        - "true"
        - "false"
        in: query
        name: pro
        required: true
        type: string
      - description: the (android) IAP token
        in: query
        name: pro_token
        required: true
        type: string
      - description: the user_id
        in: formData
        name: user_id
        required: true
        type: string
      - description: the user_key
        in: formData
        name: user_key
        required: true
        type: string
      - description: if the user is a paid account
        enum:
        - "true"
        - "false"
        in: formData
        name: pro
        required: true
        type: string
      - description: the (android) IAP token
        in: formData
        name: pro_token
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/ginresp.compatAPIError'
      summary: Upgrade a free account to a paid account
      tags:
      - API-v1
  /api/users:
    post:
      operationId: api-user-create
      parameters:
      - description: ' '
        in: body
        name: post_body
        schema:
          $ref: '#/definitions/handler.CreateUser.body'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.UserJSONWithClients'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Create a new user
      tags:
      - API-v2
  /api/users/{uid}:
    get:
      operationId: api-user-get
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.UserJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: user not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Get a user
      tags:
      - API-v2
    patch:
      description: The body-values are optional, only send the ones you want to update
      operationId: api-user-update
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: Change the username (send an empty string to clear it)
        in: body
        name: username
        schema:
          type: string
      - description: Send a verification of permium purchase
        in: body
        name: pro_token
        schema:
          type: string
      - description: Send `true` to create a new read_key
        in: body
        name: read_key
        schema:
          type: string
      - description: Send `true` to create a new send_key
        in: body
        name: send_key
        schema:
          type: string
      - description: Send `true` to create a new admin_key
        in: body
        name: admin_key
        schema:
          type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.UserJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: user not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: (Partially) update a user
      tags:
      - API-v2
  /api/users/{uid}/channels:
    get:
      description: |-
        The possible values for 'selector' are:
        - "owned"          Return all channels of the user
        - "subscribed"     Return all channels that the user is subscribing to
        - "all"            Return channels that the user owns or is subscribing
        - "subscribed_any" Return all channels that the user is subscribing to (even unconfirmed)
        - "all_any"        Return channels that the user owns or is subscribing (even unconfirmed)
      operationId: api-channels-list
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: 'Filter channels (default: owned)'
        enum:
        - owned
        - subscribed
        - all
        - subscribed_any
        - all_any
        in: query
        name: selector
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListChannels.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List channels of a user (subscribed/owned/all)
      tags:
      - API-v2
    post:
      operationId: api-channels-create
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ' '
        in: body
        name: post_body
        schema:
          $ref: '#/definitions/handler.CreateChannel.body'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ChannelWithSubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "409":
          description: channel already exists
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Create a new (empty) channel
      tags:
      - API-v2
  /api/users/{uid}/channels/{cid}:
    get:
      operationId: api-channels-get
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ChannelID
        in: path
        name: cid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ChannelWithSubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: channel not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Get a single channel
      tags:
      - API-v2
    patch:
      operationId: api-channels-update
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ChannelID
        in: path
        name: cid
        required: true
        type: integer
      - description: Send `true` to create a new subscribe_key
        in: body
        name: subscribe_key
        schema:
          type: string
      - description: Send `true` to create a new send_key
        in: body
        name: send_key
        schema:
          type: string
      - description: Change the cahnnel display-name (only chnages to lowercase/uppercase
          are allowed - internal_name must stay the same)
        in: body
        name: display_name
        schema:
          type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ChannelWithSubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: channel not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: (Partially) update a channel
      tags:
      - API-v2
  /api/users/{uid}/channels/{cid}/messages:
    get:
      description: |-
        The next_page_token is an opaque token, the special value "@start" (or empty-string) is the beginning and "@end" is the end
        Simply start the pagination without a next_page_token and get the next page by calling this endpoint with the returned next_page_token of the last query
        If there are no more entries the token "@end" will be returned
        By default we return long messages with a trimmed body, if trimmed=false is supplied we return full messages (this reduces the max page_size)
      operationId: api-channel-messages
      parameters:
      - in: query
        name: filter
        type: string
      - in: query
        name: next_page_token
        type: string
      - in: query
        name: page_size
        type: integer
      - in: query
        name: trimmed
        type: boolean
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ChannelID
        in: path
        name: cid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListChannelMessages.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: channel not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List messages of a channel
      tags:
      - API-v2
  /api/users/{uid}/channels/{cid}/subscriptions:
    get:
      operationId: api-chan-subscriptions-list
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ChannelID
        in: path
        name: cid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListChannelSubscriptions.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: channel not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List all subscriptions of a channel
      tags:
      - API-v2
  /api/users/{uid}/clients:
    get:
      operationId: api-clients-list
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListClients.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List all clients
      tags:
      - API-v2
    post:
      operationId: api-clients-create
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ' '
        in: body
        name: post_body
        schema:
          $ref: '#/definitions/handler.AddClient.body'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ClientJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Add a new clients
      tags:
      - API-v2
  /api/users/{uid}/clients/{cid}:
    delete:
      operationId: api-clients-delete
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ClientID
        in: path
        name: cid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ClientJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: client not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Delete a client
      tags:
      - API-v2
    get:
      operationId: api-clients-get
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: ClientID
        in: path
        name: cid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.ClientJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: client not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Get a single client
      tags:
      - API-v2
  /api/users/{uid}/subscriptions:
    get:
      description: |-
        The possible values for 'selector' are:
        - "outgoing_all"         All subscriptions (confirmed/unconfirmed) with the user as subscriber (= subscriptions he can use to read channels)
        - "outgoing_confirmed"   Confirmed subscriptions with the user as subscriber
        - "outgoing_unconfirmed" Unconfirmed (Pending) subscriptions with the user as subscriber
        - "incoming_all"         All subscriptions (confirmed/unconfirmed) from other users to channels of this user (= incoming subscriptions and subscription requests)
        - "incoming_confirmed"   Confirmed subscriptions from other users to channels of this user
        - "incoming_unconfirmed" Unconfirmed subscriptions from other users to channels of this user (= requests)
      operationId: api-user-subscriptions-list
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: 'Filter subscriptions (default: owner_all)'
        enum:
        - outgoing_all
        - outgoing_confirmed
        - outgoing_unconfirmed
        - incoming_all
        - incoming_confirmed
        - incoming_unconfirmed
        in: query
        name: selector
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.ListUserSubscriptions.response'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: List all subscriptions of a user (incoming/owned)
      tags:
      - API-v2
    post:
      description: Either [channel_owner_user_id, channel_internal_name] or [channel_id]
        must be supplied in the request body
      operationId: api-subscriptions-create
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - in: query
        name: chan_subscribe_key
        type: string
      - description: ' '
        in: body
        name: post_data
        schema:
          $ref: '#/definitions/handler.CreateSubscription.body'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.SubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Create/Request a subscription
      tags:
      - API-v2
  /api/users/{uid}/subscriptions/{sid}:
    delete:
      operationId: api-subscriptions-delete
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: SubscriptionID
        in: path
        name: sid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.SubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: subscription not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Cancel (delete) subscription
      tags:
      - API-v2
    get:
      operationId: api-subscriptions-get
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: SubscriptionID
        in: path
        name: sid
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.SubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: subscription not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Get a single subscription
      tags:
      - API-v2
    patch:
      operationId: api-subscriptions-update
      parameters:
      - description: UserID
        in: path
        name: uid
        required: true
        type: integer
      - description: SubscriptionID
        in: path
        name: sid
        required: true
        type: integer
      - description: ' '
        in: body
        name: post_data
        schema:
          $ref: '#/definitions/handler.UpdateSubscription.body'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/models.SubscriptionJSON'
        "400":
          description: supplied values/parameters cannot be parsed / are invalid
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: user is not authorized / has missing permissions
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "404":
          description: subscription not found
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: internal server error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Update a subscription (e.g. confirm)
      tags:
      - API-v2
  /send:
    post:
      description: All parameter can be set via query-parameter or the json body.
        Only UserID, UserKey and Title are required
      parameters:
      - example: qhnUbKcLgp6tg
        in: query
        name: chan_key
        type: string
      - example: test
        in: query
        name: channel
        type: string
      - example: This is a message
        in: query
        name: content
        type: string
      - example: db8b0e6a-a08c-4646
        in: query
        name: msg_id
        type: string
      - enum:
        - 0
        - 1
        - 2
        example: 1
        in: query
        name: priority
        type: integer
      - example: example-server
        in: query
        name: sender_name
        type: string
      - example: 1669824037
        in: query
        name: timestamp
        type: number
      - example: Hello World
        in: query
        name: title
        type: string
      - example: 7725
        in: query
        name: user_id
        type: integer
      - example: P3TNH8mvv14fm
        in: query
        name: user_key
        type: string
      - description: ' '
        in: body
        name: post_body
        schema:
          $ref: '#/definitions/handler.SendMessage.combined'
      - example: qhnUbKcLgp6tg
        in: formData
        name: chan_key
        type: string
      - example: test
        in: formData
        name: channel
        type: string
      - example: This is a message
        in: formData
        name: content
        type: string
      - example: db8b0e6a-a08c-4646
        in: formData
        name: msg_id
        type: string
      - enum:
        - 0
        - 1
        - 2
        example: 1
        in: formData
        name: priority
        type: integer
      - example: example-server
        in: formData
        name: sender_name
        type: string
      - example: 1669824037
        in: formData
        name: timestamp
        type: number
      - example: Hello World
        in: formData
        name: title
        type: string
      - example: 7725
        in: formData
        name: user_id
        type: integer
      - example: P3TNH8mvv14fm
        in: formData
        name: user_key
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.sendMessageInternal.response'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: The user_id was not found or the user_key is wrong
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "403":
          description: The user has exceeded its daily quota - wait 24 hours or upgrade
            your account
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: An internal server error occurred - try again later
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Send a new message
      tags:
      - External
  /send.php:
    post:
      deprecated: true
      description: All parameter can be set via query-parameter or form-data body.
        Only UserID, UserKey and Title are required
      parameters:
      - in: query
        name: content
        type: string
      - in: query
        name: msg_id
        type: string
      - in: query
        name: priority
        type: integer
      - in: query
        name: timestamp
        type: number
      - in: query
        name: title
        type: string
      - in: query
        name: user_id
        type: integer
      - in: query
        name: user_key
        type: string
      - in: formData
        name: content
        type: string
      - in: formData
        name: msg_id
        type: string
      - in: formData
        name: priority
        type: integer
      - in: formData
        name: timestamp
        type: number
      - in: formData
        name: title
        type: string
      - in: formData
        name: user_id
        type: integer
      - in: formData
        name: user_key
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handler.sendMessageInternal.response'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/ginresp.apiError'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ginresp.apiError'
      summary: Send a new message (compatibility)
      tags:
      - External
swagger: "2.0"
tags:
- name: External
- name: API-v1
- name: API-v2
- name: Common