If you want to extend the functionality implemented in the example projects, or make your
own implementation, you can use the API explorer to learn about the REST endpoints,
parameters and return codes you can use.
Required parameters #
You can discover which parameters you need to send to the API for running a specific task
using the API explorer.
For example, if you want to create a new project, and you want to know what parameters are
needed, open the API Explorer https://api.kaleidosim.com/explorer and find the Projects
section.
Now click on /projects/create.
Inside the /projects/create section, the first thing that you will notice is that this endpoint
requires a request body with the following fields: name, version and simulationSoftware.
The example project in Python and Javascript contains an example about how you can send
these parameters inside the request body to the KaleidoSim API.
- For JavaScript, check the file src/api-requests/projects/createProject.js.
- For Python, check the file src/api_request/projects/create.py.
Let’s look at another example of the types of endpoints the API has. For some endpoints, you
need to send a parameter in the URL and not in the request body, for example, inside the
CaseRun section, open /caseRun/runCase/{caseId}.
The example projects in Python and Javascript have an example for sending this parameter
in the URL.
- For JavaScript, check the file src/api-requests/caseRun/runCase.js.
- For Python, check the file src/api_requests/run_case/run.py.
With these kinds of endpoints, you can spot the required parameter by looking for the curly
brackets { }.
KaleidoSim API Explorer documentation will show the required parameters or fields with a
red asterisk ‘*’ next to it.
To see which parameters are required, you click the Schema tag.
The schema data will show you the required parameters denoted by the red asterisks.
Responses #
Additionally, you can also see the different responses from the KaleidoSim API. If your
request succeeds, you will receive a response code 200 along with additional information
about the operation executed. For example, the create project endpoint will return an object
with the exact format displayed in the image.
If the request fails for any reason, you will receive a response code 422 and a message with
the details about the error.
Return codes #
The following table contains all the return codes that KaleidoSim API can return.
| Return Code | Description |
| 429 | Rate limit. |
| 422 | Request failure. |
| 403 | A two-factor authentication code is required for login. |
| 402 | The account has no CPU balance. |
| 400 | Bad request or Service startup .*** |
| 200 | Request successful. |
Case status #
The cases created in KaleidoSim API have a status assigned for each stage within the
system.
For example, when the case is new, the state is Open, and when the case is running the
case state is Running, and when the simulation is completed, the state is Completed.
In UI, the case status will look like this:
KaleidoSim API will return the status as string:
You can find a list of all possible states here:
The states for the API can be grouped into the following categories:
- Running states: VMRunningState, StartVMState.
- Processing states: OpenState, TerminatedRequestedState, AbortRequestedState,
UpdatingState. - Error states: FailedState, ResourceUnavailableState, SimulationCrashedState,
LicenseServerNotFoundState, ExperimentConfigurationFailureState. - Terminated states: TerminatedState, TerminatedRequestedState, AbortedState,
AbortRequestState, BalanceZeroTerminatedState, BalanceZeroAbortedState. - Successful state: CompletedState.
Any of the states that are mentioned in the GitHub repository and do not fall into any of the
categories mentioned above can be considered as processing state.
KaleidoSim API use these categories for the endpoint /projectRun/caseStatus/{projectId}
this endpoint returns a summary of the states of all your cases inside a project, you can see
that the response has grouped the states into the different categories mentioned above.
Download and Upload files #
For uploading files, KaleidoSim API will return a signed URL that can be used to upload a file into KaleidoSim files storage.
The endpoint files/getUploadSignedUrl will return the following, a “resumableUrl” that can be used for uploading a specific file to the cloud.
- For an example in JavaScript, check the JavaScript example project, specifically the file src/api-requests/files/uploadInputFile.js.
- For an example in Python, check the Python example project file in src/api_requests/files/upload_input_file.py.
For downloading files, KaleidoSim API will return a signed URL that can be used for downloading files from KaleidoSim files storage to your local computer.
● For an example in JavaScript, check the JavaScript example project, specifically the file src/api-requests/caseFiles/getDownloadURL.js.
● For an example in Python, check the Python example project file in src/api_requests/case_files/download_files.py.
Downloading files directly from the API gives you access to the cloud storage directly, so you
can download specific files or all of them.
Datetime representation #
In order to keep the date and time representation consistent across all the functionalities provided by KaleidoSim API, the date and time are formatted to the standard ISO 8601.
Authentication #
For accounts that have 2FA enabled, the 2FA code must be provided at the moment of login. You can enable 2FA in your account here: https://app.kaleidosim.com/authentication.
If your account has 2FA enabled, but you don’t provide the 2FA code, the API will return a 403 error.
Additionally, the authentication endpoint has a maximum number of 10 for failure logins, then
the user account will be blocked for 1 minute.
If the user needs to change their password, go here: https://app.kaleidosim.com/forgot-password.
Rate Limit #
KaleidoSim API implements a rate limit mechanism as protection against system abuse and DDoS attacks. The maximum number of requests that a user can make is 15 per second, if the maximum number of requests is exceeded, the API will return an error 429.
If you are making a basic implementation against the API, the simplest way to rate limit your requests is to wait 100ms before each request. For simple scripts, normally you shouldn’t experience any need to consider the rate limits. When polling for status, consider sleeping for 30 seconds between requests. For more complex integrations, using a rate limiter can really help.
Service startup #
One interesting characteristic of working with the cloud is that the services scale up and down operation depending on the system load. Due to the way our base cloud works, you may periodically receive a 400 error code when making a request. If this occurs, please check the error message received for the following text:
“This request caused a new process to be started for your application”
When this text occurs, please pause your request for 30 seconds, then retry.
The Python example project has an example code of a retry wrapper mechanism that detects this error and retry the request. Check the file src/http_requests/retry_wrapper.py.
