Gotify REST-API.

v2.1.0

Base URLs

http://localhost

https://localhost

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

Authentication

appTokenAuthorizationHeaderapiKey

Enter an application token with the Bearer prefix, e.g. Bearer Axxxxxxxxxx.

API Key: Authorization in header

appTokenHeaderapiKey

API Key: X-Gotify-Key in header

appTokenQueryapiKey

API Key: token in query

basicAuthhttp

Scheme: basic

clientTokenAuthorizationHeaderapiKey

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

API Key: Authorization in header

clientTokenHeaderapiKey

API Key: X-Gotify-Key in header

clientTokenQueryapiKey

API Key: token in query

application

Return all applications.

GET

http://localhost/application

Return all applications.

curl -X GET 'http://localhost/application' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/application', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/application',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "createdAt": "2019-01-01T00:00:00Z",
    "defaultPriority": 4,
    "description": "Backup server for the interwebs",
    "id": 5,
    "image": "image/image.jpeg",
    "internal": false,
    "lastUsed": "2019-01-01T00:00:00Z",
    "name": "Backup Server",
    "sortKey": "a1",
    "token": "AWH0wZ5r0Mbac.r"
  }
]

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKArray<Application>

Response fields application/json

Array<Application>

Show child attributes

The Application holds information about an app which can send notifications.

createdAtstring<date-time>requiredread only

The date the application was created.

Example

2019-01-01T00:00:00Z

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstringrequired

The description of the application.

Example

Backup server for the interwebs

idinteger<int64>requiredread only

The application id.

Example

imagestringrequiredread only

The image of the application.

Example

image/image.jpeg

internalbooleanrequiredread only

Whether the application is an internal application. Internal applications should not be deleted.

Example

false

lastUsedstring<date-time>read only

The last time the application token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystringrequired

The sort key of this application. Uses fractional indexing.

Example

a1

tokenstringread only

The application token. Can be used as appToken. See Authentication.

Example

AWH0wZ5r0Mbac.r

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Create an application.

POST

http://localhost/application

Create an application.

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"
}'

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();

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)

Request Body

{
  "defaultPriority": 5,
  "description": "Backup server for the interwebs",
  "name": "Backup Server",
  "sortKey": "a1"
}

{
  "createdAt": "2019-01-01T00:00:00Z",
  "defaultPriority": 4,
  "description": "Backup server for the interwebs",
  "id": 5,
  "image": "image/image.jpeg",
  "internal": false,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Backup Server",
  "sortKey": "a1",
  "token": "AWH0wZ5r0Mbac.r"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the application to add

Params allowed to create or update Applications.

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstring

The description of the application.

Example

Backup server for the interwebs

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystring

The sortKey for the application. Uses fractional indexing.

Example

a1

Response

200OKApplication

Response fields application/json

The Application holds information about an app which can send notifications.

createdAtstring<date-time>requiredread only

The date the application was created.

Example

2019-01-01T00:00:00Z

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstringrequired

The description of the application.

Example

Backup server for the interwebs

idinteger<int64>requiredread only

The application id.

Example

imagestringrequiredread only

The image of the application.

Example

image/image.jpeg

internalbooleanrequiredread only

Whether the application is an internal application. Internal applications should not be deleted.

Example

false

lastUsedstring<date-time>read only

The last time the application token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystringrequired

The sort key of this application. Uses fractional indexing.

Example

a1

tokenstringread only

The application token. Can be used as appToken. See Authentication.

Example

AWH0wZ5r0Mbac.r

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Update an application.

PUT

http://localhost/application/{id}

Update an application.

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"
}'

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();

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)

Request Body

{
  "defaultPriority": 5,
  "description": "Backup server for the interwebs",
  "name": "Backup Server",
  "sortKey": "a1"
}

{
  "createdAt": "2019-01-01T00:00:00Z",
  "defaultPriority": 4,
  "description": "Backup server for the interwebs",
  "id": 5,
  "image": "image/image.jpeg",
  "internal": false,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Backup Server",
  "sortKey": "a1",
  "token": "AWH0wZ5r0Mbac.r"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the application to update

Params allowed to create or update Applications.

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstring

The description of the application.

Example

Backup server for the interwebs

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystring

The sortKey for the application. Uses fractional indexing.

Example

a1

Parameters

idinteger<int64>requiredpath

the application id

Response

200OKApplication

Response fields application/json

The Application holds information about an app which can send notifications.

createdAtstring<date-time>requiredread only

The date the application was created.

Example

2019-01-01T00:00:00Z

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstringrequired

The description of the application.

Example

Backup server for the interwebs

idinteger<int64>requiredread only

The application id.

Example

imagestringrequiredread only

The image of the application.

Example

image/image.jpeg

internalbooleanrequiredread only

Whether the application is an internal application. Internal applications should not be deleted.

Example

false

lastUsedstring<date-time>read only

The last time the application token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystringrequired

The sort key of this application. Uses fractional indexing.

Example

a1

tokenstringread only

The application token. Can be used as appToken. See Authentication.

Example

AWH0wZ5r0Mbac.r

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Delete an application.

DELETE

http://localhost/application/{id}

Requires elevated authentication.

Delete an application.

curl -X DELETE 'http://localhost/application/0' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/application/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/application/0',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the application id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Upload an image for an application.

POST

http://localhost/application/{id}/image

Upload an image for an application.

curl -X POST 'http://localhost/application/0/image' \
  -H 'Authorization: YOUR_TOKEN'

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());

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)

Request Body

{
  "file": "<binary>"
}

