The Request Object

Basic Usage#

The JSON object that is sent to the API is comprised of three components:

  • auth [required]: An object used to identify the user.

  • options [optional]: An object used to set certain behaviours of the request.

  • functions [required]: An array of objects defining a sequence of functions you would like to run.

sample-request-object.json
{
"auth": {
"username": "YOUR_SKYCIV_USERNAME",
"key": "YOUR_SKYCIV_API_KEY"
},
"options": {
"validate_input": true
},
"functions": [
{
"function": "S3D.session.start",
"arguments": {
"keep_open": false
}
},
{
"function": "S3D.model.set",
"arguments": {
"s3d_model": MODEL_OBJECT
}
},
{
"function": "S3D.model.solve",
"arguments": {
"analysis_type": "nonlinear",
"repair_model": true
}
}
]
}

auth#

The JSON object that is sent to the API must contain the auth key at the top level of the object. The auth object takes the following properties:

KeyTypeDescription
username (required)stringYour SkyCiv username used to sign into the platform.
key (optional)stringYour SkyCiv API key from the account settings page.
session_id (optional)stringThe session_id provided in the response from the first call to the API. Providing this session_id in lieu of key will allow you to skip the verification process for subsequent calls within 30 minutes of the first call.

The initial call object:

auth-for-new-session.json
{
"auth": {
"username": "YOUR_SKYCIV_USERNAME",
"key": "YOUR_API_KEY"
}
// ...other components
}

Subsequent calls object (within 30 mins of making the initial call):

auth-for-subsequent-sessions.json
{
"auth": {
"username": "YOUR_SKYCIV_USERNAME",
"key": "YOUR_API_KEY",
"session_id": "SESSION_ID_FROM_FIRST_API_CALL"
}
// ...other components
}
important

If you provide key and session_id, the session ID will be used to authenticate. If the session ID has expired, the key will be used to start a new session. If key is not provided and the provided session ID has expired, the request will fail.

username (required)#

The username property should have a string value of your SkyCiv username.

key (optional)#

The key property should contain a string value of your SkyCiv API key. This can be obtained from the account settings page. If this is not provided, then session_id is required.

session_id (optional)#

Providing the session_id property in lieu of key will allow you to skip the verification process for subsequent calls within 30 minutes of the first call. If the session_id property is not provided, you must provide key.

When using the S3D.session.start function, you can opt to keep your session open by setting the keep_open property to true. This means that after you run a batch of functions, you can keep the session open for 30 minutes. This allows you to re-visit the session without having to re-authenticate therefore increasing the speed of subsequent calls.

If you set the keep_open property to true, the API will return a last_session_id that you can use for the next authentication. The code block below shows the response from the initial call containing the last_session_id:

sample-response.json
{
"response": {
"data": {},
"msg": "Solved Successfully!",
"comments": " Linear Static Analysis Completed ",
"status": 0,
"function": "S3D.model.solve",
"last_session_id": "esz8ITRreJoaQsm6GRebHhxz9xg3qYhXDl6cTy88CLEdQolVcgpbf8bp7dCiuk99_2",
"monthly_api_credits": { "quota": 500, "total_used": 113, "used_this_call": 1 }
},
"functions": []
}

options#

The options property allows you to provide an object which specifies certain behaviours of the request. The options object accepts the following values:

KeyTypeDescriptionDefault
validate_input (optional)booleanVerify the model input with SkyCiv's built in model validator.false
response_data_only (optional)booleanOnly respond with data from the last function specified in the functions array.false
timeout (optional)intTimeout override option (in ms). Only implement in calls that need more time to complete. Otherwise, by default SkyCiv will use smarter timeout times based on the function and model size attemptedfalse
return_log (optional)booleanReturns a log of the API processes, useful for debuggingfalse
response_webhook_url (optional)stringLonger API calls can be returned to the user via a user-defined webhook URL. Include a URL here and your response will be sent here rather than back to the clientfalse

validate_input (optional)#

The validate_input property indicates if your input should be verified. If true is provided, a fast and descriptive response will be returned if there is any issues with the input. It is not recommended to omit this key (or use false) unless you are confident of the API call input data.

response_data_only (optional)#

The API response contains the following components:

  • response (object) - Contains the data from the final function and some other useful information.
  • functions (array) - Each object in this array provides results for the respective function.

To keep the response size down, you can set response_data_only to true. This means you will only receive the response object. This will contain the data from the last function called. response_data_only defaults to false.


functions#

The functions property takes an array of objects - each object defines a function to be executed. The functions should be in order of desired execution.

Common arguments#

KeyTypeAcceptsDescriptionDefault
return_databooleantrue, falseOmits data object from the response for the respective function.false

The following is a list of available functions:

Session#

Model#

Results#

Design#

Standard member design#

Reinforced concrete design#

Section builder#

File management#

Standalone design#

Foundation design#

Member design#

Loads#