basePath: / definitions: apierr.APIError: enum: - -1 - 0 - 1101 - 1102 - 1103 - 1104 - 1105 - 1106 - 1121 - 1151 - 1152 - 1153 - 1161 - 1171 - 1201 - 1202 - 1203 - 1204 - 1205 - 1206 - 1207 - 1208 - 1209 - 1301 - 1302 - 1303 - 1304 - 1305 - 1306 - 1307 - 1311 - 1401 - 1501 - 1511 - 1512 - 2101 - 3001 - 3002 - 9901 - 9902 - 9903 - 9904 - 9905 type: integer x-enum-varnames: - UNDEFINED - NO_ERROR - MISSING_UID - MISSING_TOK - MISSING_TITLE - INVALID_PRIO - REQ_METHOD - INVALID_CLIENTTYPE - PAGETOKEN_ERROR - BINDFAIL_QUERY_PARAM - BINDFAIL_BODY_PARAM - BINDFAIL_URI_PARAM - INVALID_BODY_PARAM - INVALID_ENUM_VALUE - NO_TITLE - TITLE_TOO_LONG - CONTENT_TOO_LONG - USR_MSG_ID_TOO_LONG - TIMESTAMP_OUT_OF_RANGE - SENDERNAME_TOO_LONG - CHANNEL_TOO_LONG - CHANNEL_DESCRIPTION_TOO_LONG - CHANNEL_NAME_EMPTY - USER_NOT_FOUND - CLIENT_NOT_FOUND - CHANNEL_NOT_FOUND - SUBSCRIPTION_NOT_FOUND - MESSAGE_NOT_FOUND - SUBSCRIPTION_USER_MISMATCH - KEY_NOT_FOUND - USER_AUTH_FAILED - NO_DEVICE_LINKED - CHANNEL_ALREADY_EXISTS - CANNOT_SELFDELETE_KEY - CANNOT_SELFUPDATE_KEY - QUOTA_REACHED - FAILED_VERIFY_PRO_TOKEN - INVALID_PRO_TOKEN - FIREBASE_COM_FAILED - FIREBASE_COM_ERRORED - INTERNAL_EXCEPTION - PANIC - NOT_IMPLEMENTED 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: string channel_internal_name: type: string channel_owner_user_id: type: string 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.CreateUserKey.body: properties: all_channels: type: boolean channels: items: type: string type: array name: type: string permissions: type: string required: - all_channels - channels - name - permissions 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.ListUserKeys.response: properties: keys: items: $ref: '#/definitions/models.KeyTokenJSON' type: array type: object handler.ListUserSubscriptions.response: properties: subscriptions: items: $ref: '#/definitions/models.SubscriptionJSON' type: array type: object handler.Register.response: properties: is_pro: type: boolean 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: channel: example: test type: string content: example: This is a message type: string key: example: P3TNH8mvv14fm 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: string type: object handler.SendMessage.response: properties: errhighlight: type: integer error: $ref: '#/definitions/apierr.APIError' is_pro: type: boolean message: type: string messagecount: type: integer quota: type: integer quota_max: type: integer scn_msg_id: type: string success: type: boolean suppress_send: type: boolean type: object handler.SendMessageCompat.response: properties: errhighlight: type: integer error: $ref: '#/definitions/apierr.APIError' 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 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.UpdateUserKey.body: properties: all_channels: type: boolean channels: items: type: string type: array name: type: string permissions: type: string 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 models.ChannelWithSubscriptionJSON: properties: channel_id: type: string description_name: type: string display_name: type: string internal_name: type: string messages_sent: type: integer owner_user_id: 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: string fcm_token: type: string timestamp_created: type: string type: $ref: '#/definitions/models.ClientType' user_id: type: string type: object models.ClientType: enum: - ANDROID - IOS type: string x-enum-varnames: - ClientTypeAndroid - ClientTypeIOS 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.KeyTokenJSON: properties: all_channels: type: boolean channels: items: type: string type: array keytoken_id: type: string messages_sent: type: integer name: type: string owner_user_id: type: string permissions: type: string timestamp_created: type: string timestamp_lastused: type: string type: object models.MessageJSON: properties: channel_id: type: string channel_internal_name: type: string content: type: string message_id: type: string owner_user_id: type: string priority: type: integer sender_ip: type: string sender_name: type: string sender_user_id: type: string timestamp: type: string title: type: string trimmed: type: boolean used_key_id: type: string usr_message_id: type: string type: object models.SubscriptionJSON: properties: channel_id: type: string channel_internal_name: type: string channel_owner_user_id: type: string confirmed: type: boolean subscriber_user_id: type: string subscription_id: type: string timestamp_created: type: string type: object models.UserJSON: properties: default_channel: type: string is_pro: type: boolean messages_sent: type: integer quota_max: type: integer quota_remaining: type: integer quota_used: type: integer timestamp_created: type: string timestamp_lastread: type: string timestamp_lastsent: type: string user_id: type: string username: type: string type: object models.UserJSONWithClientsAndKeys: 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: string 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: test in: query name: channel type: string - example: This is a message in: query name: content type: string - example: P3TNH8mvv14fm in: query name: key 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: string - description: ' ' in: body name: post_body schema: $ref: '#/definitions/handler.SendMessage.combined' - example: test in: formData name: channel type: string - example: This is a message in: formData name: content type: string - example: P3TNH8mvv14fm in: formData name: key 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: string responses: "200": description: OK schema: $ref: '#/definitions/handler.SendMessage.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/handler.Ack.response' default: description: "" 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/handler.Expand.response' default: description: "" 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/handler.Info.response' default: description: "" schema: $ref: '#/definitions/ginresp.compatAPIError' summary: Get information about the current user tags: - API-v1 /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/handler.Register.response' default: description: "" 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/handler.Requery.response' default: description: "" 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/handler.Update.response' default: description: "" 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/handler.Upgrade.response' default: description: "" schema: $ref: '#/definitions/ginresp.compatAPIError' summary: Upgrade a free account to a paid account tags: - API-v1 /api/v2/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: - description: RFC3339 in: query name: after type: string - description: RFC3339 in: query name: before type: string - collectionFormat: csv in: query items: type: string name: channel type: array - collectionFormat: csv in: query items: type: string name: channel_id type: array - in: query name: filter type: string - in: query name: next_page_token type: string - in: query name: page_size type: integer - collectionFormat: csv in: query items: type: integer name: priority type: array - collectionFormat: csv in: query items: type: string name: sender type: array - in: query name: trimmed type: boolean - collectionFormat: csv in: query items: type: string name: used_key type: array 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/v2/messages/{mid}: delete: description: The user must own the message and request the resource with the ADMIN Key operationId: api-messages-delete parameters: - description: MessageID in: path name: mid required: true type: string 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: MessageID in: path name: mid required: true type: string 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/v2/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.UserJSONWithClientsAndKeys' "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/v2/users/{uid}: get: operationId: api-user-get parameters: - description: UserID in: path name: uid required: true 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: 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: string - description: Change the username (send an empty string to clear it) in: body name: username schema: type: string - description: Send a verification of premium purchase in: body name: pro_token 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/v2/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: string - 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: string - 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/v2/users/{uid}/channels/{cid}: get: operationId: api-channels-get parameters: - description: UserID in: path name: uid required: true type: string - description: ChannelID in: path name: cid required: true 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: Get a single channel tags: - API-v2 patch: operationId: api-channels-update parameters: - description: UserID in: path name: uid required: true type: string - description: ChannelID in: path name: cid required: true type: string - 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/v2/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: string - description: ChannelID in: path name: cid required: true type: string 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/v2/users/{uid}/channels/{cid}/subscriptions: get: operationId: api-chan-subscriptions-list parameters: - description: UserID in: path name: uid required: true type: string - description: ChannelID in: path name: cid required: true type: string 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/v2/users/{uid}/clients: get: operationId: api-clients-list parameters: - description: UserID in: path name: uid required: true type: string 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: string - 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/v2/users/{uid}/clients/{cid}: delete: operationId: api-clients-delete parameters: - description: UserID in: path name: uid required: true type: string - description: ClientID in: path name: cid required: true type: string 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: string - description: ClientID in: path name: cid required: true type: string 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 patch: description: The body-values are optional, only send the ones you want to update operationId: api-client-update parameters: - description: UserID in: path name: uid required: true type: string - description: ClientID in: path name: cid required: true type: string - description: Change the clientname (send an empty string to clear it) in: body name: clientname schema: type: string - description: Send a verification of premium purchase in: body name: pro_token schema: type: string 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: client 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: (Partially) update a client tags: - API-v2 /api/v2/users/{uid}/keys: get: description: The request must be done with an ADMIN key, the returned keys are without their token. operationId: api-tokenkeys-list parameters: - description: UserID in: path name: uid required: true type: string responses: "200": description: OK schema: $ref: '#/definitions/handler.ListUserKeys.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: message not found schema: $ref: '#/definitions/ginresp.apiError' "500": description: internal server error schema: $ref: '#/definitions/ginresp.apiError' summary: List keys of the user tags: - API-v2 post: operationId: api-tokenkeys-create parameters: - description: UserID in: path name: uid required: true type: string - description: ' ' in: body name: post_body schema: $ref: '#/definitions/handler.CreateUserKey.body' responses: "200": description: OK schema: $ref: '#/definitions/models.KeyTokenJSON' "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: Create a new key tags: - API-v2 /api/v2/users/{uid}/keys/{kid}: delete: description: Cannot be used to delete the key used in the request itself operationId: api-tokenkeys-delete parameters: - description: UserID in: path name: uid required: true type: string - description: TokenKeyID in: path name: kid required: true type: string responses: "200": description: OK schema: $ref: '#/definitions/models.KeyTokenJSON' "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 key tags: - API-v2 get: description: The request must be done with an ADMIN key, the returned key does not include its token. operationId: api-tokenkeys-get parameters: - description: UserID in: path name: uid required: true type: string - description: TokenKeyID in: path name: kid required: true type: string responses: "200": description: OK schema: $ref: '#/definitions/models.KeyTokenJSON' "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 key tags: - API-v2 patch: operationId: api-tokenkeys-update parameters: - description: UserID in: path name: uid required: true type: string - description: TokenKeyID in: path name: kid required: true type: string - description: ' ' in: body name: post_body schema: $ref: '#/definitions/handler.UpdateUserKey.body' responses: "200": description: OK schema: $ref: '#/definitions/models.KeyTokenJSON' "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: Update a key tags: - API-v2 /api/v2/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: string - description: 'Filter subscriptions (default: outgoing_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: string - 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/v2/users/{uid}/subscriptions/{sid}: delete: operationId: api-subscriptions-delete parameters: - description: UserID in: path name: uid required: true type: string - description: SubscriptionID in: path name: sid required: true type: string 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: string - description: SubscriptionID in: path name: sid required: true type: string 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: string - description: SubscriptionID in: path name: sid required: true type: string - 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: test in: query name: channel type: string - example: This is a message in: query name: content type: string - example: P3TNH8mvv14fm in: query name: key 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: string - description: ' ' in: body name: post_body schema: $ref: '#/definitions/handler.SendMessage.combined' - example: test in: formData name: channel type: string - example: This is a message in: formData name: content type: string - example: P3TNH8mvv14fm in: formData name: key 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: string responses: "200": description: OK schema: $ref: '#/definitions/handler.SendMessage.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.SendMessageCompat.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