{
  "createdAt": "2019-01-01T00:00:00Z",
  "defaultPriority": 4,
  "description": "Backup server for the interwebs",
  "id": 5,
  "image": "image/image.jpeg",
  "internal": false,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Backup Server",
  "sortKey": "a1",
  "token": "AWH0wZ5r0Mbac.r"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

multipart/form-data

filestring<binary>required

the application image

Parameters

idinteger<int64>requiredpath

the application id

Response

200OKApplication

Response fields application/json

The Application holds information about an app which can send notifications.

createdAtstring<date-time>requiredread only

The date the application was created.

Example

2019-01-01T00:00:00Z

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstringrequired

The description of the application.

Example

Backup server for the interwebs

idinteger<int64>requiredread only

The application id.

Example

imagestringrequiredread only

The image of the application.

Example

image/image.jpeg

internalbooleanrequiredread only

Whether the application is an internal application. Internal applications should not be deleted.

Example

false

lastUsedstring<date-time>read only

The last time the application token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystringrequired

The sort key of this application. Uses fractional indexing.

Example

a1

tokenstringread only

The application token. Can be used as appToken. See Authentication.

Example

AWH0wZ5r0Mbac.r

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Deletes an image of an application.

DELETE

http://localhost/application/{id}/image

Deletes an image of an application.

curl -X DELETE 'http://localhost/application/0/image' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/application/0/image', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/application/0/image',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the application id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Perform security updates on an application.

PUT

http://localhost/application/{id}/security

Requires elevated authentication.

Perform security updates on an application.

curl -X PUT 'http://localhost/application/0/security' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "regenerateToken": true
}'

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();

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)

Request Body

{
  "regenerateToken": true
}

{
  "regenerateToken": {
    "token": "gtfya.e2NcJK7AenXBPIRB3S03JsBlmy0V6xP8h0hwSiAJae8"
  }
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

security update action descriptor

The SecurityUpdateAction describes the details of a requested security update.

regenerateTokenboolean

Whether to regenerate the token. Your client token must be elevated to perform this action.

Example

true

Parameters

idinteger<int64>requiredpath

the application id

Response

200OKSecurityUpdateActionResponse

Response fields application/json

The SecurityUpdateActionResponse holds information about the response to a security update request.

regenerateTokenRegenerateTokenResponse

The RegenerateTokenResponse holds information about the response to the regenerate token action.

Show child attributes

tokenstringrequiredread only

The new token.

Example

gtfya.e2NcJK7AenXBPIRB3S03JsBlmy0V6xP8h0hwSiAJae8

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

message

Return all messages from a specific application.

GET

http://localhost/application/{id}/message

Return all messages from a specific application.

curl -X GET 'http://localhost/application/0/message?limit=100' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/application/0/message?limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/application/0/message?limit=100',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "messages": [
    {
      "appid": 5,
      "date": "2018-02-27T19:36:10.5045044+01:00",
      "extras": {
        "home::appliances::lighting::on": {
          "brightness": 15
        },
        "home::appliances::thermostat::change_temperature": {
          "temperature": 23
        }
      },
      "id": 25,
      "message": "**Backup** was successfully finished.",
      "priority": 2,
      "title": "Backup"
    }
  ],
  "paging": {
    "limit": 123,
    "next": "/message?limit=50&since=123456",
    "since": 5,
    "size": 5
  }
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the application id

limitinteger[1, 200]100query

the maximal amount of messages to return

sinceinteger<int64>>= 0query

return all messages with an ID less than this value

Response

200OKPagedMessages

Response fields application/json

Wrapper for the paging and the messages.

messagesArray<Message>requiredread only

The messages.

Show child attributes

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

pagingPagingrequired

The Paging holds information about the limit and making requests to the next page.

Show child attributes

limitinteger<int64>[1, 200]requiredread only

The limit of the messages for the current request.

Example

nextstringread only

The relative path for the next page. Empty/Null when no next page is available. Should be combined with the gotify base url.

Example

/message?limit=50&since=123456

sinceinteger<int64>>= 0requiredread only

The ID of the last message returned in the current request. Use this as alternative to the next link.

Example

sizeinteger<int64>requiredread only

The amount of messages that got returned in the current request.

Example

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Delete all messages from a specific application.

DELETE

http://localhost/application/{id}/message

Delete all messages from a specific application.

curl -X DELETE 'http://localhost/application/0/message' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/application/0/message', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/application/0/message',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the application id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Return all messages.

GET

http://localhost/message

Return all messages.

curl -X GET 'http://localhost/message?limit=100' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/message?limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/message?limit=100',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "messages": [
    {
      "appid": 5,
      "date": "2018-02-27T19:36:10.5045044+01:00",
      "extras": {
        "home::appliances::lighting::on": {
          "brightness": 15
        },
        "home::appliances::thermostat::change_temperature": {
          "temperature": 23
        }
      },
      "id": 25,
      "message": "**Backup** was successfully finished.",
      "priority": 2,
      "title": "Backup"
    }
  ],
  "paging": {
    "limit": 123,
    "next": "/message?limit=50&since=123456",
    "since": 5,
    "size": 5
  }
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

limitinteger[1, 200]100query

the maximal amount of messages to return

sinceinteger<int64>>= 0query

return all messages with an ID less than this value

Response

200OKPagedMessages

Response fields application/json

Wrapper for the paging and the messages.

messagesArray<Message>requiredread only

The messages.

Show child attributes

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

pagingPagingrequired

The Paging holds information about the limit and making requests to the next page.

