# Gotify REST-API. This is the documentation of the Gotify REST-API. ## Authentication In Gotify there are two token types: __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) __appToken__: an application is something that sends messages (f.ex. this token should be used for a shell script) The token can be transmitted in a header named `X-Gotify-Key`, in a query parameter named `token` or through a header named `Authorization` with the value prefixed with `Bearer` (Ex. `Bearer randomtoken`). There is also the possibility to authenticate through basic auth, this should only be used for creating a clientToken. \--- Found a bug or have some questions? [Create an issue on GitHub](https://github.com/gotify/server/issues) Version: 2.1.0 Authentication: - appTokenAuthorizationHeader: apiKey, header Authorization. Enter an application token with the `Bearer` prefix, e.g. `Bearer Axxxxxxxxxx`. - appTokenHeader: apiKey, header X-Gotify-Key - appTokenQuery: apiKey, query token - basicAuth: http (basic) - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token ## Return all applications. `GET /application` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: Array Items: Reference: [Application](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/application-e7ad522ea3.md); Type: Application The Application holds information about an app which can send notifications. - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/application' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/application', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/application', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Create an application. `POST /application` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Request body: application/json (required) the application to add Type: ApplicationParams Params allowed to create or update Applications. Schema: [ApplicationParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/applicationparams-2c0d3c9325.md) - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 5 ``` - `description` (optional) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (optional) Type: string The sortKey for the application. Uses fractional indexing. Example: ```json "a1" ``` Responses: - 200: Ok Content type: application/json Type: Application The Application holds information about an app which can send notifications. Schema: [Application](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/application-e7ad522ea3.md) - `createdAt` (required) Type: string, date-time The date the application was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 4 ``` - `description` (required) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `id` (required) Type: integer, int64 The application id. readOnly: true Example: ```json 5 ``` - `image` (required) Type: string The image of the application. readOnly: true Example: ```json "image/image.jpeg" ``` - `internal` (required) Type: boolean Whether the application is an internal application. Internal applications should not be deleted. readOnly: true Example: ```json false ``` - `lastUsed` (optional) Type: string, date-time The last time the application token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (required) Type: string The sort key of this application. Uses fractional indexing. Example: ```json "a1" ``` - `token` (optional) Type: string The application token. Can be used as `appToken`. See Authentication. readOnly: true Example: ```json "AWH0wZ5r0Mbac.r" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/application' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }' ``` ### JavaScript ```javascript const body = `{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }`; const response = await fetch('http://localhost/application', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }''' response = requests.post( 'http://localhost/application', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Update an application. `PUT /application/{id}` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Request body: application/json (required) the application to update Type: ApplicationParams Params allowed to create or update Applications. Schema: [ApplicationParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/applicationparams-2c0d3c9325.md) - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 5 ``` - `description` (optional) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (optional) Type: string The sortKey for the application. Uses fractional indexing. Example: ```json "a1" ``` Responses: - 200: Ok Content type: application/json Type: Application The Application holds information about an app which can send notifications. Schema: [Application](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/application-e7ad522ea3.md) - `createdAt` (required) Type: string, date-time The date the application was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 4 ``` - `description` (required) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `id` (required) Type: integer, int64 The application id. readOnly: true Example: ```json 5 ``` - `image` (required) Type: string The image of the application. readOnly: true Example: ```json "image/image.jpeg" ``` - `internal` (required) Type: boolean Whether the application is an internal application. Internal applications should not be deleted. readOnly: true Example: ```json false ``` - `lastUsed` (optional) Type: string, date-time The last time the application token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (required) Type: string The sort key of this application. Uses fractional indexing. Example: ```json "a1" ``` - `token` (optional) Type: string The application token. Can be used as `appToken`. See Authentication. readOnly: true Example: ```json "AWH0wZ5r0Mbac.r" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X PUT 'http://localhost/application/0' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }' ``` ### JavaScript ```javascript const body = `{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }`; const response = await fetch('http://localhost/application/0', { method: 'PUT', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "defaultPriority": 5, "description": "Backup server for the interwebs", "name": "Backup Server", "sortKey": "a1" }''' response = requests.put( 'http://localhost/application/0', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete an application. `DELETE /application/{id}` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/application/0' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/application/0', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/application/0', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Upload an image for an application. `POST /application/{id}/image` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Request body: multipart/form-data (required) Type: object - `file` (required) Type: string, binary the application image Responses: - 200: Ok Content type: application/json Type: Application The Application holds information about an app which can send notifications. Schema: [Application](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/application-e7ad522ea3.md) - `createdAt` (required) Type: string, date-time The date the application was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 4 ``` - `description` (required) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `id` (required) Type: integer, int64 The application id. readOnly: true Example: ```json 5 ``` - `image` (required) Type: string The image of the application. readOnly: true Example: ```json "image/image.jpeg" ``` - `internal` (required) Type: boolean Whether the application is an internal application. Internal applications should not be deleted. readOnly: true Example: ```json false ``` - `lastUsed` (optional) Type: string, date-time The last time the application token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (required) Type: string The sort key of this application. Uses fractional indexing. Example: ```json "a1" ``` - `token` (optional) Type: string The application token. Can be used as `appToken`. See Authentication. readOnly: true Example: ```json "AWH0wZ5r0Mbac.r" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/application/0/image' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const form = new FormData(); const response = await fetch('http://localhost/application/0/image', { method: 'POST', headers: {"Authorization":"YOUR_TOKEN"}, body: form, }); console.log(await response.text()); ``` ### Python ```python import requests from contextlib import ExitStack with ExitStack() as stack: files = [ ] response = requests.request('POST', 'http://localhost/application/0/image', headers={"Authorization":"YOUR_TOKEN"}, files=files) print(response.text) ``` ## Deletes an image of an application. `DELETE /application/{id}/image` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/application/0/image' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/application/0/image', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/application/0/image', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Return all messages from a specific application. `GET /application/{id}/message` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 - `limit` (query, integer, optional) - the maximal amount of messages to return Type: integer default: 100 minimum: 1 maximum: 200 - `since` (query, integer, int64, optional) - return all messages with an ID less than this value Type: integer, int64 minimum: 0 Responses: - 200: Ok Content type: application/json Type: PagedMessages Wrapper for the paging and the messages. Schema: [PagedMessages](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/pagedmessages-21c696acff.md) - `messages` (required) Type: Array The messages. readOnly: true Items: Reference: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md); Type: Message The MessageExternal holds information about a message which was sent by an Application. - `paging` (required) Reference: [Paging](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/paging-a325388710.md); Type: Paging The Paging holds information about the limit and making requests to the next page. - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/application/0/message?limit=100' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/application/0/message?limit=100', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/application/0/message?limit=100', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Delete all messages from a specific application. `DELETE /application/{id}/message` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/application/0/message' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/application/0/message', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/application/0/message', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Perform security updates on an application. `PUT /application/{id}/security` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the application id Type: integer, int64 Request body: application/json (required) security update action descriptor Type: SecurityUpdateAction The SecurityUpdateAction describes the details of a requested security update. Schema: [SecurityUpdateAction](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/securityupdateaction-375b486776.md) - `regenerateToken` (optional) Type: boolean Whether to regenerate the token. Your client token must be elevated to perform this action. Example: ```json true ``` Responses: - 200: Ok Content type: application/json Type: SecurityUpdateActionResponse The SecurityUpdateActionResponse holds information about the response to a security update request. Schema: [SecurityUpdateActionResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/securityupdateactionresponse-2441fcf8c2.md) - `regenerateToken` (optional) Reference: [RegenerateTokenResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/regeneratetokenresponse-9c3be93e5e.md); Type: RegenerateTokenResponse The RegenerateTokenResponse holds information about the response to the regenerate token action. - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X PUT 'http://localhost/application/0/security' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "regenerateToken": true }' ``` ### JavaScript ```javascript const body = `{ "regenerateToken": true }`; const response = await fetch('http://localhost/application/0/security', { method: 'PUT', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "regenerateToken": true }''' response = requests.put( 'http://localhost/application/0/security', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Authenticate via basic auth and create a session. `POST /auth/local/login` Authentication (security requirement alternatives): ```json [ { "basicAuth": [] } ] ``` - basicAuth: http (basic) Request body: application/x-www-form-urlencoded (required) Type: object - `name` (required) Type: string the client name to create Responses: - 200: Ok Content type: application/json Type: CurrentUser CurrentUserExternal Model Schema: [CurrentUser](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/currentuser-785d418b2d.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `clientId` (optional) Type: integer, int64 The client id of the current session. readOnly: true Example: ```json 5 ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `elevatedUntil` (optional) Type: string, date-time The time until which the session is elevated. readOnly: true - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/auth/local/login' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-raw 'name=string' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/auth/local/login', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/x-www-form-urlencoded', }, body: 'name=string', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.post( 'http://localhost/auth/local/login', data='name=string'.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/x-www-form-urlencoded', }, ) print(response.text) ``` ## End the current session. `POST /auth/logout` Clears the session cookie and deletes the associated client. Authentication (security requirement alternatives): ```json [ { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/auth/logout' \ -H 'X-Gotify-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/auth/logout', { method: 'POST', headers: { 'X-Gotify-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.post( 'http://localhost/auth/logout', headers={ 'X-Gotify-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Handle the OIDC provider callback (browser). `GET /auth/oidc/callback` Exchanges the authorization code for tokens, resolves the user, creates a gotify client, sets a session cookie, and redirects to the UI. Authentication: no security requirement declared for this operation. Parameters: - `code` (query, string, required) - the authorization code from the OIDC provider Type: string - `state` (query, string, required) - the state parameter for CSRF protection Type: string Responses: - 200: ok - 307: Redirect to UI - default: Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/auth/oidc/callback?code=string&state=string' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/auth/oidc/callback?code=string&state=string', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/auth/oidc/callback?code=string&state=string') print(response.text) ``` ## Start the OIDC flow to elevate an existing client session (browser). `GET /auth/oidc/elevate` Redirects the user to the OIDC provider's authorization endpoint. After successful authentication, the referenced client session is elevated for the requested duration. Authentication: no security requirement declared for this operation. Parameters: - `id` (query, integer, int64, required) - the client id to elevate Type: integer, int64 - `durationSeconds` (query, integer, required) - how long the elevation should last, in seconds Type: integer Responses: - 302: Redirect to OIDC provider - default: Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/auth/oidc/elevate?id=0&durationSeconds=0' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/auth/oidc/elevate?id=0&durationSeconds=0', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/auth/oidc/elevate?id=0&durationSeconds=0') print(response.text) ``` ## Initiate the OIDC authorization flow for a native app. `POST /auth/oidc/external/authorize` The app generates a PKCE code_verifier and code_challenge, then calls this endpoint. The server forwards the code_challenge to the OIDC provider and returns the authorization URL for the app to open in a browser. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: OIDCExternalAuthorizeRequest Used to initiate the OIDC authorization flow for an external client. Schema: [OIDCExternalAuthorizeRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternalauthorizerequest-4b92299fe4.md) - `code_challenge` (required) Type: string The PKCE code challenge (S256). Example: ```json "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" ``` - `name` (required) Type: string The client name to display in gotify. Example: ```json "Android Phone" ``` - `redirect_uri` (required) Type: string The app's redirect URI. Example: ```json "gotify://oidc/callback" ``` Responses: - 200: Ok Content type: application/json Type: OIDCExternalAuthorizeResponse Returned after initiating the OIDC authorization flow. Schema: [OIDCExternalAuthorizeResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternalauthorizeresponse-332c3aad7d.md) - `authorize_url` (required) Type: string The URL to open in the browser to authenticate with the OIDC provider. Example: ```json "https://auth.example.com/authorize?client_id=gotify&..." ``` - `state` (required) Type: string The state parameter to send back with the token exchange request. Example: ```json "Android Phone:a1b2c3d4e5f6" ``` - default: Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/auth/oidc/external/authorize' \ -H 'Content-Type: application/json' \ --data-raw '{ "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "name": "Android Phone", "redirect_uri": "gotify://oidc/callback" }' ``` ### JavaScript ```javascript const body = `{ "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "name": "Android Phone", "redirect_uri": "gotify://oidc/callback" }`; const response = await fetch('http://localhost/auth/oidc/external/authorize', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "name": "Android Phone", "redirect_uri": "gotify://oidc/callback" }''' response = requests.post( 'http://localhost/auth/oidc/external/authorize', data=body.encode('utf-8'), headers={ 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Exchange an authorization code for a gotify client token. `POST /auth/oidc/external/token` After the user authenticates with the OIDC provider and the app receives the authorization code via redirect, the app calls this endpoint with the code and PKCE code_verifier. The server exchanges the code with the OIDC provider and returns a gotify client token. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: OIDCExternalTokenRequest Used to exchange an authorization code for a gotify client token. Schema: [OIDCExternalTokenRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternaltokenrequest-1288c069e8.md) - `code` (required) Type: string The authorization code from the OIDC provider. - `code_verifier` (required) Type: string The PKCE code verifier. Example: ```json "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" ``` - `state` (required) Type: string The state from the authorize response. Example: ```json "Android Phone:a1b2c3d4e5f6" ``` Responses: - 200: Ok Content type: application/json Type: OIDCExternalTokenResponse Returned after a successful token exchange. Schema: [OIDCExternalTokenResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternaltokenresponse-569315d693.md) - `token` (required) Type: string The gotify client token for API authentication. Example: ```json "CWH0wZ5r0Mbac.r" ``` - `user` (required) Reference: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md); Type: User The User holds information about permission and other stuff. - default: Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/auth/oidc/external/token' \ -H 'Content-Type: application/json' \ --data-raw '{ "code": "string", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "state": "Android Phone:a1b2c3d4e5f6" }' ``` ### JavaScript ```javascript const body = `{ "code": "string", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "state": "Android Phone:a1b2c3d4e5f6" }`; const response = await fetch('http://localhost/auth/oidc/external/token', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "code": "string", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "state": "Android Phone:a1b2c3d4e5f6" }''' response = requests.post( 'http://localhost/auth/oidc/external/token', data=body.encode('utf-8'), headers={ 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Start the OIDC login flow (browser). `GET /auth/oidc/login` Redirects the user to the OIDC provider's authorization endpoint. After authentication, the provider redirects back to the callback endpoint. Authentication: no security requirement declared for this operation. Parameters: - `name` (query, string, required) - the client name to create after login Type: string Responses: - 302: Redirect to OIDC provider - default: Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/auth/oidc/login?name=string' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/auth/oidc/login?name=string', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/auth/oidc/login?name=string') print(response.text) ``` ## Return all clients. `GET /client` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: Array Items: Reference: [Client](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/client-0c77fe09ab.md); Type: Client The Client holds information about a device which can receive notifications (and other stuff). - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/client' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/client', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/client', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Create a client. `POST /client` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Request body: application/json (required) the client to add Type: ClientParams Params allowed to create or update Clients. Schema: [ClientParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/clientparams-c648cc5c72.md) - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires. Example: ```json 2592000 ``` - `name` (required) Type: string The client name Example: ```json "My Client" ``` Responses: - 200: Ok Content type: application/json Type: Client The Client holds information about a device which can receive notifications (and other stuff). Schema: [Client](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/client-0c77fe09ab.md) - `createdAt` (required) Type: string, date-time The date the client was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `elevatedUntil` (optional) Type: string, date-time The time until which this client's session is elevated. readOnly: true - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 means the client never expires. Example: ```json 2592000 ``` - `expiresAt` (optional) Type: string, date-time The time at which this client will expire due to inactivity, or null if it never expires. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The client id. readOnly: true Example: ```json 5 ``` - `lastUsed` (optional) Type: string, date-time The last time the client token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The client name. This is how the client should be displayed to the user. Example: ```json "Android Phone" ``` - `token` (optional) Type: string The client token. Can be used as `clientToken`. See Authentication. readOnly: true Example: ```json "CWH0wZ5r0Mbac.r" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/client' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }' ``` ### JavaScript ```javascript const body = `{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }`; const response = await fetch('http://localhost/client', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }''' response = requests.post( 'http://localhost/client', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Update a client. `PUT /client/{id}` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the client id Type: integer, int64 Request body: application/json (required) the client to update Type: ClientParams Params allowed to create or update Clients. Schema: [ClientParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/clientparams-c648cc5c72.md) - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires. Example: ```json 2592000 ``` - `name` (required) Type: string The client name Example: ```json "My Client" ``` Responses: - 200: Ok Content type: application/json Type: Client The Client holds information about a device which can receive notifications (and other stuff). Schema: [Client](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/client-0c77fe09ab.md) - `createdAt` (required) Type: string, date-time The date the client was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `elevatedUntil` (optional) Type: string, date-time The time until which this client's session is elevated. readOnly: true - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 means the client never expires. Example: ```json 2592000 ``` - `expiresAt` (optional) Type: string, date-time The time at which this client will expire due to inactivity, or null if it never expires. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The client id. readOnly: true Example: ```json 5 ``` - `lastUsed` (optional) Type: string, date-time The last time the client token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The client name. This is how the client should be displayed to the user. Example: ```json "Android Phone" ``` - `token` (optional) Type: string The client token. Can be used as `clientToken`. See Authentication. readOnly: true Example: ```json "CWH0wZ5r0Mbac.r" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X PUT 'http://localhost/client/0' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }' ``` ### JavaScript ```javascript const body = `{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }`; const response = await fetch('http://localhost/client/0', { method: 'PUT', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "expiresAfterInactivitySeconds": 2592000, "name": "My Client" }''' response = requests.put( 'http://localhost/client/0', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete a client. `DELETE /client/{id}` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the client id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/client/0' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/client/0', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/client/0', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Elevate a client session. `POST /client/{id}/elevate` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the client id Type: integer, int64 Request body: application/json (required) the elevation request Type: ElevateRequest Schema: [ElevateRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/elevaterequest-1bf9eaf4d4.md) - `durationSeconds` (required) Type: integer, int64 How long the elevation should last, in seconds. Example: ```json 900 ``` Responses: - 204: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/client/0/elevate' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "durationSeconds": 900 }' ``` ### JavaScript ```javascript const body = `{ "durationSeconds": 900 }`; const response = await fetch('http://localhost/client/0/elevate', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "durationSeconds": 900 }''' response = requests.post( 'http://localhost/client/0/elevate', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Return the current user. `GET /current/user` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: User The User holds information about permission and other stuff. Schema: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/current/user' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/current/user', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/current/user', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Update the password of the current user. `POST /current/user/password` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Request body: application/json (required) the user Type: UserPass The Password for updating the user. Schema: [UserPass](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/userpass-d0d4f76c2b.md) - `pass` (required) Type: string The user password. For login. Example: ```json "nrocinu" ``` Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/current/user/password' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "pass": "nrocinu" }' ``` ### JavaScript ```javascript const body = `{ "pass": "nrocinu" }`; const response = await fetch('http://localhost/current/user/password', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "pass": "nrocinu" }''' response = requests.post( 'http://localhost/current/user/password', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Get gotify information. `GET /gotifyinfo` Authentication: no security requirement declared for this operation. Responses: - 200: Ok Content type: application/json Type: GotifyInfo GotifyInfo Model Schema: [GotifyInfo](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/gotifyinfo-f84dc581fe.md) - `localAuth` (required) Type: boolean If local authentication is enabled. Example: ```json true ``` - `oidc` (required) Type: boolean If oidc is enabled. Example: ```json true ``` - `oidcAutoRedirect` (required) Type: boolean If the WebUI should automatically redirect to the OIDC identity provider instead of showing the login page. Example: ```json false ``` - `oidcIdpName` (required) Type: string Name of the OIDC identity provider. Example: ```json "OIDC" ``` - `register` (required) Type: boolean If registration is enabled. Example: ```json true ``` - `version` (required) Type: string The current version. Example: ```json "5.2.6" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/gotifyinfo' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/gotifyinfo', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/gotifyinfo') print(response.text) ``` ## Get health information. `GET /health` Authentication: no security requirement declared for this operation. Responses: - 200: Ok Content type: application/json Type: Health Health represents how healthy the application is. Schema: [Health](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/health-55898449eb.md) - `database` (required) Type: string The health of the database connection. Example: ```json "green" ``` - `health` (required) Type: string The health of the overall application. Example: ```json "green" ``` - 500: Ok Content type: application/json Type: Health Health represents how healthy the application is. Schema: [Health](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/health-55898449eb.md) - `database` (required) Type: string The health of the database connection. Example: ```json "green" ``` - `health` (required) Type: string The health of the overall application. Example: ```json "green" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/health' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/health', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/health') print(response.text) ``` ## Return all messages. `GET /message` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `limit` (query, integer, optional) - the maximal amount of messages to return Type: integer default: 100 minimum: 1 maximum: 200 - `since` (query, integer, int64, optional) - return all messages with an ID less than this value Type: integer, int64 minimum: 0 Responses: - 200: Ok Content type: application/json Type: PagedMessages Wrapper for the paging and the messages. Schema: [PagedMessages](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/pagedmessages-21c696acff.md) - `messages` (required) Type: Array The messages. readOnly: true Items: Reference: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md); Type: Message The MessageExternal holds information about a message which was sent by an Application. - `paging` (required) Reference: [Paging](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/paging-a325388710.md); Type: Paging The Paging holds information about the limit and making requests to the next page. - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/message?limit=100' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/message?limit=100', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/message?limit=100', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Create a message. `POST /message` __NOTE__: When authenticating with a client token or basic auth, the request body must include "appid" referencing an application owned by the authenticated user. When authenticating with an application token, the application is derived from the token and any "appid" in the body is ignored. Authentication (security requirement alternatives): ```json [ { "appTokenAuthorizationHeader": [] }, { "appTokenHeader": [] }, { "appTokenQuery": [] }, { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - appTokenAuthorizationHeader: apiKey, header Authorization. Enter an application token with the `Bearer` prefix, e.g. `Bearer Axxxxxxxxxx`. - appTokenHeader: apiKey, header X-Gotify-Key - appTokenQuery: apiKey, query token - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Request body: application/json (required) the message to add Type: CreateMessage The CreateMessage holds information about a message that will be sent. Schema: [CreateMessage](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/createmessage-a2e15bf534.md) - `appid` (optional) Type: integer, int64 The application id that send this message. Always set when returned via the API. Example: ```json 5 ``` - `extras` (optional) Type: object The extra data sent along the message. The extra fields are stored in a key-value scheme. Only accepted in CreateMessage requests with application/json content-type. The keys should be in the following format: <top-namespace>::[<sub-namespace>::]<action> These namespaces are reserved and might be used in the official clients: gotify android ios web server client. Do not use them for other purposes. Example: ```json { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } } ``` Additional properties: Type: any - `message` (required) Type: string The message. Markdown (excluding html) is allowed. Example: ```json "**Backup** was successfully finished." ``` - `priority` (optional) Type: integer, int64 The priority of the message. If unset, then the default priority of the application will be used. Example: ```json 2 ``` - `title` (optional) Type: string The title of the message. Example: ```json "Backup" ``` Responses: - 200: Ok Content type: application/json Type: Message The MessageExternal holds information about a message which was sent by an Application. Schema: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md) - `appid` (required) Type: integer, int64 The application id that send this message. readOnly: true Example: ```json 5 ``` - `date` (required) Type: string, date-time The date the message was created. readOnly: true Example: ```json "2018-02-27T19:36:10.5045044+01:00" ``` - `extras` (optional) Type: object The extra data sent along the message. The extra fields are stored in a key-value scheme. Only accepted in CreateMessage requests with application/json content-type. The keys should be in the following format: <top-namespace>::[<sub-namespace>::]<action> These namespaces are reserved and might be used in the official clients: gotify android ios web server client. Do not use them for other purposes. Example: ```json { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } } ``` Additional properties: Type: any - `id` (required) Type: integer, int64 The message id. readOnly: true Example: ```json 25 ``` - `message` (required) Type: string The message. Markdown (excluding html) is allowed. Example: ```json "**Backup** was successfully finished." ``` - `priority` (optional) Type: integer, int64 The priority of the message. If unset, then the default priority of the application will be used. Example: ```json 2 ``` - `title` (optional) Type: string The title of the message. Example: ```json "Backup" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/message' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "appid": 5, "extras": { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } }, "message": "**Backup** was successfully finished.", "priority": 2, "title": "Backup" }' ``` ### JavaScript ```javascript const body = `{ "appid": 5, "extras": { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } }, "message": "**Backup** was successfully finished.", "priority": 2, "title": "Backup" }`; const response = await fetch('http://localhost/message', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "appid": 5, "extras": { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } }, "message": "**Backup** was successfully finished.", "priority": 2, "title": "Backup" }''' response = requests.post( 'http://localhost/message', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete all messages. `DELETE /message` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/message' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/message', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/message', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Deletes a message with an id. `DELETE /message/{id}` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the message id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/message/0' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/message/0', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/message/0', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Return all plugins. `GET /plugin` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: Array Items: Reference: [PluginConf](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/pluginconf-f74213b140.md); Type: PluginConf Holds information about a plugin instance for one user. - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/plugin' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/plugin', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Get YAML configuration for Configurer plugin. `GET /plugin/{id}/config` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the plugin id Type: integer, int64 Responses: - 200: Ok Content type: application/x-yaml Type: object plugin configuration - 400: Bad Request Content type: application/x-yaml Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/x-yaml Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/x-yaml Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/x-yaml Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/x-yaml Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/plugin/0/config' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin/0/config', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/plugin/0/config', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Update YAML configuration for Configurer plugin. `POST /plugin/{id}/config` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the plugin id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/plugin/0/config' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin/0/config', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.post( 'http://localhost/plugin/0/config', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Disable a plugin. `POST /plugin/{id}/disable` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the plugin id Type: integer, int64 Responses: - 200: Ok - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/plugin/0/disable' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin/0/disable', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.post( 'http://localhost/plugin/0/disable', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Get display info for a Displayer plugin. `GET /plugin/{id}/display` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the plugin id Type: integer, int64 Responses: - 200: Ok Content type: application/json Type: string - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/plugin/0/display' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin/0/display', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/plugin/0/display', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Enable a plugin. `POST /plugin/{id}/enable` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the plugin id Type: integer, int64 Responses: - 200: Ok - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Internal Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/plugin/0/enable' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/plugin/0/enable', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.post( 'http://localhost/plugin/0/enable', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Websocket, return newly created messages. `GET /stream` Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: Message The MessageExternal holds information about a message which was sent by an Application. Schema: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md) - `appid` (required) Type: integer, int64 The application id that send this message. readOnly: true Example: ```json 5 ``` - `date` (required) Type: string, date-time The date the message was created. readOnly: true Example: ```json "2018-02-27T19:36:10.5045044+01:00" ``` - `extras` (optional) Type: object The extra data sent along the message. The extra fields are stored in a key-value scheme. Only accepted in CreateMessage requests with application/json content-type. The keys should be in the following format: <top-namespace>::[<sub-namespace>::]<action> These namespaces are reserved and might be used in the official clients: gotify android ios web server client. Do not use them for other purposes. Example: ```json { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } } ``` Additional properties: Type: any - `id` (required) Type: integer, int64 The message id. readOnly: true Example: ```json 25 ``` - `message` (required) Type: string The message. Markdown (excluding html) is allowed. Example: ```json "**Backup** was successfully finished." ``` - `priority` (optional) Type: integer, int64 The priority of the message. If unset, then the default priority of the application will be used. Example: ```json 2 ``` - `title` (optional) Type: string The title of the message. Example: ```json "Backup" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 500: Server Error Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/stream' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/stream', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/stream', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Return all users. `GET /user` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Responses: - 200: Ok Content type: application/json Type: Array Items: Reference: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md); Type: User The User holds information about permission and other stuff. - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/user' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/user', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/user', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Create a user. `POST /user` With enabled registration: non admin users can be created without authentication. With disabled registrations: users can only be created by admin users. Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Request body: application/json (required) the user to add Type: CreateUserExternal Used for user creation. Schema: [CreateUserExternal](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/createuserexternal-8b170a1f76.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - `pass` (required) Type: string The user password. For login. Example: ```json "nrocinu" ``` Responses: - 200: Ok Content type: application/json Type: User The User holds information about permission and other stuff. Schema: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/user' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "admin": true, "name": "unicorn", "pass": "nrocinu" }' ``` ### JavaScript ```javascript const body = `{ "admin": true, "name": "unicorn", "pass": "nrocinu" }`; const response = await fetch('http://localhost/user', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "admin": true, "name": "unicorn", "pass": "nrocinu" }''' response = requests.post( 'http://localhost/user', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Get a user. `GET /user/{id}` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the user id Type: integer, int64 Responses: - 200: Ok Content type: application/json Type: User The User holds information about permission and other stuff. Schema: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/user/0' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/user/0', { method: 'GET', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'http://localhost/user/0', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Update a user. `POST /user/{id}` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the user id Type: integer, int64 Request body: application/json (required) the updated user Type: UpdateUserExternal Used for updating a user. Schema: [UpdateUserExternal](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/updateuserexternal-2d72e290fe.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - `pass` (optional) Type: string The user password. For login. Empty for using old password Example: ```json "nrocinu" ``` Responses: - 200: Ok Content type: application/json Type: User The User holds information about permission and other stuff. Schema: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X POST 'http://localhost/user/0' \ -H 'Authorization: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "admin": true, "name": "unicorn", "pass": "nrocinu" }' ``` ### JavaScript ```javascript const body = `{ "admin": true, "name": "unicorn", "pass": "nrocinu" }`; const response = await fetch('http://localhost/user/0', { method: 'POST', headers: { 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "admin": true, "name": "unicorn", "pass": "nrocinu" }''' response = requests.post( 'http://localhost/user/0', data=body.encode('utf-8'), headers={ 'Authorization': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Deletes a user. `DELETE /user/{id}` Requires elevated authentication. Authentication (security requirement alternatives): ```json [ { "clientTokenAuthorizationHeader": [] }, { "clientTokenHeader": [] }, { "clientTokenQuery": [] }, { "basicAuth": [] } ] ``` - clientTokenAuthorizationHeader: apiKey, header Authorization. Enter a client token with the `Bearer` prefix, e.g. `Bearer Cxxxxxxxxxx`. - clientTokenHeader: apiKey, header X-Gotify-Key - clientTokenQuery: apiKey, query token - basicAuth: http (basic) Parameters: - `id` (path, integer, int64, required) - the user id Type: integer, int64 Responses: - 200: Ok - 400: Bad Request Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 401: Unauthorized Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 403: Forbidden Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` - 404: Not Found Content type: application/json Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## Examples ### cURL ```bash curl -X DELETE 'http://localhost/user/0' \ -H 'Authorization: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/user/0', { method: 'DELETE', headers: { 'Authorization': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'http://localhost/user/0', headers={ 'Authorization': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Get version information. `GET /version` Authentication: no security requirement declared for this operation. Responses: - 200: Ok Content type: application/json Type: VersionInfo VersionInfo Model Schema: [VersionInfo](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/versioninfo-641558380f.md) - `buildDate` (required) Type: string The date on which this binary was built. Example: ```json "2018-02-27T19:36:10.5045044+01:00" ``` - `commit` (required) Type: string The git commit hash on which this binary was built. Example: ```json "ae9512b6b6feea56a110d59a3353ea3b9c293864" ``` - `version` (required) Type: string The current version. Example: ```json "5.2.6" ``` ## Examples ### cURL ```bash curl -X GET 'http://localhost/version' ``` ### JavaScript ```javascript const response = await fetch('http://localhost/version', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('http://localhost/version') print(response.text) ``` ## Application Type: Application The Application holds information about an app which can send notifications. Schema: [Application](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/application-e7ad522ea3.md) - `createdAt` (required) Type: string, date-time The date the application was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 4 ``` - `description` (required) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `id` (required) Type: integer, int64 The application id. readOnly: true Example: ```json 5 ``` - `image` (required) Type: string The image of the application. readOnly: true Example: ```json "image/image.jpeg" ``` - `internal` (required) Type: boolean Whether the application is an internal application. Internal applications should not be deleted. readOnly: true Example: ```json false ``` - `lastUsed` (optional) Type: string, date-time The last time the application token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (required) Type: string The sort key of this application. Uses fractional indexing. Example: ```json "a1" ``` - `token` (optional) Type: string The application token. Can be used as `appToken`. See Authentication. readOnly: true Example: ```json "AWH0wZ5r0Mbac.r" ``` ## ApplicationParams Type: ApplicationParams Params allowed to create or update Applications. Schema: [ApplicationParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/applicationparams-2c0d3c9325.md) - `defaultPriority` (optional) Type: integer, int64 The default priority of messages sent by this application. Defaults to 0. Example: ```json 5 ``` - `description` (optional) Type: string The description of the application. Example: ```json "Backup server for the interwebs" ``` - `name` (required) Type: string The application name. This is how the application should be displayed to the user. Example: ```json "Backup Server" ``` - `sortKey` (optional) Type: string The sortKey for the application. Uses fractional indexing. Example: ```json "a1" ``` ## Client Type: Client The Client holds information about a device which can receive notifications (and other stuff). Schema: [Client](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/client-0c77fe09ab.md) - `createdAt` (required) Type: string, date-time The date the client was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `elevatedUntil` (optional) Type: string, date-time The time until which this client's session is elevated. readOnly: true - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 means the client never expires. Example: ```json 2592000 ``` - `expiresAt` (optional) Type: string, date-time The time at which this client will expire due to inactivity, or null if it never expires. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The client id. readOnly: true Example: ```json 5 ``` - `lastUsed` (optional) Type: string, date-time The last time the client token was used. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `name` (required) Type: string The client name. This is how the client should be displayed to the user. Example: ```json "Android Phone" ``` - `token` (optional) Type: string The client token. Can be used as `clientToken`. See Authentication. readOnly: true Example: ```json "CWH0wZ5r0Mbac.r" ``` ## ClientParams Type: ClientParams Params allowed to create or update Clients. Schema: [ClientParams](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/clientparams-c648cc5c72.md) - `expiresAfterInactivitySeconds` (optional) Type: integer, int64 The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires. Example: ```json 2592000 ``` - `name` (required) Type: string The client name Example: ```json "My Client" ``` ## CreateMessage Type: CreateMessage The CreateMessage holds information about a message that will be sent. Schema: [CreateMessage](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/createmessage-a2e15bf534.md) - `appid` (optional) Type: integer, int64 The application id that send this message. Always set when returned via the API. Example: ```json 5 ``` - `extras` (optional) Type: object The extra data sent along the message. The extra fields are stored in a key-value scheme. Only accepted in CreateMessage requests with application/json content-type. The keys should be in the following format: <top-namespace>::[<sub-namespace>::]<action> These namespaces are reserved and might be used in the official clients: gotify android ios web server client. Do not use them for other purposes. Example: ```json { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } } ``` Additional properties: Type: any - `message` (required) Type: string The message. Markdown (excluding html) is allowed. Example: ```json "**Backup** was successfully finished." ``` - `priority` (optional) Type: integer, int64 The priority of the message. If unset, then the default priority of the application will be used. Example: ```json 2 ``` - `title` (optional) Type: string The title of the message. Example: ```json "Backup" ``` ## CreateUserExternal Type: CreateUserExternal Used for user creation. Schema: [CreateUserExternal](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/createuserexternal-8b170a1f76.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - `pass` (required) Type: string The user password. For login. Example: ```json "nrocinu" ``` ## CurrentUser Type: CurrentUser CurrentUserExternal Model Schema: [CurrentUser](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/currentuser-785d418b2d.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `clientId` (optional) Type: integer, int64 The client id of the current session. readOnly: true Example: ```json 5 ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `elevatedUntil` (optional) Type: string, date-time The time until which the session is elevated. readOnly: true - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` ## ElevateRequest Type: ElevateRequest Schema: [ElevateRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/elevaterequest-1bf9eaf4d4.md) - `durationSeconds` (required) Type: integer, int64 How long the elevation should last, in seconds. Example: ```json 900 ``` ## Error Type: Error The Error contains error relevant information. Schema: [Error](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/error-54a0e8c17e.md) - `error` (required) Type: string The general error message Example: ```json "Unauthorized" ``` - `errorCode` (required) Type: integer, int64 The http error code. Example: ```json 401 ``` - `errorDescription` (required) Type: string The http error code. Example: ```json "you need to provide a valid access token or user credentials to access this api" ``` ## GotifyInfo Type: GotifyInfo GotifyInfo Model Schema: [GotifyInfo](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/gotifyinfo-f84dc581fe.md) - `localAuth` (required) Type: boolean If local authentication is enabled. Example: ```json true ``` - `oidc` (required) Type: boolean If oidc is enabled. Example: ```json true ``` - `oidcAutoRedirect` (required) Type: boolean If the WebUI should automatically redirect to the OIDC identity provider instead of showing the login page. Example: ```json false ``` - `oidcIdpName` (required) Type: string Name of the OIDC identity provider. Example: ```json "OIDC" ``` - `register` (required) Type: boolean If registration is enabled. Example: ```json true ``` - `version` (required) Type: string The current version. Example: ```json "5.2.6" ``` ## Health Type: Health Health represents how healthy the application is. Schema: [Health](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/health-55898449eb.md) - `database` (required) Type: string The health of the database connection. Example: ```json "green" ``` - `health` (required) Type: string The health of the overall application. Example: ```json "green" ``` ## Message Type: Message The MessageExternal holds information about a message which was sent by an Application. Schema: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md) - `appid` (required) Type: integer, int64 The application id that send this message. readOnly: true Example: ```json 5 ``` - `date` (required) Type: string, date-time The date the message was created. readOnly: true Example: ```json "2018-02-27T19:36:10.5045044+01:00" ``` - `extras` (optional) Type: object The extra data sent along the message. The extra fields are stored in a key-value scheme. Only accepted in CreateMessage requests with application/json content-type. The keys should be in the following format: <top-namespace>::[<sub-namespace>::]<action> These namespaces are reserved and might be used in the official clients: gotify android ios web server client. Do not use them for other purposes. Example: ```json { "home::appliances::lighting::on": { "brightness": 15 }, "home::appliances::thermostat::change_temperature": { "temperature": 23 } } ``` Additional properties: Type: any - `id` (required) Type: integer, int64 The message id. readOnly: true Example: ```json 25 ``` - `message` (required) Type: string The message. Markdown (excluding html) is allowed. Example: ```json "**Backup** was successfully finished." ``` - `priority` (optional) Type: integer, int64 The priority of the message. If unset, then the default priority of the application will be used. Example: ```json 2 ``` - `title` (optional) Type: string The title of the message. Example: ```json "Backup" ``` ## OIDCExternalAuthorizeRequest Type: OIDCExternalAuthorizeRequest Used to initiate the OIDC authorization flow for an external client. Schema: [OIDCExternalAuthorizeRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternalauthorizerequest-4b92299fe4.md) - `code_challenge` (required) Type: string The PKCE code challenge (S256). Example: ```json "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" ``` - `name` (required) Type: string The client name to display in gotify. Example: ```json "Android Phone" ``` - `redirect_uri` (required) Type: string The app's redirect URI. Example: ```json "gotify://oidc/callback" ``` ## OIDCExternalAuthorizeResponse Type: OIDCExternalAuthorizeResponse Returned after initiating the OIDC authorization flow. Schema: [OIDCExternalAuthorizeResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternalauthorizeresponse-332c3aad7d.md) - `authorize_url` (required) Type: string The URL to open in the browser to authenticate with the OIDC provider. Example: ```json "https://auth.example.com/authorize?client_id=gotify&..." ``` - `state` (required) Type: string The state parameter to send back with the token exchange request. Example: ```json "Android Phone:a1b2c3d4e5f6" ``` ## OIDCExternalTokenRequest Type: OIDCExternalTokenRequest Used to exchange an authorization code for a gotify client token. Schema: [OIDCExternalTokenRequest](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternaltokenrequest-1288c069e8.md) - `code` (required) Type: string The authorization code from the OIDC provider. - `code_verifier` (required) Type: string The PKCE code verifier. Example: ```json "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" ``` - `state` (required) Type: string The state from the authorize response. Example: ```json "Android Phone:a1b2c3d4e5f6" ``` ## OIDCExternalTokenResponse Type: OIDCExternalTokenResponse Returned after a successful token exchange. Schema: [OIDCExternalTokenResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/oidcexternaltokenresponse-569315d693.md) - `token` (required) Type: string The gotify client token for API authentication. Example: ```json "CWH0wZ5r0Mbac.r" ``` - `user` (required) Reference: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md); Type: User The User holds information about permission and other stuff. ## PagedMessages Type: PagedMessages Wrapper for the paging and the messages. Schema: [PagedMessages](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/pagedmessages-21c696acff.md) - `messages` (required) Type: Array The messages. readOnly: true Items: Reference: [Message](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/message-2f77668a9d.md); Type: Message The MessageExternal holds information about a message which was sent by an Application. - `paging` (required) Reference: [Paging](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/paging-a325388710.md); Type: Paging The Paging holds information about the limit and making requests to the next page. ## Paging Type: Paging The Paging holds information about the limit and making requests to the next page. Schema: [Paging](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/paging-a325388710.md) - `limit` (required) Type: integer, int64 The limit of the messages for the current request. minimum: 1 maximum: 200 readOnly: true Example: ```json 123 ``` - `next` (optional) Type: string The relative path for the next page. Empty/Null when no next page is available. Should be combined with the gotify base url. readOnly: true Example: ```json "/message?limit=50&since=123456" ``` - `since` (required) Type: integer, int64 The ID of the last message returned in the current request. Use this as alternative to the next link. minimum: 0 readOnly: true Example: ```json 5 ``` - `size` (required) Type: integer, int64 The amount of messages that got returned in the current request. readOnly: true Example: ```json 5 ``` ## PluginConf Type: PluginConf Holds information about a plugin instance for one user. Schema: [PluginConf](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/pluginconf-f74213b140.md) - `author` (optional) Type: string The author of the plugin. readOnly: true Example: ```json "jmattheis" ``` - `capabilities` (required) Type: Array Capabilities the plugin provides Example: ```json [ "webhook", "display" ] ``` Items: Type: string - `createdAt` (required) Type: string, date-time The date the plugin was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `enabled` (required) Type: boolean Whether the plugin instance is enabled. Example: ```json true ``` - `id` (required) Type: integer, int64 The plugin id. readOnly: true Example: ```json 25 ``` - `license` (optional) Type: string The license of the plugin. readOnly: true Example: ```json "MIT" ``` - `modulePath` (required) Type: string The module path of the plugin. readOnly: true Example: ```json "github.com/gotify/server/plugin/example/echo" ``` - `name` (required) Type: string The plugin name. readOnly: true Example: ```json "RSS poller" ``` - `token` (required) Type: string The user name. For login. Example: ```json "P1234" ``` - `website` (optional) Type: string The website of the plugin. readOnly: true Example: ```json "gotify.net" ``` ## RegenerateTokenResponse Type: RegenerateTokenResponse The RegenerateTokenResponse holds information about the response to the regenerate token action. Schema: [RegenerateTokenResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/regeneratetokenresponse-9c3be93e5e.md) - `token` (required) Type: string The new token. readOnly: true Example: ```json "gtfya.e2NcJK7AenXBPIRB3S03JsBlmy0V6xP8h0hwSiAJae8" ``` ## SecurityUpdateAction Type: SecurityUpdateAction The SecurityUpdateAction describes the details of a requested security update. Schema: [SecurityUpdateAction](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/securityupdateaction-375b486776.md) - `regenerateToken` (optional) Type: boolean Whether to regenerate the token. Your client token must be elevated to perform this action. Example: ```json true ``` ## SecurityUpdateActionResponse Type: SecurityUpdateActionResponse The SecurityUpdateActionResponse holds information about the response to a security update request. Schema: [SecurityUpdateActionResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/securityupdateactionresponse-2441fcf8c2.md) - `regenerateToken` (optional) Reference: [RegenerateTokenResponse](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/regeneratetokenresponse-9c3be93e5e.md); Type: RegenerateTokenResponse The RegenerateTokenResponse holds information about the response to the regenerate token action. ## UpdateUserExternal Type: UpdateUserExternal Used for updating a user. Schema: [UpdateUserExternal](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/updateuserexternal-2d72e290fe.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` - `pass` (optional) Type: string The user password. For login. Empty for using old password Example: ```json "nrocinu" ``` ## User Type: User The User holds information about permission and other stuff. Schema: [User](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/user-b512d97e7c.md) - `admin` (required) Type: boolean If the user is an administrator. Example: ```json true ``` - `createdAt` (required) Type: string, date-time The date the user was created. readOnly: true Example: ```json "2019-01-01T00:00:00Z" ``` - `id` (required) Type: integer, int64 The user id. readOnly: true Example: ```json 25 ``` - `name` (required) Type: string The user name. For login. Example: ```json "unicorn" ``` ## UserPass Type: UserPass The Password for updating the user. Schema: [UserPass](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/userpass-d0d4f76c2b.md) - `pass` (required) Type: string The user password. For login. Example: ```json "nrocinu" ``` ## VersionInfo Type: VersionInfo VersionInfo Model Schema: [VersionInfo](https://sourcey-gotify.pages.dev/api-docs/v3.1.0/schemas/versioninfo-641558380f.md) - `buildDate` (required) Type: string The date on which this binary was built. Example: ```json "2018-02-27T19:36:10.5045044+01:00" ``` - `commit` (required) Type: string The git commit hash on which this binary was built. Example: ```json "ae9512b6b6feea56a110d59a3353ea3b9c293864" ``` - `version` (required) Type: string The current version. Example: ```json "5.2.6" ```