# Quick Start

This guide walks you through connecting to the API, opening a built-in
sample project, and reading nodes — using the SDK clients or plain
HTTP. No project file of your own is required.

### Prerequisites

- [SPACE GASS](https://www.spacegass.com/) **14.5 or later** installed on your machine
- SPACE GASS has been opened at least once to initialise the required
  data files
- One of:
  - **C#** — [.NET 8 SDK](https://dotnet.microsoft.com/download) (any
    editor works; [Visual Studio Code](https://code.visualstudio.com/)
    + the C# Dev Kit extension is a free option), or
  - **Python** — [Python 3.10 or newer](https://www.python.org/downloads/)
    (any editor works; VS Code + the Python extension is a free option), or
  - **Just an HTTP client** — `curl` is built into Windows 10+;
    [Postman](https://www.postman.com/) and [Insomnia](https://insomnia.rest/)
    also work.

<Stepper>
1. **Start the Service**

   The API runs as a local server. The easiest way to start it is to
   double-click the **SPACE GASS API** shortcut under the SPACE GASS
   Windows application folder.

   Alternatively, open a terminal and run:

   ```bash
   "C:\Program Files\SPACE GASS 14.5\SpaceGassApi.exe"
   ```

   By default the service starts on `http://localhost:34560`. To use a
   different port, pass the `--port` flag:

   ```bash
   "C:\Program Files\SPACE GASS 14.5\SpaceGassApi.exe" --port=5025
   ```

   Leave the terminal or shortcut window open — the service runs until
   you close it.

1. **Explore the API**

   Once the service is running, open your browser and navigate to:

   ```
   http://localhost:34560/swagger
   ```

   The interactive Swagger UI lets you browse every endpoint, see
   request and response schemas, and make live API calls directly
   from your browser — no SDK or code required. This is the quickest
   way to get familiar with the API.

   When you are ready to integrate the API into your own code,
   continue with the steps below.

1. **Create a Project Folder and Install the SDK**

   The API includes generated SDK clients for C# and Python. These
   handle serialisation and give you typed methods for every endpoint.
   If you prefer raw HTTP, you can skip this step and use the **curl**
   tab in every snippet below.

   <CodeTabs>
   ```bash title="C#"
   # In a fresh folder:
   dotnet new console -n SpaceGassQuickStart
   cd SpaceGassQuickStart
   dotnet add package SpaceGassApi
   ```

   ```bash title="Python"
   # In a fresh folder:
   python -m venv .venv
   .venv\Scripts\activate          # macOS/Linux: source .venv/bin/activate
   pip install space-gass-api
   ```

   ```bash title="curl"
   # No installation needed — curl is built into Windows 10+ and most
   # macOS/Linux installations. Postman or Insomnia work too.
   ```
   </CodeTabs>

1. **Create the Client**

   The SDK provides a `CreateClient()` factory that configures
   everything for you — it connects to the local API with no
   additional setup required. See
   [Authentication](/authentication) for details on
   custom URLs and future API key support.

   <CodeTabs>
   ```csharp title="C#"
   using SpaceGassApi;
   using SpaceGassApi.Models;

   var client = SpaceGassApiClient.CreateClient("http://localhost:34560");
   ```

   ```python title="Python"
   from space_gass_api import SpaceGassApiClient
   import space_gass_api.models as models

   client = SpaceGassApiClient.create_client("http://localhost:34560")
   ```

   ```bash title="curl"
   # No client setup needed — just make HTTP requests directly.
   curl http://localhost:34560/api/v1/service/info
   ```
   </CodeTabs>

1. **Open a Sample Project**

   `Job.OpenSample` loads one of the built-in SPACE GASS samples as a
   new unsaved job — perfect for getting going without your own `.sg`
   file. List available samples with `GET /file/samples` (or
   [browse them in Swagger](http://localhost:34560/swagger#/File/get_file_samples));
   here we'll open `Portal Frame.SG`, which ships with every install.

   When you have your own file, use `Job.Open` with `FilePath` instead.
   See [File Handling](/guides/file-handling) for the full set of
   open/save/close patterns.

   <CodeTabs>
   ```csharp title="C#"
   await client.Job.OpenSample.PostAsync(
       new OpenSampleRequest { FileName = "Portal Frame.SG" });
   ```

   ```python title="Python"
   await client.job.open_sample.post(
       models.OpenSampleRequest(file_name="Portal Frame.SG"))
   ```

   ```bash title="curl"
   curl -X POST http://localhost:34560/api/v1/job/open-sample \
     -H "Content-Type: application/json" \
     -d '{"fileName": "Portal Frame.SG"}'
   ```
   </CodeTabs>

1. **Get All Nodes**

   <CodeTabs>
   ```csharp title="C#"
   var nodes = await client.Job.Structure.Nodes.GetAsync();

   foreach (var node in nodes)
   {
       Console.WriteLine($"Node {node.Id}: ({node.X}, {node.Y}, {node.Z})");
   }
   ```

   ```python title="Python"
   nodes = await client.job.structure.nodes.get()

   for node in nodes:
       print(f"Node {node.id}: ({node.x}, {node.y}, {node.z})")
   ```

   ```bash title="curl"
   curl http://localhost:34560/api/v1/job/structure/nodes
   ```
   </CodeTabs>

1. **Close the Project**

   <CodeTabs>
   ```csharp title="C#"
   await client.Job.Close.PostAsync();
   ```

   ```python title="Python"
   await client.job.close.post()
   ```

   ```bash title="curl"
   curl -X POST http://localhost:34560/api/v1/job/close
   ```
   </CodeTabs>
</Stepper>

## Putting It All Together

Drop this complete program into the project you created in Step 3 and
run it. It opens the `Portal Frame.SG` sample, lists every node, and
closes cleanly.

<CodeTabs>
```csharp title="C# (Program.cs)"
using SpaceGassApi;
using SpaceGassApi.Models;

var client = SpaceGassApiClient.CreateClient("http://localhost:34560");

try
{
    await client.Job.OpenSample.PostAsync(
        new OpenSampleRequest { FileName = "Portal Frame.SG" });

    var nodes = await client.Job.Structure.Nodes.GetAsync();
    foreach (var node in nodes!)
    {
        Console.WriteLine($"Node {node.Id}: ({node.X}, {node.Y}, {node.Z})");
    }
}
finally
{
    await client.Job.Close.PostAsync();
}
```

```python title="Python (main.py)"
import asyncio

from space_gass_api import SpaceGassApiClient
import space_gass_api.models as models


async def main():
    client = SpaceGassApiClient.create_client("http://localhost:34560")
    try:
        await client.job.open_sample.post(
            models.OpenSampleRequest(file_name="Portal Frame.SG"))

        nodes = await client.job.structure.nodes.get()
        for node in nodes:
            print(f"Node {node.id}: ({node.x}, {node.y}, {node.z})")
    finally:
        await client.job.close.post()


if __name__ == "__main__":
    asyncio.run(main())
```

```bash title="curl"
# Open the sample, list nodes, close the job. Run from a terminal —
# bash on Linux/macOS or Git Bash / WSL on Windows.
curl -X POST http://localhost:34560/api/v1/job/open-sample \
  -H "Content-Type: application/json" \
  -d '{"fileName": "Portal Frame.SG"}'

curl http://localhost:34560/api/v1/job/structure/nodes

curl -X POST http://localhost:34560/api/v1/job/close
```
</CodeTabs>

## Run this example locally

The same code is in the repo as
[`Example.QuickStart`](https://github.com/SpaceGass/space-gass-api/tree/main/sdks/csharp/examples/Example.QuickStart) (C#) and
[`quick_start`](https://github.com/SpaceGass/space-gass-api/tree/main/sdks/python/examples/quick_start) (Python).
Clone the repo and run it directly — no copy-paste:

<CodeTabs>
```bash title="C#"
git clone https://github.com/SpaceGass/space-gass-api.git
cd space-gass-api/sdks/csharp/examples/Example.QuickStart
dotnet run
```

```bash title="Python"
git clone https://github.com/SpaceGass/space-gass-api.git
cd space-gass-api/sdks/python/examples/quick_start
pip install space-gass-api    # once per environment
python quick_start.py
```
</CodeTabs>

Make sure the SPACE GASS API service is running first (step 1 above).

## Next Steps

- [Simple Beam Model](/examples/simple-beam) — Full walkthrough
  building a model, running analysis, and querying results
- [File Handling](/guides/file-handling) — Open, save, force-open, and
  file status checks
- [API Reference](/api) — Browse all endpoints interactively