Show child attributes

limitinteger<int64>[1, 200]requiredread only

The limit of the messages for the current request.

Example

nextstringread only

The relative path for the next page. Empty/Null when no next page is available. Should be combined with the gotify base url.

Example

/message?limit=50&since=123456

sinceinteger<int64>>= 0requiredread only

The ID of the last message returned in the current request. Use this as alternative to the next link.

Example

sizeinteger<int64>requiredread only

The amount of messages that got returned in the current request.

Example

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Create a message.

POST

http://localhost/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.

Create a message.

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"
}'

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();

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)

Request 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"
}

{
  "appid": 5,
  "date": "2018-02-27T19:36:10.5045044+01:00",
  "extras": {
    "home::appliances::lighting::on": {
      "brightness": 15
    },
    "home::appliances::thermostat::change_temperature": {
      "temperature": 23
    }
  },
  "id": 25,
  "message": "**Backup** was successfully finished.",
  "priority": 2,
  "title": "Backup"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the message to add

The CreateMessage holds information about a message that will be sent.

appidinteger<int64>

The application id that send this message. Always set when returned via the API.

Example

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

Response

200OKMessage

Response fields application/json

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

appTokenAuthorizationHeaderapiKey in header

Enter an application token with the Bearer prefix, e.g. Bearer Axxxxxxxxxx.

appTokenHeaderapiKey in header

appTokenQueryapiKey in query

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Delete all messages.

DELETE

http://localhost/message

Delete all messages.

curl -X DELETE 'http://localhost/message' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/message', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/message',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OK

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Deletes a message with an id.

DELETE

http://localhost/message/{id}

Deletes a message with an id.

curl -X DELETE 'http://localhost/message/0' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/message/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/message/0',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the message id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Websocket, return newly created messages.

GET

http://localhost/stream

Websocket, return newly created messages.

curl -X GET 'http://localhost/stream' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/stream', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/stream',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "appid": 5,
  "date": "2018-02-27T19:36:10.5045044+01:00",
  "extras": {
    "home::appliances::lighting::on": {
      "brightness": 15
    },
    "home::appliances::thermostat::change_temperature": {
      "temperature": 23
    }
  },
  "id": 25,
  "message": "**Backup** was successfully finished.",
  "priority": 2,
  "title": "Backup"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKMessage

Response fields application/json

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

auth

Authenticate via basic auth and create a session.

POST

http://localhost/auth/local/login

Authenticate via basic auth and create a session.

curl -X POST 'http://localhost/auth/local/login' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'name=string'

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();

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)

Request Body

{
  "name": "string"
}

