Omada V2 API
This thread has been locked for further replies. You can start a new thread to share your ideas or ask questions.
How does one get info on the V2 API? I see on previous posts it was provided for V1, but nothing on the newest. I am currently running the Omada V4 Controller Software.
Example - https://community.tp-link.com/en/business/forum/topic/156627
Please advise.
- Copy Link
- Subscribe
- Bookmark
- Report Inappropriate Content
Here is an example that I have validated to work on version 5.0.30: https://gist.github.com/mbentley/03c198077c81d52cb029b825e9a6dc18
Also copied here for completeness:
# set variables
OMADA_URL="https://omada.example.com:8443"
USERNAME="admin"
PASSWORD="test12345"
# get controller id from the API
CONTROLLER_ID="$(curl -sk "${OMADA_URL}/api/info" | jq -r .result.omadacId)"
# login, get token, set & use cookies
TOKEN="$(curl -sk -X POST -c "/tmp/omada-cookies.txt" -b "/tmp/omada-cookies.txt" -H "Content-Type: application/json" "${OMADA_URL}/${CONTROLLER_ID}/api/v2/login" -d '{"username": "'"${USERNAME}"'", "password": "'"${PASSWORD}"'"}' | jq -r .result.token)"
# once logged in, make sure you add the following header on additional API calls:
# -H "Csrf-Token: ${TOKEN}"
# validate login
curl -sk -X GET -b "/tmp/omada-cookies.txt" -H "Content-Type: application/json" -H "Csrf-Token: ${TOKEN}" "${OMADA_URL}/${CONTROLLER_ID}/api/v2/loginStatus?token=${TOKEN}" | jq .
# example to get info on the current user
curl -sk -X GET -b "/tmp/omada-cookies.txt" -H "Content-Type: application/json" -H "Csrf-Token: ${TOKEN}" "${OMADA_URL}/${CONTROLLER_ID}/api/v2/users/current?token=${TOKEN}¤tPage=1¤tPageSize=1000"- Copy Link
- Report Inappropriate Content
Hi all,
I would like to provide updated information related to the Omada API here.
- About Omada API Documentation
Currently, Omada API can be classified into Web API and Open API, whose documentations are different.
- The attachment is the latest Omada Web API documentation, which is mainly applicable to Omada SDN Controller v5.9.
Notes:
1) Web API may change with Omada Controller version iterations. The attached Web API documentation shall only be used as
a reference to other Omada SDN Controller versions.
2) For API samples, please refer to API and Code Sample for External Portal Server (Omada Controller 5.0.15 or above)
- Here is the online documentation for Omada Open API: https://use1-omada-northbound.tplinkcloud.com/doc.html#/home
Notes:
1) All Omada Pro versions support Open API.
2) Omada Software/Hardware Controller support Open API since Controller v5.12.
3) Omada Cloud-Based Controller (CBC) does NOT support Open API yet (as of December 12, 2023).
- About Omada API Version
The “v2” mentioned in the API request example “${OMADA_URL}/${CONTROLLER_ID}/api/v2/users/…” is actually the version of the Omada Web API. Please note that Omada Open API currently only has the V1 version.
- Copy Link
- Report Inappropriate Content
Dear @sic,
How does one get info on the V2 API? I see on previous posts it was provided for V1, but nothing on the newest. I am currently running the Omada V4 Controller Software.
Example - https://community.tp-link.com/en/business/forum/topic/156627
Here is the API for Omada Controller V4.1.5 for your reference.
- Copy Link
- Report Inappropriate Content
@Fae This is great. But I'm having a couple of issues with the API on v4.4.3 of the controller.
- The path /api/v2/sites/{siteKey}/clients returns an error. Has this been removed?
- The path /api/v2/sites/{siteKey}/insight/clients works, but only returns 10 clients. The JSON shows:
"currentPage": 1,
"currentSize": 10,- How can the size and page be updated? It doesn't appear to be covered in the API document.
Is there a place that we can find the updated API documentation (this should be published on the site somewhere)?
Thanks, the API documentation you provided has been a real help.
- Copy Link
- Report Inappropriate Content
Dear @OneFix,
OneFix wrote
- The path /api/v2/sites/{siteKey}/clients returns an error. Has this been removed?
- The path /api/v2/sites/{siteKey}/insight/clients works, but only returns 10 clients. The JSON shows:
"currentPage": 1,
"currentSize": 10,
- How can the size and page be updated? It doesn't appear to be covered in the API document.
Just confirmed the information for you, here is the answer:
No, both paths haven't been adjusted/removed, but paging queries are required.
"currentPage" refers to the current page number, it is populated with 1 by default;
"currentPageSize" refers to the number of clients displaying on each page, and it's populated with 10 by default.
The above fields are not populated by default on the interface /api/v2/sites/{siteKey}/clients, so it returns an error.
I think you can modify the currentPage and currentSize to check more clients.
- Copy Link
- Report Inappropriate Content
@Fae Thanks for the pointer to the API; excuse my ignorance, but where is the definition of the POST payloads? For example for `login` API call?
- Copy Link
- Report Inappropriate Content
Fae wrote
Dear @OneFix,
OneFix wrote
- The path /api/v2/sites/{siteKey}/clients returns an error. Has this been removed?
- The path /api/v2/sites/{siteKey}/insight/clients works, but only returns 10 clients. The JSON shows:
"currentPage": 1,
"currentSize": 10,
- How can the size and page be updated? It doesn't appear to be covered in the API document.
Just confirmed the information for you, here is the answer:
No, both paths haven't been adjusted/removed, but paging queries are required.
"currentPage" refers to the current page number, it is populated with 1 by default;
"currentPageSize" refers to the number of clients displaying on each page, and it's populated with 10 by default.
The above fields are not populated by default on the interface /api/v2/sites/{siteKey}/clients, so it returns an error.
I think you can modify the currentPage and currentSize to check more clients.
Thanks, the API document doesn't seem to mention the proper way to modify the currentPage and currentPageSize settings.
I seem to have gotten it working with the insights page. For anyone interested, It is:
/api/v2/sites/{siteKey}/insight/clients?currentPageSize=999¤tPage=1 (there seems to be no upper limit on currentPageSize)
But, the interface /api/v2/sites/{siteKey}/clients still returns a "General Error" even when I add the currentPageSize and currentPage parameters.
Do you have any information on how to do this correctly?
- Copy Link
- Report Inappropriate Content
Dear @OneFix,
OneFix wrote
But, the interface /api/v2/sites/{siteKey}/clients still returns a "General Error" even when I add the currentPageSize and currentPage parameters.
Do you have any information on how to do this correctly?
Sorry, there is another parameter to verify, that is "filters.active=true", which refers to check the online clients.
Note: the current controller doesn't support checking the offline clients.
- Copy Link
- Report Inappropriate Content
Do you have a complete/functional v2 API document? Preferably a Swagger/OpenAPI version? The v2 API document referenced above contains the HTTP verbs and URLs but doesn't provide any of the JSON request payloads or example JSON responses. Thanks!
- Copy Link
- Report Inappropriate Content
A complete OpenAPI document would be ideal - one can then generate a client from it.
- Copy Link
- Report Inappropriate Content
ZdenekM wrote
A complete OpenAPI document would be ideal - one can then generate a client from it.
Agreed, that is actually what I was working on building (a Python module to be specific).
- Copy Link
- Report Inappropriate Content
@Fae any update on complete API documentation?
- Copy Link
- Report Inappropriate Content
Information
Helpful: 0
Views: 34140
Replies: 50
Voters 0
No one has voted for it yet.