Urban Strategy REST API - OpenAPI 3.0

The Urban Strategy REST API is based on the OpenAPI 3.0 specification. The REST API offers alternative access to the Urban Strategy Platform, outside the standard webinterface.

Store

The structure of the functions in the API is in line with the categorization of data within the DT data store.

Download

A .yaml file of the OpenAPI specification can be found here: openapi .yaml version

Access

Access is given trhough the AUTH editor. Besides fine graned access through specific rest groups, full access is given to all projects through group *.

Specific access groups:

rest:/data provides basic read-only access to the project of the user
rest:rw provides write access to the projects of the user
rest:schema provides write access to the schema
rest:bins provides access to the bins/statistics and bins/commit command
rest:mc provides access to the model control commands
<base-bin-in-uppercase>, like US_DEMO_2025, gives access to a specific project

Usage

Select a target server. Aquire a token for access through the Access token method /login. register the token in the Authorize secion. Any following commands should

Version: 0.6.4

Contact information:
support@scenexus.com

Servers

URL
http://localhost:8080/api/v1
https://portal.urbanstrategy.nl/api/v1

Scenexus

Available authorizations

ApiKeyAuth (API Key Authentication)

Name: token
In: query

Access token

Obtain a token to access the API Find out more about tokens

Obtain a token (no special access needed)

Use your Email and Password to get the token

Parameters

Name	Located in	Description	Required	Schema
email	query	Email as UserId	Yes	string
password	query	Password belonging to Email	Yes	password

Responses

Code	Description	Schema
200	Successful acquired token	application/json: string
400	Bad request
401	Invalid Email/Password supplied

Help

Output the REST API end-points

[GET] /data/help

Obtain Help

Displays a small help text - AUTH access groups: * | rest:/data

Responses

Code	Description	Schema
200	Successful operation	text/html: string

Security

Security Schema	Scopes
ApiKeyAuth

Schema

Information from the Schema service

[GET] /data/schema/{Schema}/get

Get schema

Get schema - AUTH access groups: * | rest:/data

Parameters

Name	Located in	Description	Required	Schema
Schema	path	Name of the Schema	Yes	string
format	query	Specify output format json (default), csv or html	No	string, Available values: "json", "csv", "html", Default: json

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[PUT] /data/schema/{Schema}/set

Update schema

Update schema - AUTH access groups: * | (rest:/data & res:mc)

Parameters

Name	Located in	Description	Required	Schema
Schema	path	Name of the Schema	Yes	string

Request Body

A JSON formatted entry to change or add. Set field-type: null to remove field.

Required	Schema
No	application/json: { "request": { "data": string } }

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Bins

Command access to all Bins in the store

[GET] /data/bins

Get all bins in the store

Retrieve a list of the Bins in the Urban Strategy storage. Access is given through membership of AUTH group * or rest:/data in combination with the base bin of the project (for example US_DEMO_2025) - AUTH access groups: * | (rest:/data)

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bins/*/statistics

Get statistics of all bins in the store.

Get statistics of all the Bins in the Urban Strategy storage - AUTH access groups: * | (rest:/data & res:bins)

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bins/*/commit

Commit data for every bin

Commit data for every bin - AUTH access groups: * | (rest:/data & res:bins)

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Bin

Data access to a specific Bin in the store

[GET] /data/bin/{Bin}/get

Get collections of a single bin

Get collections of a single Bin - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bin/{SrcBin}/copy/{DstBin}

Copy Bin to a new Bin

Copy Bin to a new Bin - AUTH access groups: * | (rest:/data & rest:rw & & )

Parameters

Name	Located in	Description	Required	Schema
SrcBin	path	Name of the Source Bin	Yes	string
DstBin	path	Name of the (new) Destination Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bin/{SrcBin}/rename/{DstBin}

Rename Bin

Rename Bin - AUTH access groups: * | (rest:/data & rest:rw & & )

Parameters

Name	Located in	Description	Required	Schema
SrcBin	path	Name of the Bin to be renamed	Yes	string
DstBin	path	New name of the Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bin/{Bin}/remove

Remove/Delete a single bin

Remove/Delete a single Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bin/{Bin}/statistics

Get statistics of a single bin in the store

Get statistics of a single Bin in the Urban Strategy storage - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/bin/{Bin}/unload

Unload a bin from the store. (Only used by uploader tools)

Unload a bin from the store. (Only used by uploader tools) - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Scenario

Create, edit and remove scenarios

[PUT] /data/scenario/{Bin}/copy

Copy scenario

Copy a scenario bin and add a metascenario entry - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin used as source for the new scenario	Yes	string
dstscenarioid	query		No	integer
year	query		No	integer
name	query		No	string
info	query		No	string
notes	query		No	string
type	query		No	string
scenario_status	query		No	string
questions	query		No	string
run_number	query		No	string
time_period	query		No	string
feeds_into	query		No	string
attribution	query		No	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[PUT] /data/scenario/{Bin}/edit

