Omada V2 API

This thread has been locked for further replies. You can start a new thread to share your ideas or ask questions.

Omada V2 API

This thread has been locked for further replies. You can start a new thread to share your ideas or ask questions.
Omada V2 API
Omada V2 API
2021-02-21 03:21:27 - last edited 2023-12-12 08:49:36
Tags: #API

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.

  0      
  0      
#1
Options
2 Accepted Solutions
Re:Omada V2 API-Solution
2022-02-14 13:35:52 - last edited 2023-12-12 08:49:07

  @straydog 

 

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}&currentPage=1&currentPageSize=1000"
Recommended Solution
  12  
  12  
#33
Options
Re:Omada V2 API-Solution
2023-12-12 08:48:22 - last edited 2023-12-12 08:48:37

Hi all,

 

I would like to provide updated information related to the Omada API here.

 

  1. 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)

 

    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).

 

  1. 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.

 

>> Omada EAP Firmware Trial Available Here << *Try filtering posts on each forum by Label of [Early Access]*
Recommended Solution
  2  
  2  
#52
Options
50 Reply
Re:Omada V2 API
2021-02-22 06:23:18 - last edited 2022-12-29 08:36:07

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.

File:
Omada_SDN_Controller_V4.1.5 API Document.zipDownload
>> Omada EAP Firmware Trial Available Here << *Try filtering posts on each forum by Label of [Early Access]*
  0  
  0  
#2
Options
Re:Omada V2 API
2021-07-03 20:20:02 - last edited 2022-12-29 08:36:07

@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.

  0  
  0  
#3
Options
Re:Omada V2 API
2021-07-08 02:44:39 - last edited 2022-12-29 08:36:07

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.

>> Omada EAP Firmware Trial Available Here << *Try filtering posts on each forum by Label of [Early Access]*
  0  
  0  
#4
Options
Re:Omada V2 API
2021-07-08 14:15:41 - last edited 2022-12-29 08:36:07

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

  0  
  0  
#5
Options
Re:Omada V2 API
2021-07-12 03:12:52 - last edited 2022-12-29 08:36:07

 

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&currentPage=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?

  0  
  0  
#6
Options
Re:Omada V2 API
2021-07-14 06:40:55 - last edited 2022-12-29 08:36:07

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.

>> Omada EAP Firmware Trial Available Here << *Try filtering posts on each forum by Label of [Early Access]*
  0  
  0  
#7
Options
Re:Omada V2 API
2021-07-27 19:29:01 - last edited 2022-12-29 08:36:07

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!

  0  
  0  
#8
Options
Re:Omada V2 API
2021-07-28 06:10:44 - last edited 2022-12-29 08:36:07

A complete OpenAPI document would be ideal - one can then generate a client from it.

  0  
  0  
#9
Options
Re:Omada V2 API
2021-07-28 23:25:34 - last edited 2022-12-29 08:36:07

 

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).

  0  
  0  
#10
Options
Re:Omada V2 API
2021-08-23 14:16:56 - last edited 2022-12-29 08:36:07

@Fae any update on complete API documentation?

  0  
  0  
#11
Options

Information

Helpful: 0

Views: 28191

Replies: 50

Tags

Related Articles