How To Use the OpenAPI Integration | ObjectSecurity OT.AI Platform

Modified on Mon, 16 Oct 2023 at 01:58 PM

To facilitate a transparent user experience and to enable full third-party integration with the ObjectSecurity OT.AI Platform, OpenAPI Initiative functionality is natively integrated into the platform.

The "OpenAPI Page" details the API routes for interacting with the OT.AI Platform. The API routes, corresponding description, and 'Send" button are all listed on the left panel. Clicking the "Send" button queries the route, producing output on the right panel. Additionally, you may toggle between different API routes via a dropdown menu:

Additionally, some API routes require additional parameters or arguments. These parameters and arguments are listed on the left panel if needed:


External Usage

Our API may also be queried externally from any network connection with access to your deployment. Depending on your deployment type, the URL used to query the routes will differ.

Offline/On-Prem Virtual Machine:

Typically, an Offline/On-Prem virtual machine will be accessible via localhost. In this case, the following URL format will suffice:


If your On-Prem virtual machine is hosted on a private network, the following URL format will suffice, with ip_address referring to the IP address of your deployment on your local network.


(The <route> here refers to any route described in the Available Routes section.)

Cloud Deployment:

For Cloud Deployments, the API will be accessible from anywhere on the Internet. The following URL will be used, with deployment_name referring to the name of your cloud deployment.


(The <route> here refers to any route described in the Available Routes section.)

Note on bearer token:

Most OT.AI Platform API routes require a Bearer authentication token. You can learn to get this Bearer token under Authentication in the Available Routes section.

You can read more about Bearer tokens here.

Available Routes

This section provides a general overview of the purpose and output of each route. Information regarding the specific parameters and exact output schema can be found in the application itself.


General routes handle the most basic usage of the OT.AI Platform, mainly including fetching data to view.

  • GET /assessor/getassets
    You can use this route to get a list of your assets. Assets have a set of binaries that have each been analyzed.

  • POST /assessor/getbinaries
    Use this route to get the set of analyzed binaries in a given asset.

  • POST /assessor/getresults
    Use this route to get analysis results for a given binary.

  • POST /assessor/getcwe
    Get additional information on specific CWEs.

Assessments & Analysis:

These routes handle the analysis process, including the ability to queue up and start various assessments.

  • GET /assessor/getassetprogress
    Gets the current analysis progress of all ongoing analyses in the user's current organization. 

  • GET /assessor/listbinaries
    Gets the set of binaries uploaded to the dropzone.

  • POST /saas/addfile
    Uploads a binary to the dropzone. 

  • POST /saas/rmfile
    Removes a binary from the dropzone.

  • POST /saas/start
    Starts the analysis procedure on the binaries in the dropzone. 

Asset Management:

These routes handle the managing of assets after they have been analyzed. Various actions can be taken on assets, including deleting or updating multiple asset fields.

  • GET /assessor/getnumnew
    Gets the number of new assets in an organization. New assets are those that haven't been viewed yet after being analyzed. 

  • POST /assessor/deleteasset
    Deletes an asset from an organization. 

  • POST /assessor/renameasset
    Renames an asset.

  • POST /assessor/update/assetdescription
    Updates an asset's description.

  • POST /assessor/updateassettype
    Updates an asset's type.

  • POST /assessor/markassetviewed
    Marks an asset as viewed.

  • GET /saas/asset/{assetid}/audit
    Gets the audit log for an asset. 

Facility Management:

These routes handle the management of facilities. Facilities each have a location and set of child assets located within the facility.

  • GET /assessor/getfacilities
    Gets all the facilities in the organization. 

  • POST /assessor/createfacility
    Creates a new facility.

  • POST /assessor/updatefacility
    Updates an existing facility. 

  • GET /assessor/getassetsinfacility/{facility_id}
    Get the assets in a facility.

  • GET /assessor/deletefacility/{facility_id}
    Deletes a facility. 

  • GET /assessor/getdefaultfacility
    Each organization has a default facility that cannot be deleted. All assets in an organization are analyzed in this default facility by default.


Authentication routes manage user login, role-based querying, and 2FA.

  • POST /saas/mfalogin
    Gets an "access_token" that may be set as the Bearer Token when calling the "/saas/validate_totp" route. This route acts as the first factor of 2-factor authentication. "/saas/validate_totp" acts as the second factor. 

  • GET /saas/generate_totp
    Generates a time-based one-time password for the current user. This TOTP can be converted into a QR code and scanned with Google Authenticator for 2 Factor Authentication.

  • POST /saas/validate_totp
    Validates a user's time-based one-time password and returns to them a token that may be set as the Bearer Token when accessing all other routes of the API. This route acts as the second factor of 2-factor authentication, with "/saas/mfalogin" being the first. 

  • POST /saas/auth/user/add
    Creates a new user.

  • POST /saas/auth/password
    Updates a user's password. 

  • GET /saas/auth/userinvite/user/{user_id}
    Invites a user to the server. Returns a token specific to the "user_id" set in the API route. The token may be redeemed by the user using the "/saas/auth/userinvite/redeem/{invite}" route. 

  • GET /saas/auth/userinvite/redeem/{invite}
    Redeems an invite generated using the "/auth/userinvite/user/{user_id}" route. Returns a token that may be used to set up a new account. 

  • POST /saas/auth/user/eula/accept
    Accepts the EULA for the calling user. 

  • GET /saas/auth/user/{userid}/profile
    Gets a user's profile.

Organization Management:

These routes handle the managing of organizations. Organizations each have a set of child facilities and a set of child users. Organizations may have multiple administrators. The server SUPERADMIN is a part of every organization, and there may only ever be one SUPERADMIN at a time.

  • GET /assessor/getdashboard
    Gets the data needed to generate the dashboard on the UI. 

  • GET /saas/auth/userall
    Gets all the users in an organization. 

  • POST /saas/auth/user/addroles
    Assigns a user new roles in an organization. This is equivalent to adding a user to an organization, should the user not already have roles in the organization.

  • POST /saas/auth/user/removeroles
    Remove roles from a user in an organization. This is equivalent to removing a user from an organization, should the user not have any remaining roles in the organization after this route has been called. 

  • POST /saas/auth/user/setorg
    Swaps the org a user is currently viewing.  

  • POST /saas/auth/organization/add
    Adds an organization.

  • POST /saas/auth/organization/update
    Updates an organization.

  • GET /saas/org/audit
    Gets the audit log of an organization. The audit log tracks the history of all analyzed assets in the organization. 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article