Introduction

Info

This guide assumes that you:

• understand what an API is and know how you can make REST API calls
• have a valid Nexus Web API token
• have the Scenario Analyst role assigned to your account

Not the case? Check the API Basics first before continuing here.

Root and authentication

Nexus Web API can be reached at https://nexus.stellaspark.com/api/v1/.

The Nexus Web API token must be provided as URL query parameter:

curl "https://nexus.stellaspark.com/api/v1/{api_service}/?token={web_api_token}"

Step 1: List available analyses

To see which analyses are available in your world, call the analyses endpoint with a world query parameter:

curl "https://nexus.stellaspark.com/api/v1/analyses/?world={world_alias}&token={web_api_token}"

This returns a list of analyses, for example:

[
    {
        "id": 3,
        "alias": "precipitation_analysis",
        "name": "Precipitation analysis",
        "description": "Simulate yearly precipitation patterns for a given period.",
        "image": null,
        "calculation_name": "Demo interpolation",
        "calculation_icon": null,
        "calculation_organization": "StellaSpark"
    }
]

Field	Meaning
id	Unique ID of the analysis (used in subsequent calls)
alias	Machine-readable alias
name	Display name of the analysis (localized)
description	Description of the analysis (localized)
image	Optional image URL
calculation_name	Name of the underlying calculation
calculation_icon	Optional icon for the calculation
calculation_organization	Organization that owns the calculation

To retrieve details for a single analysis, including its input form definition:

curl "https://nexus.stellaspark.com/api/v1/analyses/{id}/?world={world_alias}&token={web_api_token}"

The detail response includes a rendered_input_form field containing the JSON Schema that describes which input fields the analysis expects.

Step 2: Start a scenario simulation

To start a simulation, send a POST request to the scenario action of a specific analysis. The request body must include a name for your scenario, plus any additional fields required by the analysis input form:

curl -X POST "https://nexus.stellaspark.com/api/v1/analyses/{id}/scenario/?token={web_api_token}" \
     -H "Content-Type: application/json" \
     -d '{"name": "My scenario", "start_date": "2026-01-01", "end_date": "2026-03-01"}'

Note

The fields beyond name depend on the analysis. Use the rendered_input_form from step 1 to find out which fields are expected.

A successful request returns status '201 Created' with the sync task ID:

{"id": 42}

Step 3: List your scenarios

To see all your scenario tasks, filter the sync tasks endpoint by task_type=scenario:

curl "https://nexus.stellaspark.com/api/v1/sync_tasks/?task_type=scenario&token={web_api_token}"

Response:

[
    {
        "id": 42,
        "name": "My scenario",
        "owner": "My organization",
        "task_type": "scenario",
        "private": true,
        "uploadable": false,
        "trigger": "On demand",
        "harvest_last_success": "2026-03-10T14:30:00Z",
        "data_source": null,
        "calculation": {
            "id": 3,
            "name": "Demo interpolation",
            "owner": "StellaSpark",
            "description": "Spatially interpolate the cumulative rainfall sum for the current year for all weather stations in a world."
        },
        "scenario": {
            "analysis": {
                "id": 3,
                "name": "Precipitation analysis",
                "description": "Simulate yearly precipitation patterns for a given period."
            },
            "user_name": "John Doe"
        },
        "dataconnections": [
            {
                "dc_id": 101,
                "name": null,
                "feature_type": "raster",
                "join_to": null,
                "output_props": [],
                "output_params": [
                    "parameter:prec_cum_ytd_mm"
                ]
            }
        ]
    }
]

See Sync tasks for a full description of all fields.

Step 4: Access scenario results

Each scenario sync task contains a dataconnections list. Use the dc_id values from these data connections to retrieve the scenario output data.

Via the Nexus Web API

Use the dc_id and feature_type from the scenario's data connections to query results through the standard data consumption services. In this example the feature_type is raster, so we use the WCS API to download the raster data as a GeoTIFF.

To download the entire scenario raster, use the dc_id from the data connection as a subset:

curl -o scenario_result.tif "https://nexus.stellaspark.com/api/v1/wcs/?request=getcoverage&format=geotiff&coverageid={world_alias}:rasterbase&subset=dc_id(101)&subset=parameter(\"prec_cum_ytd_mm\")&token={web_api_token}"

If the scenario produced raster output for multiple timesteps, use the time subset to select a specific moment:

curl -o scenario_result_march.tif "https://nexus.stellaspark.com/api/v1/wcs/?request=getcoverage&format=geotiff&coverageid={world_alias}:rasterbase&subset=dc_id(101)&subset=parameter(\"prec_cum_ytd_mm\")&subset=time(\"2026-03-01T00:00:00.000Z\")&token={web_api_token}"

Use the X and Y subsets to clip the raster to a bounding box:

curl -o scenario_result_clip.tif "https://nexus.stellaspark.com/api/v1/wcs/?request=getcoverage&format=geotiff&coverageid={world_alias}:rasterbase&subset=dc_id(101)&subset=parameter(\"prec_cum_ytd_mm\")&subset=time(\"2026-03-01T00:00:00.000Z\")&subset=X(100000,150000)&subset=Y(440000,470000)&token={web_api_token}"

See the WCS service page for all available parameters and slicing options.

Via the Expert API

You can also query scenario results directly in the database using the Expert API reading data. The dc_id maps to data in the world's schema.