{
  "admin": true,
  "clientId": 5,
  "createdAt": "2019-01-01T00:00:00Z",
  "elevatedUntil": "2024-01-15T09:30:00Z",
  "id": 25,
  "name": "unicorn"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKCurrentUser

Response headers

Response fields application/json

CurrentUserExternal Model

adminbooleanrequired

If the user is an administrator.

Example

true

clientIdinteger<int64>read only

The client id of the current session.

Example

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which the session is elevated.

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

End the current session.

POST

http://localhost/auth/logout

Clears the session cookie and deletes the associated client.

End the current session.

curl -X POST 'http://localhost/auth/logout' \
  -H 'X-Gotify-Key: YOUR_TOKEN'

const response = await fetch('http://localhost/auth/logout', {
  method: 'POST',
  headers: {
    'X-Gotify-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost/auth/logout',
    headers={
        'X-Gotify-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

400

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OK

Response headers

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

oidc

Handle the OIDC provider callback (browser).

GET

http://localhost/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.

Handle the OIDC provider callback (browser).

curl -X GET 'http://localhost/auth/oidc/callback?code=string&state=string'

const response = await fetch('http://localhost/auth/oidc/callback?code=string&state=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/auth/oidc/callback?code=string&state=string')
print(response.text)

default

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

codestringrequiredquery

the authorization code from the OIDC provider

statestringrequiredquery

the state parameter for CSRF protection

Response

200OK

307Temporary Redirect

Redirect to UI

defaultError

Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Start the OIDC flow to elevate an existing client session (browser).

GET

http://localhost/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.

Start the OIDC flow to elevate an existing client session (browser).

curl -X GET 'http://localhost/auth/oidc/elevate?id=0&durationSeconds=0'

const response = await fetch('http://localhost/auth/oidc/elevate?id=0&durationSeconds=0', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/auth/oidc/elevate?id=0&durationSeconds=0')
print(response.text)

default

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredquery

the client id to elevate

durationSecondsintegerrequiredquery

how long the elevation should last, in seconds

Response

302Found

Redirect to OIDC provider

defaultError

Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Initiate the OIDC authorization flow for a native app.

POST

http://localhost/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.

Initiate the OIDC authorization flow for a native app.

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"
}'

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();

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)

Request Body

{
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "name": "Android Phone",
  "redirect_uri": "gotify://oidc/callback"
}

{
  "authorize_url": "https://auth.example.com/authorize?client_id=gotify&...",
  "state": "Android Phone:a1b2c3d4e5f6"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

Used to initiate the OIDC authorization flow for an external client.

code_challengestringrequired

The PKCE code challenge (S256).

Example

E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

namestringrequired

The client name to display in gotify.

Example

Android Phone

redirect_uristringrequired

The app's redirect URI.

Example

gotify://oidc/callback

Response

200OKOIDCExternalAuthorizeResponse

Response fields application/json

Returned after initiating the OIDC authorization flow.

authorize_urlstringrequired

The URL to open in the browser to authenticate with the OIDC provider.

Example

https://auth.example.com/authorize?client_id=gotify&...

statestringrequired

The state parameter to send back with the token exchange request.

Example

Android Phone:a1b2c3d4e5f6

defaultError

Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Exchange an authorization code for a gotify client token.

POST

http://localhost/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.

Exchange an authorization code for a gotify client token.

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"
}'

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();

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)

Request Body

{
  "code": "string",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "state": "Android Phone:a1b2c3d4e5f6"
}

{
  "token": "CWH0wZ5r0Mbac.r",
  "user": {
    "admin": true,
    "createdAt": "2019-01-01T00:00:00Z",
    "id": 25,
    "name": "unicorn"
  }
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

Used to exchange an authorization code for a gotify client token.

codestringrequired

The authorization code from the OIDC provider.

code_verifierstringrequired

The PKCE code verifier.

Example

dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

statestringrequired

The state from the authorize response.

Example

Android Phone:a1b2c3d4e5f6

Response

200OKOIDCExternalTokenResponse

Response fields application/json

Returned after a successful token exchange.

tokenstringrequired

The gotify client token for API authentication.

Example

CWH0wZ5r0Mbac.r

userUserrequired

The User holds information about permission and other stuff.

Show child attributes

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

defaultError

Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Start the OIDC login flow (browser).

GET

http://localhost/auth/oidc/login

Redirects the user to the OIDC provider's authorization endpoint. After authentication, the provider redirects back to the callback endpoint.

Start the OIDC login flow (browser).

curl -X GET 'http://localhost/auth/oidc/login?name=string'

const response = await fetch('http://localhost/auth/oidc/login?name=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/auth/oidc/login?name=string')
print(response.text)

default

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

defaultError

Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

client

Return all clients.

GET

http://localhost/client

Return all clients.

curl -X GET 'http://localhost/client' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/client', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/client',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "createdAt": "2019-01-01T00:00:00Z",
    "elevatedUntil": "2024-01-15T09:30:00Z",
    "expiresAfterInactivitySeconds": 2592000,
    "expiresAt": "2019-01-01T00:00:00Z",
    "id": 5,
    "lastUsed": "2019-01-01T00:00:00Z",
    "name": "Android Phone",
    "token": "CWH0wZ5r0Mbac.r"
  }
]

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKArray<Client>

Response fields application/json

Array<Client>

Show child attributes

The Client holds information about a device which can receive notifications (and other stuff).

createdAtstring<date-time>requiredread only

The date the client was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which this client's session is elevated.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 means the client never expires.

Example

expiresAtstring<date-time>read only

The time at which this client will expire due to inactivity, or null if it never expires.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The client id.

Example

lastUsedstring<date-time>read only

The last time the client token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The client name. This is how the client should be displayed to the user.

Example

Android Phone

tokenstringread only

The client token. Can be used as clientToken. See Authentication.

Example

CWH0wZ5r0Mbac.r

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Create a client.

POST

http://localhost/client

Create a client.

curl -X POST 'http://localhost/client' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "expiresAfterInactivitySeconds": 2592000,
  "name": "My Client"
}'

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();

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)

Request Body

{
  "expiresAfterInactivitySeconds": 2592000,
  "name": "My Client"
}

{
  "createdAt": "2019-01-01T00:00:00Z",
  "elevatedUntil": "2024-01-15T09:30:00Z",
  "expiresAfterInactivitySeconds": 2592000,
  "expiresAt": "2019-01-01T00:00:00Z",
  "id": 5,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Android Phone",
  "token": "CWH0wZ5r0Mbac.r"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the client to add

Params allowed to create or update Clients.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires.

Example

namestringrequired

The client name

Example

My Client

Response

200OKClient

Response fields application/json

The Client holds information about a device which can receive notifications (and other stuff).

createdAtstring<date-time>requiredread only

The date the client was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which this client's session is elevated.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 means the client never expires.

Example

expiresAtstring<date-time>read only

The time at which this client will expire due to inactivity, or null if it never expires.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The client id.

Example

lastUsedstring<date-time>read only

The last time the client token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The client name. This is how the client should be displayed to the user.

Example

Android Phone

tokenstringread only

The client token. Can be used as clientToken. See Authentication.

Example

CWH0wZ5r0Mbac.r

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Update a client.

PUT

http://localhost/client/{id}

Update a client.

curl -X PUT 'http://localhost/client/0' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "expiresAfterInactivitySeconds": 2592000,
  "name": "My Client"
}'

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();

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)

Request Body

{
  "expiresAfterInactivitySeconds": 2592000,
  "name": "My Client"
}

{
  "createdAt": "2019-01-01T00:00:00Z",
  "elevatedUntil": "2024-01-15T09:30:00Z",
  "expiresAfterInactivitySeconds": 2592000,
  "expiresAt": "2019-01-01T00:00:00Z",
  "id": 5,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Android Phone",
  "token": "CWH0wZ5r0Mbac.r"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the client to update

Params allowed to create or update Clients.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires.

Example

namestringrequired

The client name

Example

My Client

Parameters

idinteger<int64>requiredpath

the client id

Response

200OKClient

Response fields application/json

The Client holds information about a device which can receive notifications (and other stuff).

createdAtstring<date-time>requiredread only

The date the client was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which this client's session is elevated.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 means the client never expires.

Example

expiresAtstring<date-time>read only

The time at which this client will expire due to inactivity, or null if it never expires.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The client id.

Example

lastUsedstring<date-time>read only

The last time the client token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The client name. This is how the client should be displayed to the user.

Example

Android Phone

tokenstringread only

The client token. Can be used as clientToken. See Authentication.

Example

CWH0wZ5r0Mbac.r

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Delete a client.

DELETE

http://localhost/client/{id}

Requires elevated authentication.

Delete a client.

curl -X DELETE 'http://localhost/client/0' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/client/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/client/0',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the client id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Elevate a client session.

POST

http://localhost/client/{id}/elevate

Requires elevated authentication.

Elevate a client session.

curl -X POST 'http://localhost/client/0/elevate' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "durationSeconds": 900
}'

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();

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)