Edit scenario

Edit a scenario metascenario entry - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin to identify the scenario to edit	Yes	string
year	query		No	integer
info	query		No	string
notes	query		No	string
type	query		No	string
scenario_status	query		No	string
questions	query		No	string
run_number	query		No	string
time_period	query		No	string
feeds_into	query		No	string
attribution	query		No	string
published	query		No	integer
base_id	query		No	integer

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/scenario/{Bin}/remove

Remove scenario

Remove a scenario bin and metascenario entry - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin to identify the scenario to remove	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Collections

Data access to Collections from Bins in the store

[GET] /data/collection/{Bin}/get/{Collection}

Get collection data

Get collection data - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string
filter	query	Specify SQL like field filter. filter options: https://docs.microsoft.com/en-us/dotnet/api/system.data.datacolumn.expression?view=netcore-3.1	No	string
format	query	Optional specify the output format (json default)	No	string, Available values: "json", "csv", "geo", Default: json
separator	query	Optional specify the separator (tab default)	No	string, Available values: "tab", "semicolon", "comma", Default: tab
geometry	query	1=generic json array(default), 2=wkt Polygon, 3=wkt Multi polygon, 4=wkt Line, 5=wkt Point, 6=JSON array, 7=override, always use point	No	integer
id	query	id10=derive id10 field (decimal representation of first 3 fields of guid) from id, od=derive origin/destination from id	No	string, Available values: "id10", "od"
fields	query	list of case sensitive fields separated by commas to return by request	No	[ string ]
download	query	trigger a browser to download the data instead of showing it directly	No	integer, Available values: 0, 1
expressions	query	{:[,:]}	No	string
aggregation	query	{:[,:]} See https://docs.microsoft.com/en-us/dotnet/api/system.data.datacolumn.expression?view=netcore-3.1	No	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[PUT] /data/collection/{Bin}/set/{Collection}

Update or Add Collection data

Update or Add Collection data - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Request Body

A JSON formatted entry to change or add. When no id field is given in the data object a random one is generated. GUID format of id normally is build like {--<0>-<0000000000000001>}. GUID format of id for od matrix entries is build like {---<0000000000000001>}

Required	Schema
No	application/json: { "request": { "data": { "field": string } } }

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{SrcBin}/copy/{SrcCollection}

Copy collection Bin to a new Bin

Copy the specified collection from the SrcBin to an other Bin and or other collection name - AUTH access groups: * | (rest:/data & rest:rw & & )

Parameters

Name	Located in	Description	Required	Schema
SrcBin	path	Name of the Source Bin	Yes	string
SrcCollection	path	Name of the Source Collection	Yes	string
newbinname	query	Name of the (new) Destination Bin	Yes	string
newcollectionname	query	Name of the (new) Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/remove/{Collection}

Remove collection from bin

Remove Collection from Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/truncate/{Collection}

Truncate collection from bin

Truncate Collection from Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/truncatets/{Collection}

Truncate collection from bin

Truncate Collection from Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string
timestampgroup	query	Specify the timestampgroup for truncation	No	integer

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/timestamps/{Collection}

List available timestamps for this collection

List available timestamps for this collection - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/unload/{Collection}

Unload a collection from the store. (Only used by uploader tools)

Unload a collection from the store. (Only used by uploader tools) - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/collection/{Bin}/fingerprint/{Collection}

Calculate fingerprint of a collection.

Calculate fingerprint of a collection. - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Collection	path	Name of the Collection	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Key/value sets

Set of key-value pairs. Mainly used for model parameters

[GET] /data/keyvalueset/{Bin}/get/{KeyValueSet}

Get a key-value set from a Bin

Get a key-value set from a Bin - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
KeyValueSet	path	Name of the KeyValue Set	Yes	string
values	query	Specify the output format.	No	string, Available values: "json"

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[PUT] /data/keyvalueset/{Bin}/set/{KeyValueSet}

Update or Add a key-value set to the Bin

Update or Add a key-value set to the Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
KeyValueSet	path	Name of the KeyValue Set	Yes	string

Request Body

A JSON formatted entry to change or add.

Required	Schema
No	application/json: { "request": { "data": { "key": string } } }

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/keyvalueset/{Bin}/remove/{KeyValueSet}

Remove a key-value set from a Bin

Remove a key-value set from a Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
KeyValueSet	path	Name of the KeyValue Set	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/keyvalueset/{Bin}/truncate/{KeyValueSet}

Truncate a key-value set from a Bin

Truncate a key-value set from a Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
KeyValueSet	path	Name of the KeyValue Set	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/keyvalueset/{Bin}/fingerprint/{KeyValueSet}

Calculate the fingerprint of a key-value set from a Bin

Calculate the fingerprint of a key-value set from a Bin - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
KeyValueSet	path	Name of the KeyValue Set	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Matrices

Data access for Matrices

[GET] /data/matrix/{Bin}/get/{Matrix}

Get matrix data

