{ "consumes": [ "application/json" ], "produces": [ "application/json" ], "schemes": [ "http", "https" ], "swagger": "2.0", "info": { "description": "This is the documentation of the Gotify REST-API.\n\n# Authentication\nIn Gotify there are two token types:\n__clientToken__: a client is something that receives message and manages stuff like creating new tokens or delete messages. (f.ex this token should be used for an android app)\n__appToken__: an application is something that sends messages (f.ex. this token should be used for a shell script)\n\nThe token can be either transmitted through a header named `X-Gotify-Key` or a query parameter named `token`.\nThere is also the possibility to authenticate through basic auth, this should only be used for creating a clientToken.\n\n\\---\n\nFound a bug or have some questions? [Create an issue on GitHub](https://github.com/gotify/server/issues)", "title": "Gotify REST-API.", "license": { "name": "MIT", "url": "https://github.com/gotify/server/blob/master/LICENSE" }, "version": "1.0.3" }, "host": "localhost", "paths": { "/application": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Return all applications.", "operationId": "getApps", "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/Application" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Create an application.", "operationId": "createApp", "parameters": [ { "description": "the application to add", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Application" } } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/Application" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/application/{id}": { "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Delete an application.", "operationId": "deleteApp", "parameters": [ { "type": "integer", "description": "the application id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/application/{id}/image": { "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "description": "Upload an image for an application", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "token" ], "operationId": "uploadAppImage", "parameters": [ { "type": "file", "description": "the application image", "name": "file", "in": "formData", "required": true }, { "type": "integer", "description": "the application id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/Application" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/application/{id}/message": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Return all messages from a specific application.", "operationId": "getAppMessages", "parameters": [ { "type": "integer", "description": "the application id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/Message" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Delete all messages from a specific application.", "operationId": "deleteAppMessages", "parameters": [ { "type": "integer", "description": "the application id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/client": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Return all clients.", "operationId": "getClients", "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/Client" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Create a client.", "operationId": "createClient", "parameters": [ { "description": "the client to add", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Client" } } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/Client" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/client/{id}": { "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "token" ], "summary": "Delete a client.", "operationId": "deleteClient", "parameters": [ { "type": "integer", "description": "the client id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/current/user": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Return the current user.", "operationId": "currentUser", "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/current/user/password": { "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Update the password of the current user.", "operationId": "updateCurrentUser", "parameters": [ { "description": "the user", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserPass" } } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/message": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Return all messages.", "operationId": "getMessages", "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/Message" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "security": [ { "appTokenHeader": [] }, { "appTokenQuery": [] } ], "description": "__NOTE__: This API ONLY accepts an application token as authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Create a message.", "operationId": "createMessage", "parameters": [ { "description": "the message to add", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Message" } } ], "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/Message" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } } } }, "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Delete all messages.", "operationId": "deleteMessages", "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/message/{id}": { "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Deletes a message with an id.", "operationId": "deleteMessage", "parameters": [ { "type": "integer", "description": "the message id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/stream": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "message" ], "summary": "Websocket, return newly created messages.", "operationId": "streamMessages", "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/Message" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/user": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Return all users.", "operationId": "getUsers", "responses": { "200": { "description": "Ok", "schema": { "type": "array", "items": { "$ref": "#/definitions/User" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Create a user.", "operationId": "createUser", "parameters": [ { "description": "the user to add", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserWithPass" } } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/user/{id}": { "get": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Get a user.", "operationId": "getUser", "parameters": [ { "type": "integer", "description": "the user id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Update a user.", "operationId": "updateUser", "parameters": [ { "type": "integer", "description": "the user id", "name": "id", "in": "path", "required": true }, { "description": "the updated user", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserWithPass" } } ], "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } }, "delete": { "security": [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Deletes a user.", "operationId": "deleteUser", "parameters": [ { "type": "integer", "description": "the user id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Ok" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/Error" } } } } }, "/version": { "get": { "produces": [ "application/json" ], "tags": [ "version" ], "summary": "Get version information.", "operationId": "getVersion", "responses": { "200": { "description": "Ok", "schema": { "$ref": "#/definitions/VersionInfo" } } } } } }, "definitions": { "Application": { "description": "The Application holds information about an app which can send notifications.", "type": "object", "title": "Application Model", "required": [ "id", "token", "name", "description", "image" ], "properties": { "description": { "description": "The description of the application.", "type": "string", "x-go-name": "Description", "example": "Backup server for the interwebs" }, "id": { "description": "The application id.", "type": "integer", "format": "uint64", "x-go-name": "ID", "readOnly": true, "example": 5 }, "image": { "description": "The image of the application.", "type": "string", "x-go-name": "Image", "readOnly": true, "example": "https://example.com/image.jpeg" }, "name": { "description": "The application name. This is how the application should be displayed to the user.", "type": "string", "x-go-name": "Name", "example": "Backup Server" }, "token": { "description": "The application token. Can be used as `appToken`. See Authentication.", "type": "string", "x-go-name": "Token", "readOnly": true, "example": "AWH0wZ5r0Mbac.r" } }, "x-go-package": "github.com/gotify/server/model" }, "Client": { "description": "The Client holds information about a device which can receive notifications (and other stuff).", "type": "object", "title": "Client Model", "required": [ "id", "token", "name" ], "properties": { "id": { "description": "The client id.", "type": "integer", "format": "uint64", "x-go-name": "ID", "readOnly": true, "example": 5 }, "name": { "description": "The client name. This is how the client should be displayed to the user.", "type": "string", "x-go-name": "Name", "example": "Android Phone" }, "token": { "description": "The client token. Can be used as `clientToken`. See Authentication.", "type": "string", "x-go-name": "Token", "readOnly": true, "example": "CWH0wZ5r0Mbac.r" } }, "x-go-package": "github.com/gotify/server/model" }, "Error": { "description": "The Error contains error relevant information.", "type": "object", "title": "Error Model", "required": [ "error", "errorCode", "errorDescription" ], "properties": { "error": { "description": "The general error message", "type": "string", "x-go-name": "Error", "example": "Unauthorized" }, "errorCode": { "description": "The http error code.", "type": "integer", "format": "int64", "x-go-name": "ErrorCode", "example": 401 }, "errorDescription": { "description": "The http error code.", "type": "string", "x-go-name": "ErrorDescription", "example": "you need to provide a valid access token or user credentials to access this api" } }, "x-go-package": "github.com/gotify/server/model" }, "Message": { "description": "The Message holds information about a message which was sent by an Application.", "type": "object", "title": "Message Model", "required": [ "id", "appid", "message", "title", "date" ], "properties": { "appid": { "description": "The application id that send this message.", "type": "integer", "format": "uint64", "x-go-name": "ApplicationID", "readOnly": true, "example": 5 }, "date": { "description": "The date the message was created.", "type": "string", "format": "date-time", "x-go-name": "Date", "readOnly": true, "example": "2018-02-27T19:36:10.5045044+01:00" }, "id": { "description": "The message id.", "type": "integer", "format": "uint64", "x-go-name": "ID", "readOnly": true, "example": 25 }, "message": { "description": "The actual message.", "type": "string", "x-go-name": "Message", "example": "Backup was successfully finished." }, "priority": { "description": "The priority of the message.", "type": "integer", "format": "int64", "x-go-name": "Priority", "example": 2 }, "title": { "description": "The title of the message.", "type": "string", "x-go-name": "Title", "example": "Backup" } }, "x-go-package": "github.com/gotify/server/model" }, "User": { "description": "The User holds information about permission and other stuff.", "type": "object", "title": "UserExternal Model", "required": [ "id", "name" ], "properties": { "admin": { "description": "If the user is an administrator.", "type": "boolean", "x-go-name": "Admin", "example": true }, "id": { "description": "The user id.", "type": "integer", "format": "uint64", "x-go-name": "ID", "readOnly": true, "example": 25 }, "name": { "description": "The user name. For login.", "type": "string", "x-go-name": "Name", "example": "unicorn" } }, "x-go-name": "UserExternal", "x-go-package": "github.com/gotify/server/model" }, "UserPass": { "description": "The Password for updating the user.", "type": "object", "title": "UserExternalPass Model", "required": [ "pass" ], "properties": { "pass": { "description": "The user password. For login.", "type": "string", "x-go-name": "Pass", "example": "nrocinu" } }, "x-go-name": "UserExternalPass", "x-go-package": "github.com/gotify/server/model" }, "UserWithPass": { "description": "The UserWithPass holds information about the credentials and other stuff.", "type": "object", "title": "UserExternalWithPass Model", "required": [ "id", "name", "pass" ], "properties": { "admin": { "description": "If the user is an administrator.", "type": "boolean", "x-go-name": "Admin", "example": true }, "id": { "description": "The user id.", "type": "integer", "format": "uint64", "x-go-name": "ID", "readOnly": true, "example": 25 }, "name": { "description": "The user name. For login.", "type": "string", "x-go-name": "Name", "example": "unicorn" }, "pass": { "description": "The user password. For login.", "type": "string", "x-go-name": "Pass", "example": "nrocinu" } }, "x-go-name": "UserExternalWithPass", "x-go-package": "github.com/gotify/server/model" }, "VersionInfo": { "description": "VersionInfo Model", "type": "object", "required": [ "version", "commit", "buildDate" ], "properties": { "buildDate": { "description": "The date on which this binary was built.", "type": "string", "x-go-name": "BuildDate", "example": "2018-02-27T19:36:10.5045044+01:00" }, "commit": { "description": "The git commit hash on which this binary was built.", "type": "string", "x-go-name": "Commit", "example": "ae9512b6b6feea56a110d59a3353ea3b9c293864" }, "version": { "description": "The current version.", "type": "string", "x-go-name": "Version", "example": "5.2.6" } }, "x-go-package": "github.com/gotify/server/model" } }, "securityDefinitions": { "appTokenHeader": { "type": "apiKey", "name": "X-Gotify-Key", "in": "header" }, "appTokenQuery": { "type": "apiKey", "name": "token", "in": "query" }, "basicAuth": { "type": "basic" }, "clientTokenHeader": { "type": "apiKey", "name": "X-Gotify-Key", "in": "header" }, "clientTokenQuery": { "type": "apiKey", "name": "token", "in": "query" } } }