How to use the API?

I would like to do some actions on my YunoHost instance without using the moulinette CLI or the admin page. I noticed there was an API already developed and documented:

So any idea on how to use it please? Which URL should I call or curl?


The address for the API should be

Hello and thanks,
That’s the address I use for the web interface yes, but can I interact with it using CURL or http requests?
I tried to add “/domains?api_key=mypassword” to this URL without success


Hello @scith,

You can use the API at the URL https://maindomain.tld/yunohost/api. There is a lot of work to do to document it, sorry about that!
You try to guess with the admin_js, but basically you just have make a POST with password as argument to the route /login - which will set a session cookie - and then call the route you want.

Happy hacking!

Thanks a lot, it works now!! :smile:

Here are the commands to login and then work with the API:


curl -k -d "password=XXX" --dump-header headers https://domain/yunohost/api/login


curl -k -i -H "Accept: application/json" -H "Content-Type: application/json" -L -b headers -X GET https://domain/yunohost/api/ROUTE | grep }| python -mjson.tool

All functions are then documented here:

1 Like

I can’t find a way to get Yunohost API work!

I have tried your command to login but I get this reply :

            <title>Error: 403 Forbidden</title>
            <style type="text/css">
              html {background-color: #eee; font-family: sans;}
              body {background-color: #fff; border: 1px solid #ddd;
                    padding: 15px; margin: 15px;}
              pre {background-color: #eee; border: 1px solid #ddd; padding: 5px;}
            <h1>Error: 403 Forbidden</h1>
            <p>Sorry, the requested URL <tt>&#039;http://XXX/login&#039;</tt>
               caused an error:</p>
            <pre>CSRF protection</pre>

Seems like your post is old and some “CSRF protection” has been implemented in the meantime. Do you know how can I do?

Moreover, if I use the command provided in docs (curl -k -H "X-Requested-With: customscript" -d "password=adminPassword" --dump-header headers https://XXX/yunohost/api/login) I get this reply :
Missing credentials parameter%

What can I do? I’d like to do some testing with the YNH API

Should be something like:

curl -H "X-Requested-With: whatever" -F credentials=admin:TheSuperAdminPassword https://domain.tld/yunohost/api/login

Unfortunately, this request doesn’t work. Even though I replace the password with my admin password, I get an error Invalid password.
I have also tried to replace admin by my admin username but still no luck.
I really run out of options to make it work, and it really is discouraging :confused:

Edit : Okay I could log in using curl -k -H "X-Requested-With: whatever" -F credentials=AdminPassword
but now I can’t make requests…
If I run something like this for example: curl -k -i -H "Accept: application/json" -H "Content-type: application/json" -L -b headers -o test.txt -X GET | grep } | python -mjson.tool nothing happens

Yeah I had some trouble with probably saving / reusing the cookie from the initial curl request …

It’s a bit cumbersome to do all this using just curl requests … I would really encourage you to use some Python script but it depends on what exactly you’re trying to achieve with what constrains

Okay thanks.
Our end goal would be to automate the process of creating new Yunohost users because we are in the process of migrating a discourse instance with +1k to a new Discourse instance linked with Yunohost, Yunohost being the “backend” for managing users and apps (we would like to integrate Bookstack as well). LDAP would help us to bridge all of this.

I know this isn’t quite what Yunohost is designed for at the beginning but it’s klnda cool to challenge Yunohost more and more.
We have started with the new Ansible role ( and it’s evolving into a collection with new automated features.
This migration is our next big challenge^^

In that case I would really encourage you to use Yunohost as a Python lib (though that’s assuming that the script runs as root … ) with something like:

import sys
sys.path.insert(0, "/usr/lib/moulinette/")
import yunohost
yunohost.init_logging() # possibly set debug=True if needed, but when writing script supposedly you ain't debugging yunohost itself, and full log is still available in yunohost-cli.log and yunohost log list...

from yunohost.user import user_create

user_create(username="foo", ...)

Note that this is going to be simplified with Bullseye, as Yunohost will be installed similarly to a “regular” python lib in /usr/lib/python3/dist-packages, therefore the two first lines should become uneccesary

1 Like

Okay thanks I will try this out!