Get Matrix data - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string
fields	query	list of case sensitive fields separated by commas to return by request	No	[ string ]
format	query	Optional specify the output format (json default)	No	string, Available values: "json", "csv"
separator	query	Optional specify the separator (tab default)	No	string, Available values: "tab", "semicolon", "comma"
download	query	trigger a browser to download the data instead of showing it directly	No	integer, Available values: 0, 1

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/update/{Matrix}

Update matrix

Update Matrix - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/set/{Matrix}

Set matrix

Set Matrix - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/remove/{Matrix}

Remove matrix

Remove Matrix - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/truncate/{Matrix}

Truncate matrix

Truncate Matrix - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/unload/{Matrix}

Unload a matrix from the store. (Only used by uploader tools)

Unload a Matrix from the store. (Only used by uploader tools) - AUTH access groups: * | (rest:/data & rest:rw & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/matrix/{Bin}/fingerprint/{Matrix}

Calculate the fingerprint of a matrix

Calculate the fingerprint of a Matrix - AUTH access groups: * | (rest:/data & )

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
Matrix	path	Name of the Matrix	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Models

Control the models

[GET] /data/models

Retrieve a list of the available models

Retrieve a list of the available models - AUTH access groups: * | rest:/data

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/models/{Bin}/start/{SetupName}

Start a model

Start a model - AUTH access groups: * | (rest:/data & rest:rw & & rest:mc)

Parameters

Name	Located in	Description	Required	Schema
Bin	path	Name of the Bin	Yes	string
SetupName	path	Setup Name of the Model	Yes	string
version	query	optional setup version number	No	string
node	query	optional node name of the setup	No	string
stopAt	query	optional excel date/time when at latest stop model	No	number
state	query	optional initial model state	No	integer
desiredState	query	optional desired model state	No	integer
stateGroup	query	optional state manager group	No	integer
stateRequested	query	optional state manager requested state	No	integer
waitForSetupSeconds	query	optional time to wait before setup becomes available	No	integer
maxIdleTime	query	optional maximum allowed idle time (fraction of day)	No	number

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/models/{InstanceId}/stop

Stop a model

Stop a model - AUTH access groups: * | (rest:/data & rest:rw & & rest:mc)

Parameters

Name	Located in	Description	Required	Schema
InstanceId	path	The Instance Id	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[GET] /data/models/{InstanceId}/stop/force

Force a model to stop

Force a model to stop - AUTH access groups: * | (rest:/data & rest:rw & & rest:mc)

Parameters

Name	Located in	Description	Required	Schema
InstanceId	path	The Instance Id	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

[PUT] /data/models/*/state

Request model state. Will return when the model goes through a change to the

Request model state. Will return when the model goes through a change to the - AUTH access groups: * | (rest:/data & rest:mc)

Request Body

A JSON formatted entry.

Required	Schema
No	application/json: { "request": { "instances": [ string ], "targetstate": integer, "timeoutsec": integer } }

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Log

Fetch the log of a calculation model

[GET] /data/instances/{InstanceId}/log

Fetch a log remotely

Fetch a log remotely - AUTH access groups: * | (rest:/data & & rest:mc)

Parameters

Name	Located in	Description	Required	Schema
InstanceId	path	The Instance Id	Yes	string

Responses

Code	Description
200	Successful operation

Security

Security Schema	Scopes
ApiKeyAuth

Urban Strategy REST API - OpenAPI 3.0

Version: 0.6.4

Servers

Available authorizations

ApiKeyAuth (API Key Authentication)

Access token

[GET] /login

Parameters

Responses

Help

[GET] /data/help

Responses

Security

Schema

[GET] /data/schema/{Schema}/get

Parameters

Responses

Security

[PUT] /data/schema/{Schema}/set

Parameters

Request Body

Responses

Security

Bins

[GET] /data/bins

Responses

Security

[GET] /data/bins/*/statistics

Responses

Security

[GET] /data/bins/*/commit

Responses

Security

Bin

[GET] /data/bin/{Bin}/get

Parameters

Responses

Security

[GET] /data/bin/{SrcBin}/copy/{DstBin}

Parameters

Responses

Security

[GET] /data/bin/{SrcBin}/rename/{DstBin}

Parameters

Responses

Security

[GET] /data/bin/{Bin}/remove

Parameters

Responses

Security

[GET] /data/bin/{Bin}/statistics

Parameters

Responses

Security

[GET] /data/bin/{Bin}/unload

Parameters

Responses

Security

Scenario

[PUT] /data/scenario/{Bin}/copy

Parameters

Responses

Security

[PUT] /data/scenario/{Bin}/edit

Parameters

Responses

Security

[GET] /data/scenario/{Bin}/remove

Parameters

Responses

Security

Collections

[GET] /data/collection/{Bin}/get/{Collection}

Parameters

Responses

Security

[PUT] /data/collection/{Bin}/set/{Collection}

Parameters

Request Body

Responses