Request Body

{
  "durationSeconds": 900
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the elevation request

durationSecondsinteger<int64>required

How long the elevation should last, in seconds.

Example

Parameters

idinteger<int64>requiredpath

the client id

Response

204No Content

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

user

Return the current user.

GET

http://localhost/current/user

Requires elevated authentication.

Return the current user.

curl -X GET 'http://localhost/current/user' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/current/user', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/current/user',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "admin": true,
  "createdAt": "2019-01-01T00:00:00Z",
  "id": 25,
  "name": "unicorn"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKUser

Response fields application/json

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Update the password of the current user.

POST

http://localhost/current/user/password

Requires elevated authentication.

Update the password of the current user.

curl -X POST 'http://localhost/current/user/password' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "pass": "nrocinu"
}'

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();

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)

Request Body

{
  "pass": "nrocinu"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the user

The Password for updating the user.

passstringrequired

The user password. For login.

Example

nrocinu

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Return all users.

GET

http://localhost/user

Requires elevated authentication.

Return all users.

curl -X GET 'http://localhost/user' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/user', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/user',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "admin": true,
    "createdAt": "2019-01-01T00:00:00Z",
    "id": 25,
    "name": "unicorn"
  }
]

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKArray<User>

Response fields application/json

Array<User>

Show child attributes

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Create a user.

POST

http://localhost/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.

Create a user.

curl -X POST 'http://localhost/user' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "admin": true,
  "name": "unicorn",
  "pass": "nrocinu"
}'

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();

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)

Request Body

{
  "admin": true,
  "name": "unicorn",
  "pass": "nrocinu"
}

{
  "admin": true,
  "createdAt": "2019-01-01T00:00:00Z",
  "id": 25,
  "name": "unicorn"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the user to add

Used for user creation.

adminbooleanrequired

If the user is an administrator.

Example

true

namestringrequired

The user name. For login.

Example

unicorn

passstringrequired

The user password. For login.

Example

nrocinu

Response

200OKUser

Response fields application/json

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Get a user.

GET

http://localhost/user/{id}

Requires elevated authentication.

Get a user.

curl -X GET 'http://localhost/user/0' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/user/0', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/user/0',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "admin": true,
  "createdAt": "2019-01-01T00:00:00Z",
  "id": 25,
  "name": "unicorn"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the user id

Response

200OKUser

Response fields application/json

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Update a user.

POST

http://localhost/user/{id}

Requires elevated authentication.

Update a user.

curl -X POST 'http://localhost/user/0' \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "admin": true,
  "name": "unicorn",
  "pass": "nrocinu"
}'

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();

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)

Request Body

{
  "admin": true,
  "name": "unicorn",
  "pass": "nrocinu"
}

