SkyCiv Core API Skill

You are an agent that interacts with the SkyCiv API. This skill covers authentication, session management, the request/response envelope, and all common patterns shared across every SkyCiv API function.

API Endpoint

All requests are HTTP POST to:

https://api.skyciv.com/v3

Content-Type must be application/json.

Request Object Structure

Every API call sends a single JSON body with three top-level keys:

{
  "auth": { ... },       // required
  "options": { ... },    // optional
  "functions": [ ... ]   // required — ordered array of functions to run
}

auth

First call — always provide key:

{
  "auth": {
    "username": "user@example.com",
    "key": "YOUR_API_KEY"
  }
}

Subsequent calls within 30 min — provide both to allow automatic fallback if session expires:

{
  "auth": {
    "username": "user@example.com",
    "key": "YOUR_API_KEY",
    "session_id": "SESSION_ID_FROM_PREVIOUS_RESPONSE"
  }
}

When session_id is valid it is used; if expired, key starts a fresh session. If key is absent and session_id is expired, the call fails.

options

All fields optional.

{
  "options": {
    "validate_input": true,
    "response_data_only": false
  }
}

functions

An ordered array of function objects. Functions execute sequentially. Each object must have:

{
  "function": "Namespace.function.name",
  "arguments": { ... }
}

return_data (boolean, default false) can be added to any function object to omit that function's data from the response.

S3D.session.start

Must always be the first function in the array — even when reusing a session_id.

{
  "function": "S3D.session.start",
  "arguments": {
    "keep_open": true
  }
}

Response includes:

{
  "response": {
    "session_id": "Ofd4WYH...",
    "last_session_id": "Ofd4WYH...",
    "session_expiry_time": 1605153571,
    "msg": "S3D session successfully started.",
    "status": 0,
    "function": "S3D.session.start"
  }
}

Store last_session_id for the next call's auth.session_id.

Response Object Structure

{
  "response": {
    "data": { ... },
    "msg": "Human-readable message",
    "status": 0,
    "function": "last-function-name",
    "last_session_id": "...",
    "monthly_api_credits": {
      "quota": 6000,
      "total_used": 22,
      "used_this_call": 1
    }
  },
  "functions": [
    { /* result for functions[0] */ },
    { /* result for functions[1] */ },
    { /* ... */ }
  ]
}

Always check response.status === 0 before using results.

Full Minimal Example

Session start → set model → solve:

{
  "auth": {
    "username": "user@example.com",
    "key": "YOUR_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": "linear" }
    }
  ]
}

Available Function Namespaces

Common Patterns

Check success before using data:

if (response.status === 0) {
  const data = response.data;
} else {
  console.error(response.msg);
}

Minimise response size with filters:
Use result_filter and lc_filter in solve/results calls to return only what you need. Only if you're confident that load combination exists.

Reuse sessions for speed:
Set keep_open: true in S3D.session.start, then pass the returned last_session_id as auth.session_id in subsequent calls. This skips re-authentication and is 4–8× faster.

Troubleshooting

"Your API credentials could not be authenticated. Please try again." / any auth-rejection response.msg: This message comes straight from the live API when auth.username/auth.key don't validate — it is not something a client can trigger by sending a malformed request shape (a shape bug produces a different kind of error, e.g. about the missing/invalid field itself). If you see this and the {username, key} shape already matches this skill's docs exactly, don't keep editing the request code looking for a bug — the credentials themselves are almost certainly the problem:

• Confirm this same failure reproduces across every function call in the account (e.g. a plain S3D.model.solve and a standalone.loads.*/cloudcad.* call), not just one namespace — if it's every call, that confirms it's account-wide, not specific to whichever call you were debugging.
• Re-copy the username (account email) and API key fresh from https://platform.skyciv.com/api — a stale, truncated, or wrong-field value pasted into .env (or wherever credentials are stored) is the most common cause. A real SkyCiv API key is a long alphanumeric string (tens of characters); a much shorter value is a strong signal something got truncated or the wrong value was pasted.
• If credentials are loaded from a .env file via dotenv, double check the value actually landed in .env (the file actually read at runtime) and not just .env.example (a template file, not loaded by the app) — easy to mix up when copying a real key in for local testing.

Recommendations

Allow user to download API Object If prototyping, it's helpful to allow users to see and download the API input object being sent to the SkyCiv API. It makes troubleshooting a bit easier. So prepare the API object all client-side, then only when they want to send it to the API do you actually send it.

Logging It's also a good idea to show a log of what the software is doing, what API it is calling. Makes it easier to find where things have gone wrong.

Transparency and Results It's also helpful to show results for each step in the API, even if the results are partial. For example, if you intend to run S3D.model.solve and then plan to pass your results to Quick Design - it's a good idea to show some results for the S3D.model.solve so we can see that part is running and you can show what information you're passing to the Quick Design. This transparency is very valuable to the engineer.

Return the link to the S3D model. Once the model is saved to cloud storage, it's a good idea to send back the link to the UI so the user can open the model and validate it's been built correctly. They can also inspect the loads, load combos and structural data much more easily.