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.

[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?

[Tealk]

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.

is there anything new about this, the discussion function seems to no longer exist?

I would like to control the maintenance function via API, as I could update all my services via Ansible. This could be very easily integrated

[CommanderStorm]

Please refer to #3854 our the draft/plan to implement this.
Please refer to #4500 for the things that are needed for the current release and how helping out can help get this done faster.

Tip

In the meantime, you can temporarily rely on an external/third party tool. (Make sure to audit their software, this is not something we have capacity for):

• cli https://github.com/BigBoot/AutoKuma?tab=readme-ov-file#kuma-cli--
• python https://pypi.org/project/uptime-kuma-api/
• http https://github.com/MedAziz11/Uptime-Kuma-Web-API

[paul-uz]

Any update on this?