Gotify

Gotify REST-API.

This is the documentation of the Gotify REST-API. Authentication In Gotify there are two token types: __clientToken__: a client is something that receives…

Communication#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

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

Endpoints 42

application

  • GETReturn all applications./application
  • POSTCreate an application./application
  • PUTUpdate an application./application/:id
  • DELETEDelete an application./application/:idRequires elevated authentication.
  • POSTUpload an image for an application./application/:id/image
  • DELETEDeletes an image of an application./application/:id/image
  • PUTPerform security updates on an application./application/:id/securityRequires elevated authentication.

message

  • GETReturn all messages from a specific application./application/:id/message?limit=100&since=0
  • DELETEDelete all messages from a specific application./application/:id/message
  • GETReturn all messages./message?limit=100&since=0
  • POSTCreate a message./message__NOTE__: When authenticating with a client token or basic auth, the request body must include "appid" referencing an application owned by the authenticated…
  • DELETEDelete all messages./message
  • DELETEDeletes a message with an id./message/:id
  • GETWebsocket, return newly created messages./stream

auth

  • POSTAuthenticate via basic auth and create a session./auth/local/login
  • POSTEnd the current session./auth/logoutClears the session cookie and deletes the associated client.

oidc

  • GETHandle the OIDC provider callback (browser)./auth/oidc/callback?code=string&state=stringExchanges the authorization code for tokens, resolves the user, creates a gotify client, sets a session cookie, and redirects to the UI.
  • GETStart the OIDC flow to elevate an existing client session (browser)./auth/oidc/elevate?id=0&durationSeconds=0Redirects the user to the OIDC provider's authorization endpoint. After successful authentication, the referenced client session is elevated for the requested…
  • POSTInitiate the OIDC authorization flow for a native app./auth/oidc/external/authorizeThe 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…
  • POSTExchange an authorization code for a gotify client token./auth/oidc/external/tokenAfter 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…
  • GETStart the OIDC login flow (browser)./auth/oidc/login?name=stringRedirects the user to the OIDC provider's authorization endpoint. After authentication, the provider redirects back to the callback endpoint.

client

  • GETReturn all clients./client
  • POSTCreate a client./client
  • PUTUpdate a client./client/:id
  • DELETEDelete a client./client/:idRequires elevated authentication.
  • POSTElevate a client session./client/:id/elevateRequires elevated authentication.

user

  • GETReturn the current user./current/userRequires elevated authentication.
  • POSTUpdate the password of the current user./current/user/passwordRequires elevated authentication.
  • GETReturn all users./userRequires elevated authentication.
  • POSTCreate a user./userWith enabled registration: non admin users can be created without authentication. With disabled registrations: users can only be created by admin users with…
  • GETGet a user./user/:idRequires elevated authentication.
  • POSTUpdate a user./user/:idRequires elevated authentication.
  • DELETEDeletes a user./user/:idRequires elevated authentication.

info

  • GETGet gotify information./gotifyinfo
  • GETGet health information./health
  • GETGet version information./version

plugin

  • GETReturn all plugins./plugin
  • GETGet YAML configuration for Configurer plugin./plugin/:id/config
  • POSTUpdate YAML configuration for Configurer plugin./plugin/:id/config
  • POSTDisable a plugin./plugin/:id/disable
  • GETGet display info for a Displayer plugin./plugin/:id/display
  • POSTEnable a plugin./plugin/:id/enable

API details

Base URL
https://localhost
Authentication
An API key in the Authorization header
An API key in the X-Gotify-Key header
An API key in the token query parameter
HTTP Basic authentication (username and password)
An API key in the Authorization header
An API key in the X-Gotify-Key header
An API key in the token query parameter
Operations
42 operations on 30 pathsGET 17POST 15DELETE 7PUT 3
Main resources
application 7message 7user 7plugin 6client 5oidc 5info 3auth 2
Response formats
application/json
Description format
Swagger 2.0, API version 2.1.0

How to test the Gotify REST-API. in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Gotify REST-API. collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Return all applications.” (GET /application), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Gotify REST-API.?

This is the documentation of the Gotify REST-API. Authentication In Gotify there are two token types: __clientToken__: a client is something that receives… It is listed under Communication and has 42 endpoints.

Who publishes the Gotify REST-API.?

It is listed from Gotify's public API description (an OpenAPI document), not published by Gotify on Swastik Codes. Anyone who controls gotify.net can claim the profile by adding a DNS TXT record.

What is the base URL of the Gotify REST-API.?

Requests go to https://localhost. Endpoint paths are added to this base URL.

How do I authenticate with the Gotify REST-API.?

It accepts 7 methods: an API key in the Authorization header; an API key in the X-Gotify-Key header; an API key in the token query parameter; HTTP Basic authentication (username and password); an API key in the Authorization header; an API key in the X-Gotify-Key header; an API key in the token query parameter.

How many endpoints does the Gotify REST-API. have?

42 operations on 30 paths (17 GET, 15 POST, 7 DELETE, 3 PUT). The largest groups are application, message, user, plugin.

Is forking the Gotify REST-API. free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.