{
  "admin": true,
  "createdAt": "2019-01-01T00:00:00Z",
  "id": 25,
  "name": "unicorn"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Body

application/json

the updated user

Used for updating a user.

adminbooleanrequired

If the user is an administrator.

Example

true

namestringrequired

The user name. For login.

Example

unicorn

passstring

The user password. For login. Empty for using old password

Example

nrocinu

Parameters

idinteger<int64>requiredpath

the user id

Response

200OKUser

Response fields application/json

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Deletes a user.

DELETE

http://localhost/user/{id}

Requires elevated authentication.

Deletes a user.

curl -X DELETE 'http://localhost/user/0' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/user/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost/user/0',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the user id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

info

Get gotify information.

GET

http://localhost/gotifyinfo

Get gotify information.

curl -X GET 'http://localhost/gotifyinfo'

const response = await fetch('http://localhost/gotifyinfo', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/gotifyinfo')
print(response.text)

200

{
  "localAuth": true,
  "oidc": true,
  "oidcAutoRedirect": false,
  "oidcIdpName": "OIDC",
  "register": true,
  "version": "5.2.6"
}

Response

200OKGotifyInfo

Response fields application/json

GotifyInfo Model

localAuthbooleanrequired

If local authentication is enabled.

Example

true

oidcbooleanrequired

If oidc is enabled.

Example

true

oidcAutoRedirectbooleanrequired

If the WebUI should automatically redirect to the OIDC identity provider instead of showing the login page.

Example

false

oidcIdpNamestringrequired

Name of the OIDC identity provider.

Example

OIDC

registerbooleanrequired

If registration is enabled.

Example

true

versionstringrequired

The current version.

Example

5.2.6

Get health information.

GET

http://localhost/health

Get health information.

curl -X GET 'http://localhost/health'

const response = await fetch('http://localhost/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/health')
print(response.text)

{
  "database": "green",
  "health": "green"
}

{
  "database": "green",
  "health": "green"
}

Response

200OKHealth

Response fields application/json

Health represents how healthy the application is.

databasestringrequired

The health of the database connection.

Example

green

healthstringrequired

The health of the overall application.

Example

green

500Internal Server ErrorHealth

Response fields application/json

Health represents how healthy the application is.

databasestringrequired

The health of the database connection.

Example

green

healthstringrequired

The health of the overall application.

Example

green

Get version information.

GET

http://localhost/version

Get version information.

curl -X GET 'http://localhost/version'

const response = await fetch('http://localhost/version', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost/version')
print(response.text)

200

{
  "buildDate": "2018-02-27T19:36:10.5045044+01:00",
  "commit": "ae9512b6b6feea56a110d59a3353ea3b9c293864",
  "version": "5.2.6"
}

Response

200OKVersionInfo

Response fields application/json

VersionInfo Model

buildDatestringrequired

The date on which this binary was built.

Example

2018-02-27T19:36:10.5045044+01:00

commitstringrequired

The git commit hash on which this binary was built.

Example

ae9512b6b6feea56a110d59a3353ea3b9c293864

versionstringrequired

The current version.

Example

5.2.6

plugin

Return all plugins.

GET

http://localhost/plugin

Return all plugins.

curl -X GET 'http://localhost/plugin' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/plugin',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "author": "jmattheis",
    "capabilities": [
      "webhook",
      "display"
    ],
    "createdAt": "2019-01-01T00:00:00Z",
    "enabled": true,
    "id": 25,
    "license": "MIT",
    "modulePath": "github.com/gotify/server/plugin/example/echo",
    "name": "RSS poller",
    "token": "P1234",
    "website": "gotify.net"
  }
]

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Response

200OKArray<PluginConf>

Response fields application/json

Array<PluginConf>

Show child attributes

Holds information about a plugin instance for one user.

authorstringread only

The author of the plugin.

Example

jmattheis

capabilitiesArray<string>required

Capabilities the plugin provides

Example

[
  "webhook",
  "display"
]

createdAtstring<date-time>requiredread only

The date the plugin was created.

Example

2019-01-01T00:00:00Z

enabledbooleanrequired

Whether the plugin instance is enabled.

Example

true

idinteger<int64>requiredread only

The plugin id.

Example

licensestringread only

The license of the plugin.

Example

MIT

modulePathstringrequiredread only

The module path of the plugin.

Example

github.com/gotify/server/plugin/example/echo

namestringrequiredread only

The plugin name.

Example

RSS poller

tokenstringrequired

The user name. For login.

Example

P1234

websitestringread only

The website of the plugin.

Example

gotify.net

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Get YAML configuration for Configurer plugin.

GET

http://localhost/plugin/{id}/config

Get YAML configuration for Configurer plugin.

curl -X GET 'http://localhost/plugin/0/config' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin/0/config', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/plugin/0/config',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the plugin id

Response

200OKobject

Response fields application/x-yaml

plugin configuration

object

400Bad RequestError

Bad Request

Response fields application/x-yaml

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/x-yaml

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/x-yaml

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/x-yaml

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/x-yaml

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Update YAML configuration for Configurer plugin.

POST

http://localhost/plugin/{id}/config

Update YAML configuration for Configurer plugin.

curl -X POST 'http://localhost/plugin/0/config' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin/0/config', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost/plugin/0/config',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the plugin id

Response

200OK

400Bad RequestError

Bad Request

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Disable a plugin.

POST

http://localhost/plugin/{id}/disable

Disable a plugin.

curl -X POST 'http://localhost/plugin/0/disable' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin/0/disable', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost/plugin/0/disable',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the plugin id

Response

200OK

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Get display info for a Displayer plugin.

GET

http://localhost/plugin/{id}/display

Get display info for a Displayer plugin.

curl -X GET 'http://localhost/plugin/0/display' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin/0/display', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost/plugin/0/display',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

"string"

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the plugin id

Response

200OKstring

Response fields application/json

string

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Enable a plugin.

POST

http://localhost/plugin/{id}/enable

Enable a plugin.

curl -X POST 'http://localhost/plugin/0/enable' \
  -H 'Authorization: YOUR_TOKEN'

const response = await fetch('http://localhost/plugin/0/enable', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost/plugin/0/enable',
    headers={
        'Authorization': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

{
  "error": "Unauthorized",
  "errorCode": 401,
  "errorDescription": "you need to provide a valid access token or user credentials to access this api"
}

Parameters

idinteger<int64>requiredpath

the plugin id

Response

200OK

401UnauthorizedError

Unauthorized

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

403ForbiddenError

Forbidden

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

404Not FoundError

Not Found

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

500Internal Server ErrorError

Internal Server Error

Response fields application/json

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

Authorization

clientTokenAuthorizationHeaderapiKey in header

Enter a client token with the Bearer prefix, e.g. Bearer Cxxxxxxxxxx.

clientTokenHeaderapiKey in header

clientTokenQueryapiKey in query

basicAuthhttp (basic)

Models

Application

object

The Application holds information about an app which can send notifications.

createdAtstring<date-time>requiredread only

The date the application was created.

Example

2019-01-01T00:00:00Z

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstringrequired

The description of the application.

Example

Backup server for the interwebs

idinteger<int64>requiredread only

The application id.

Example

imagestringrequiredread only

The image of the application.

Example

image/image.jpeg

internalbooleanrequiredread only

Whether the application is an internal application. Internal applications should not be deleted.

Example

false

lastUsedstring<date-time>read only

The last time the application token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystringrequired

The sort key of this application. Uses fractional indexing.

Example

a1

tokenstringread only

The application token. Can be used as appToken. See Authentication.

Example

AWH0wZ5r0Mbac.r

Example

{
  "createdAt": "2019-01-01T00:00:00Z",
  "defaultPriority": 4,
  "description": "Backup server for the interwebs",
  "id": 5,
  "image": "image/image.jpeg",
  "internal": false,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Backup Server",
  "sortKey": "a1",
  "token": "AWH0wZ5r0Mbac.r"
}

ApplicationParams

object

Params allowed to create or update Applications.

defaultPriorityinteger<int64>

The default priority of messages sent by this application. Defaults to 0.

Example

descriptionstring

The description of the application.

Example

Backup server for the interwebs

namestringrequired

The application name. This is how the application should be displayed to the user.

Example

Backup Server

sortKeystring

The sortKey for the application. Uses fractional indexing.

Example

a1

Client

object

The Client holds information about a device which can receive notifications (and other stuff).

createdAtstring<date-time>requiredread only

The date the client was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which this client's session is elevated.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 means the client never expires.

Example

expiresAtstring<date-time>read only

The time at which this client will expire due to inactivity, or null if it never expires.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The client id.

Example

lastUsedstring<date-time>read only

The last time the client token was used.

Example

2019-01-01T00:00:00Z

namestringrequired

The client name. This is how the client should be displayed to the user.

Example

Android Phone

tokenstringread only

The client token. Can be used as clientToken. See Authentication.

Example

CWH0wZ5r0Mbac.r

Example

{
  "createdAt": "2019-01-01T00:00:00Z",
  "elevatedUntil": "2024-01-15T09:30:00Z",
  "expiresAfterInactivitySeconds": 2592000,
  "expiresAt": "2019-01-01T00:00:00Z",
  "id": 5,
  "lastUsed": "2019-01-01T00:00:00Z",
  "name": "Android Phone",
  "token": "CWH0wZ5r0Mbac.r"
}

ClientParams

object

Params allowed to create or update Clients.

expiresAfterInactivitySecondsinteger<int64>

The number of seconds of inactivity after which the client is removed. 0 (or omitted) means the client never expires.

Example

namestringrequired

The client name

Example

My Client

CreateMessage

object

The CreateMessage holds information about a message that will be sent.

appidinteger<int64>

The application id that send this message. Always set when returned via the API.

Example

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

Example

{
  "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"
}

CreateUserExternal

object

Used for user creation.

adminbooleanrequired

If the user is an administrator.

Example

true

namestringrequired

The user name. For login.

Example

unicorn

passstringrequired

The user password. For login.

Example

nrocinu

CurrentUser

object

CurrentUserExternal Model

adminbooleanrequired

If the user is an administrator.

Example

true

clientIdinteger<int64>read only

The client id of the current session.

Example

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

elevatedUntilstring<date-time>read only

The time until which the session is elevated.

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

ElevateRequest

object

durationSecondsinteger<int64>required

How long the elevation should last, in seconds.

Example

Error

object

The Error contains error relevant information.

errorstringrequired

The general error message

Example

Unauthorized

errorCodeinteger<int64>required

The http error code.

Example

errorDescriptionstringrequired

The http error code.

Example

you need to provide a valid access token or user credentials to access this api

GotifyInfo

object

GotifyInfo Model

localAuthbooleanrequired

If local authentication is enabled.

Example

true

oidcbooleanrequired

If oidc is enabled.

Example

true

oidcAutoRedirectbooleanrequired

If the WebUI should automatically redirect to the OIDC identity provider instead of showing the login page.

Example

false

oidcIdpNamestringrequired

Name of the OIDC identity provider.

Example

OIDC

registerbooleanrequired

If registration is enabled.

Example

true

versionstringrequired

The current version.

Example

5.2.6

Health

object

Health represents how healthy the application is.

databasestringrequired

The health of the database connection.

Example

green

healthstringrequired

The health of the overall application.

Example

green

Message

object

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

Example

{
  "appid": 5,
  "date": "2018-02-27T19:36:10.5045044+01:00",
  "extras": {
    "home::appliances::lighting::on": {
      "brightness": 15
    },
    "home::appliances::thermostat::change_temperature": {
      "temperature": 23
    }
  },
  "id": 25,
  "message": "**Backup** was successfully finished.",
  "priority": 2,
  "title": "Backup"
}

OIDCExternalAuthorizeRequest

object

Used to initiate the OIDC authorization flow for an external client.

code_challengestringrequired

The PKCE code challenge (S256).

Example

E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

namestringrequired

The client name to display in gotify.

Example

Android Phone

redirect_uristringrequired

The app's redirect URI.

Example

gotify://oidc/callback

OIDCExternalAuthorizeResponse

object

Returned after initiating the OIDC authorization flow.

authorize_urlstringrequired

The URL to open in the browser to authenticate with the OIDC provider.

Example

https://auth.example.com/authorize?client_id=gotify&...

statestringrequired

The state parameter to send back with the token exchange request.

Example

Android Phone:a1b2c3d4e5f6

OIDCExternalTokenRequest

object

Used to exchange an authorization code for a gotify client token.

codestringrequired

The authorization code from the OIDC provider.

code_verifierstringrequired

The PKCE code verifier.

Example

dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

statestringrequired

The state from the authorize response.

Example

Android Phone:a1b2c3d4e5f6

OIDCExternalTokenResponse

object

Returned after a successful token exchange.

tokenstringrequired

The gotify client token for API authentication.

Example

CWH0wZ5r0Mbac.r

userUserrequired

The User holds information about permission and other stuff.

Show child attributes

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

PagedMessages

object

Wrapper for the paging and the messages.

messagesArray<Message>requiredread only

The messages.

Show child attributes

The MessageExternal holds information about a message which was sent by an Application.

appidinteger<int64>requiredread only

The application id that send this message.

Example

datestring<date-time>requiredread only

The date the message was created.

Example

2018-02-27T19:36:10.5045044+01:00

extrasobject

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.

Show child attributes

[key: string]any

Example

{
  "home::appliances::lighting::on": {
    "brightness": 15
  },
  "home::appliances::thermostat::change_temperature": {
    "temperature": 23
  }
}

idinteger<int64>requiredread only

The message id.

Example

messagestringrequired

The message. Markdown (excluding html) is allowed.

Example

**Backup** was successfully finished.

priorityinteger<int64>

The priority of the message. If unset, then the default priority of the application will be used.

Example

titlestring

The title of the message.

Example

Backup

pagingPagingrequired

The Paging holds information about the limit and making requests to the next page.

Show child attributes

limitinteger<int64>[1, 200]requiredread only

The limit of the messages for the current request.

Example

nextstringread only

The relative path for the next page. Empty/Null when no next page is available. Should be combined with the gotify base url.

Example

/message?limit=50&since=123456

sinceinteger<int64>>= 0requiredread only

The ID of the last message returned in the current request. Use this as alternative to the next link.

Example

sizeinteger<int64>requiredread only

The amount of messages that got returned in the current request.

Example

{
  "messages": [
    {
      "appid": 5,
      "date": "2018-02-27T19:36:10.5045044+01:00",
      "extras": {
        "home::appliances::lighting::on": {
          "brightness": 15
        },
        "home::appliances::thermostat::change_temperature": {
          "temperature": 23
        }
      },
      "id": 25,
      "message": "**Backup** was successfully finished.",
      "priority": 2,
      "title": "Backup"
    }
  ],
  "paging": {
    "limit": 123,
    "next": "/message?limit=50&since=123456",
    "since": 5,
    "size": 5
  }
}

Paging

object

The Paging holds information about the limit and making requests to the next page.

limitinteger<int64>[1, 200]requiredread only

The limit of the messages for the current request.

Example

nextstringread only

The relative path for the next page. Empty/Null when no next page is available. Should be combined with the gotify base url.

Example

/message?limit=50&since=123456

sinceinteger<int64>>= 0requiredread only

The ID of the last message returned in the current request. Use this as alternative to the next link.

Example

sizeinteger<int64>requiredread only

The amount of messages that got returned in the current request.

Example

PluginConf

object

Holds information about a plugin instance for one user.

authorstringread only

The author of the plugin.

Example

jmattheis

capabilitiesArray<string>required

Capabilities the plugin provides

Example

[
  "webhook",
  "display"
]

createdAtstring<date-time>requiredread only

The date the plugin was created.

Example

2019-01-01T00:00:00Z

enabledbooleanrequired

Whether the plugin instance is enabled.

Example

true

idinteger<int64>requiredread only

The plugin id.

Example

licensestringread only

The license of the plugin.

Example

MIT

modulePathstringrequiredread only

The module path of the plugin.

Example

github.com/gotify/server/plugin/example/echo

namestringrequiredread only

The plugin name.

Example

RSS poller

tokenstringrequired

The user name. For login.

Example

P1234

websitestringread only

The website of the plugin.

Example

gotify.net

Example

{
  "author": "jmattheis",
  "capabilities": [
    "webhook",
    "display"
  ],
  "createdAt": "2019-01-01T00:00:00Z",
  "enabled": true,
  "id": 25,
  "license": "MIT",
  "modulePath": "github.com/gotify/server/plugin/example/echo",
  "name": "RSS poller",
  "token": "P1234",
  "website": "gotify.net"
}

RegenerateTokenResponse

object

The RegenerateTokenResponse holds information about the response to the regenerate token action.

tokenstringrequiredread only

The new token.

Example

gtfya.e2NcJK7AenXBPIRB3S03JsBlmy0V6xP8h0hwSiAJae8

SecurityUpdateAction

object

The SecurityUpdateAction describes the details of a requested security update.

regenerateTokenboolean

Whether to regenerate the token. Your client token must be elevated to perform this action.

Example

true

SecurityUpdateActionResponse

object

The SecurityUpdateActionResponse holds information about the response to a security update request.

regenerateTokenRegenerateTokenResponse

The RegenerateTokenResponse holds information about the response to the regenerate token action.

Show child attributes

tokenstringrequiredread only

The new token.

Example

gtfya.e2NcJK7AenXBPIRB3S03JsBlmy0V6xP8h0hwSiAJae8

UpdateUserExternal

object

Used for updating a user.

adminbooleanrequired

If the user is an administrator.

Example

true

namestringrequired

The user name. For login.

Example

unicorn

passstring

The user password. For login. Empty for using old password

Example

nrocinu

User

object

The User holds information about permission and other stuff.

adminbooleanrequired

If the user is an administrator.

Example

true

createdAtstring<date-time>requiredread only

The date the user was created.

Example

2019-01-01T00:00:00Z

idinteger<int64>requiredread only

The user id.

Example

namestringrequired

The user name. For login.

Example

unicorn

UserPass

object

The Password for updating the user.

passstringrequired

The user password. For login.

Example

nrocinu

VersionInfo

object

VersionInfo Model

buildDatestringrequired

The date on which this binary was built.

Example

2018-02-27T19:36:10.5045044+01:00

commitstringrequired

The git commit hash on which this binary was built.

Example

ae9512b6b6feea56a110d59a3353ea3b9c293864

versionstringrequired

The current version.

Example

5.2.6