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.true
response_data_only (optional)booleanOnly respond with data from the last function specified in the functions array.false

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 recommended to omit this key unless confident.

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#