The AMI REST server is used for providing information about the AMI session and the VM it's running in.
Generally, the REST endpoints are in two categories:
Retrieving information about the AMI session. This includes information on JVM memory usage, user statistics, and more.
Querying the AMI Center. This involves sending commands into the center and requires authentication.
The default endpoint of the REST server is attributed to the web server's own ports followed by the REST query. For example: "localhost:33332/3forge_rest/stats".
To configure your AMI session's REST Server API, see the following full list of properties. Otherwise, for a minimal configuration see the setup below.
The default endpoints supplied by AMI are primarily aimed at developers to debug and retrieve information about the JVM state of the AMI session.
While some endpoints are publicly available, others require admin or dev access. See the below table for a list of the default endpoints and their access requirements.
Endpoint
Description
Authentication Required
Admin Only
Params
/3forge_rest/version
Returns detailed version information about the AMI session
display=json or display=text
/3forge_rest/whoami
Returns the username and properties
display=json or display=text
/3forge_rest/whatsmyip
Returns the IP address of the client accessing the endpoint
display=json or display=text
/3forge_rest/stats
Public endpoint that returns statistics about the VM
display=json or display=text
/3forge_rest/query?
Executes a command against the center and returns the result sets. See here for more information on query commands and parameters
For the simplest authentication setup that uses a combination of an AMI user's username and password, see the instructions below.
When accessing an endpoint that requires authorization via browser links, i.e: navigating to http://localhost:33332/3forge_rest/version, you will be prompted to login.
Enter your AMI username and password details in the pop-up.
To send a curl request via a terminal, supply the username and password token using the Basic Authentication flag:
These are examples of queries that can be passed to the REST API.
Examples assume the following that the AMI session is being hosted on your local machine with default ports (localhost:33332). Please change these details according to your setup.
Output from hitting the endpoint with no additional parameters (http://localhost:33332/3forge_rest/version), or with display=text (http://localhost:33332/3forge_rest/version?display=text)
This will return a webpage with information similar to the following:
3forge AMI Version: version
+----------------------------------
| Visit http://3forge.com
| 3forge.com
+----------------------------------
| Startup Time: Thu May 01 10:10:18 BST 2025
| Working Dir: C:/Program Files/ami_dev/amione
| Local Host: PC_NAME
| Pid: 6164
| F1 ProcessUid: F1-c2kVn5PI9DUgPZ0GE8lY0i
| CPU Count: 14
| Avail.Memory: 3.78 GB (4,054,319,104 B)
| Line Seperator: \r\n
| Java Home: c:\program files\ami_dev\jre
| Java Version: 1.8.0_242
| Java Vendor: AdoptOpenJDK
| Java Compiler: null
| RC5 Strength: unlimited
| OS - Version: Windows 10 - 10.0
| OS Arch.: amd64
| Current Time: Thu May 01 10:21:34 BST 2025
| Default TimeZone: Europe/London
| Default Charset: UTF-8
| Default Country: GB
| Default Language: en
| User: User
| User Home: C:\Users\User
+----------------------------------
| License App: amione
| License Instance: id=717021
| License Host: latitude5350-1
| License Start Date: 20250120
| License End Date: 20260101
| License Text: 3FKEY|amione|id=717021|PC_NAME|start_date|end_date|license_key
+----------------------------------
| Max Code Cache: 240.00 MB (251,658,240 B)
| Max Metaspace: -1 (-1 B)
| Max Compressed Class Space: 1,024.00 MB (1,073,741,824 B)
| Max Par Eden Space: 732.19 MB (767,754,240 B)
| Max Par Survivor Space: 91.50 MB (95,944,704 B)
| Max CMS Old Gen: 2.97 GB (3,190,620,160 B)
+----------------------------------
| Java Ext. Dirs.: c:\program files\ami_dev\jre\lib\ext
| C:\WINDOWS\Sun\Java\lib\ext
+----------------------------------
| Java Classpath: C:\Program Files\ami_dev\.install4j\i4jruntime.jar (cksum 1291145369 1946822)
| C:\Program Files\ami_dev\amione\..\amione\lib\autocode.jar (cksum 3575987261 4746753)
| C:\Program Files\ami_dev\amione\..\amione\lib\ch.ethz.ganymed-ganymed-ssh2-262.jar (cksum 1554228428 307216)
....
Output from hitting the endpoint with the additional display=json parameter (http://localhost:33332/3forge_rest/version?display=json).
This will return a webpage similar to the following:
Navigate between the different headers. To view/download the raw JSON, select the "Raw Data" tab. Below is a sample of the Pretty Print formatted JSON output from this endpoint:
Output from hitting the endpoint with no additional parameters (http://localhost:33332/3forge_rest/whoami), or with display=text (http://localhost:33332/3forge_rest/whoami?display=text)
This will return a webpage with information similar to the following:
Output from hitting the endpoint with the additional display=json parameter (http://localhost:33332/3forge_rest/whoami?display=json).
This will return a webpage similar to the following:
Navigate between the different headers. To view/download the raw JSON, select the "Raw Data" tab. Below is a sample of the Pretty Print formatted JSON output from this endpoint:
Output from hitting the endpoint with no additional parameters (http://localhost:33332/3forge_rest/whatsmyip), or with display=text (http://localhost:33332/3forge_rest/whatsmyip?display=text)
This will return a webpage with information similar to the following:
Output from hitting the endpoint with the additional display=json parameter (http://localhost:33332/3forge_rest/whatsmyip?display=json).
This will return a webpage similar to the following:
Navigate between the different headers. To view/download the raw JSON, select the "Raw Data" tab. Below is a sample of the Pretty Print formatted JSON output from this endpoint:
Output from hitting the endpoint with no additional parameters (http://localhost:33332/3forge_rest/stats), or with display=text (http://localhost:33332/3forge_rest/stats?display=text)
This will return a webpage with information similar to the following:
========= JAVA VIRTUAL MACHINE =========
Start Time: 2025-05-01 09:10:18.094 GMT
Now: 2025-05-01 10:22:14.547 GMT
CPU Used: 8.12%
Threads Used: 32.46%
Estimated Memory Used: 2.88%
Used Memory: 111.57 MB
Used Memory After GC: 84.59 MB
Max Memory: 3.78 GB
Total Memory: 239.75 MB
Garbage Collections: 81
Total Threads: 77
Running Threads: 25
================= WEB ==================
logins: 1
sessions: 1
Output from hitting the endpoint with the additional display=json parameter (http://localhost:33332/3forge_rest/stats?display=json).
This will return a webpage similar to the following:
Navigate between the different headers. To view/download the raw JSON, select the "Raw Data" tab. Below is a sample of the Pretty Print formatted JSON output from this endpoint:
Output from hitting the endpoint with no additional parameters (http://localhost:33332/3forge_rest/query?cmd=SHOW+TABLES), or with display=text (http://localhost:33332/3forge_rest/query?cmd=SHOW+TABLES&display=text)
This will return a webpage with information similar to the following:
Output from hitting the endpoint with the additional display=json parameters, of which there are several. Please refer to the table above for the different options.
This will return a webpage similar to the following:
Navigate between the different headers. To view/download the raw JSON, select the "Raw Data" tab.
Listed below are samples of Pretty Print formatted JSON from the different display options: