API functionality

[louislam]

Discussed in https://github.com/louislam/uptime-kuma/discussions/96

^{Originally posted by TheGuyDanish July 12, 2021} I'd love to see the ability to retrieve, update, remove or add monitors via API calls. Maybe using an API key that's tied to the user. In a way that when spinning up a new docker container or doing an automated workflow like Terraform, the new device could be added to the software automatically.

[Panja0]

API call for putting monitors on pause/unpause for an xx period would be awesome! We can than include the API call in a script before doing a restart on a server for instance.

[bsord]

Commenting as I too would love to see this functionality.

[jtagcat]

GitHub Etiquette

• Please use the 👍 reaction to show that you are affected by the same issue.
• Please don't comment if you have no relevant information to add. It's just extra noise for everyone subscribed to this issue.
• Subscribe to receive notifications on status change and new comments.

[deefdragon]

Some things, like that which is visible on the status page, are already readily accessible, just undocumented. The creation and deletion of monitors/notifications are some of the things that are not.

Thus this realistically sounds like a 2 part task.

1. Add the ability to use a key for api calls.
2. Document the API being used so that it can be easily interacted with.

[hypervtechnics]

Another endpoint I'd need is to read the the active incident information

[louislam]

Some things, like that which is visible on the status page, are already readily accessible, just undocumented. The creation and deletion of monitors/notifications are some of the things that are not.

Thus this realistically sounds like a 2 part task.

1. Add the ability to use a key for api calls.
2. Document the API being used so that it can be easily interacted with.

No, it should not be used in my opinion.

It is not the same thing, because these are internal APIs which I expected that it should be called from Uptime Kuma only. I could change API without any notices.

[deefdragon]

While I understand that the current calls are expected to be Uptime Kuma only, I really think it should be a single API instead of a public API and an internal API. The biggest reason is that maintaining multiple APIs for the same thing is a real pain. (I have personal experience on this from work. We had internal and external APIs for some products, and about one in 5 feature changes resulted in bugs, as changes were made to one API, but done incorrectly, or not at, all to the other).

Having a unified API has some other benefits as well:

• It Forces good documentation of the API, useful for developers and users.
• API changes would always get multiple pairs of eyes looking over them
• Obviously, each endpoint & the logic therein only has to be implemented once

I do understand the want to be able to iterate quickly, and change endpoints. This is still possible if the endpoints are versioned: alpha, beta, stable, deprecated etc. and would just require having a system around these changes. Something that should be considered anyways.

The biggest downside I can see is that the auth logic gets more complicated to account for the different ways the API is getting accessed. Given most of the work would be needed with separate APIs anyway, its not the worst thing.

[louislam]

Yes, I see your point.

I won't implement two sets of APIs, but as of 1.8.0, I labeled them as "internal APIs" that everyone should not use. In the future, I may re-label them as "public APIs" and documented it in the wiki once it get stable.

[deefdragon]

Kuma has changed a lot in the last few months, and will likely keep getting major changes for a while yet. Exposing the APIs now would likely be a pain point for anyone attempting to use them anyway.

I think reaching reasonable feature stability is a fair point to expose the apis. (perhaps as a 2.0 feature? Not sure your intended versioning scheme).

[alexschomb]

I couldn't find any explicit mentioning of it, so I'd like to add that it would be awesome to use the API with external monitoring tools like Zabbix, Monitoring Plugins (Nagios, Icinga, Check_Mk), ... That way Uptime-Kuma could be used as the external status page to these internal tools. Another side effect would be that Uptime-Kuma automatically gains thousands of more monitoring options without implementing them manually into this project.

[nicjansma]

This is a fantastic project, and I'm really interested in integrating Kuma into Home Assistant and other home-network things. I'd like an API for:

• Adding / removing monitors (I have hundreds of things I want to monitor and doing it by hand would be tedious)
• Checking the overall status of how many monitors are down
• Checking the status of specific monitors

@louislam would you be up for choosing a few core APIs that would be public and supported as such?

[jesperordrup]

Yes, I see your point.

I won't implement two sets of APIs, but as of 1.8.0, I labeled them as "internal APIs" that everyone should not use. In the future, I may re-label them as "public APIs" and documented it in the wiki once it get stable.

I would definatly chose otherwise. If you make your internal api and external api the same, you effectly put a stop to rapid development of solution.

I would countinue with the intenal api (for sure) I would create a the public api as a versionised api /api/v1/methods

Your internal api can expand change and do whatever you need in the speed you need.

The public api - of course just uses the nternal The public api carefully ensures that it doesnt change / expose features you dont want to expose.

[jiri]

I completely agree with the point that if providing a unified API isn't something that can be done fast, it's not worth the benefit. At this point, not having an API renders Uptime Kuma borderline unusable for me, because I frequently get notification of outages whenever a scheduled service update is in place -- being able to pause an unpause monitors with an API call would alleviate this issue completely.

This issue will soon have been opened for a year and new issues requesting an API keep being opened. I hardly see a core set of functionality (like CRUD on monitors) changing in the foreseeable future and I don't see a reason for stalling just because of a private API that doesn't affect regular users.

[RedLeeder]

I agree with the overall sentiment here. Having an accessible API is extremely helpful to developers and provides a ton of out-of-the-box functionality that you otherwise wouldn't have. I would suggest you reconsider the reluctance to implement this as it is a fairly large omission from the project as it stands now (to the point where, despite the otherwise great implementation, I personally would look for alternatives).

[alichaudry]

I love Uptime-Kuma, but it sounds like it's a no-go for a lot of folks here because of its lack of API support.

Something similar to Uptime-Kuma (for my purposes, anyway) while also allowing API access is Gatus. Might be worth looking into for folks who cannot live without API access to their health + monitoring tool.

(Disclaimer: I'm using both Uptime-Kuma + Gatus as I love exploring cool new homelab projects, but I can't wait to rely solely on Uptime-Kuma once API functionality is introduced into the project.)

[anthosz]

I love Uptime-Kuma, but it sounds like it's a no-go for a lot of folks here because of its lack of API support.

Something similar to Uptime-Kuma (for my purposes, anyway) while also allowing API access is Gatus. Might be worth looking into for folks who cannot live without API access to their health + monitoring tool.

(Disclaimer: I'm using both Uptime-Kuma + Gatus as I love exploring cool new homelab projects, but I can't wait to rely solely on Uptime-Kuma once API functionality is introduced into the project.)

Seems a read API only on Gatus so the issue is the same

[GVALFER]

i really consider this feature (API) very important. I really love thhe Kuma, but without API, it can not work for us :-(

[Computroniks]

I think that something that could be useful here is creating a list of the core APIs that would be useful and that people want. Then we could go about creating a spec using something like the OpenAPI fomat (https://swagger.io/specification/) After that, if we decide a standard way in which endpoints should be implemented, we could then divide up the endpoints between developers to distribute the workload more.

Using OpenAPI has the added benefit that it can be used to generate documentation that can provide examples of how to interface with the API. There are various generators to output it in pretty much any format you like, e.g PDF, HTML, markdown.

[jesperordrup]

@louislam any updates on how you think about this?

[anthosz]

I think that something that could be useful here is creating a list of the core APIs that would be useful and that people want. Then we could go about creating a spec using something like the OpenAPI fomat (https://swagger.io/specification/) After that, if we decide a standard way in which endpoints should be implemented, we could then divide up the endpoints between developers to distribute the workload more.

Using OpenAPI has the added benefit that it can be used to generate documentation that can provide examples of how to interface with the API. There are various generators to output it in pretty much any format you like, e.g PDF, HTML, markdown.

imo, can be interesting to be able to:

• search probe (by name or url)
• add probe (with all parameters available in uptime-kuma)
• modify probe (search by name or url and modify all parameters available in uptime-kuma)
• delete probe (search by name or url)

[Computroniks]

I have created a gist to act as a sort of list for suggested endpoints to try and help them from getting lost among comments https://gist.github.com/Computroniks/d04c2f42e430fd9f6656e40626cbdf0e

[iotemylabs]

@Computroniks might I add Pause Monitor in the Manage Monitor Endpoint as a POST request?

[rmawhinnie]

Uptime Kuma seems like a really neat project, however without an api to create/delete services, and pause/unapause , it creates toil tasks for people :(. keep up the good work,

[vumdao]

Unbelivable a high stared opensource project without API to automate things

[C-Duv]

You could at least have rephrased your message (ad?) to make it less mean…

[jiri]

@louislam This thread is getting somewhat derailed with most comments just re-emphasizing the desire for this feature. May I suggest constraining this issue to collaborators and writing down a definition-of-done for this feature, so it can be tracked properly? 😃

[PhakornKiong]

@louislam This thread is getting somewhat derailed with most comments just re-emphasizing the desire for this feature. May I suggest constraining this issue to collaborators and writing down a definition-of-done for this feature, so it can be tracked properly? 😃

+1

Would love to contribute to writing some of the API. Can we start a draft proposal using OpenAPI spec?

[Computroniks]

Would love to contribute to writing some of the API. Can we start a draft proposal using OpenAPI spec?

@PhakornKiong I created a basic list of the endpoints people suggested (https://gist.github.com/Computroniks/d04c2f42e430fd9f6656e40626cbdf0e) and was kind of waiting for some feedback from @louislam before I went on to doing the spec. I will probably create a draft (i.e version 0.0.1) spec at the weekend and put it in with the gist so that I can perhaps get some feedback on the parameters of the different endpoints.

[bluepuma77]

Would love to use uptime-kuma, but need an API to add 100+ services with URL.

"Add foundation for API development" https://github.com/louislam/uptime-kuma/pull/1834 seems to be stuck. It only has GET, no POST.

How can we support?

[lucasheld]

I have developed an Ansible collection of modules to configure Uptime Kuma with Ansible. Currently monitors, notifications, proxies, tags, monitor tags and status pages are supported. https://github.com/lucasheld/ansible-uptime-kuma

Under the hood, the Socket.IO API is used to communicate with Uptime Kuma. The Ansible modules are using a Python wrapper to communicate with the API. This Python module can also be used without Ansible. https://github.com/lucasheld/uptime-kuma-api

[lionep]

Nice work @lucasheld, the clean way to proceed IMO