API Client CLI

On this page:


Why use the API client?

The oasislmf model run command runs an analysis entirely in-process. The Oasis Platform, by contrast, serialises intermediate data to files between stages — for example, writing generated input files to shared storage before the losses stage reads them back.

This difference means a model can pass oasislmf model run but fail on the platform when a serialisation or file-format issue is exposed. The oasislmf api subcommand runs an analysis through a live Platform instance using its real worker containers, so it is a faithful test of how the model will behave in a deployed environment.

Using the API client is the recommended way for model developers to validate a model against a worker container before distributing it to users.


Prerequisites

  • A running Oasis Platform instance accessible over HTTP. The OasisEvaluation repository provides a Docker Compose configuration that brings up the full stack locally.

  • The oasislmf package installed (pip install oasislmf).

  • OED exposure files and an analysis_settings.json for the model you want to test.

When using the OasisEvaluation compose file the server is available at http://localhost:8000 with the default credentials admin / password. The oasislmf api commands will try these defaults automatically, so no extra auth configuration is needed for a local evaluation deployment.


Authentication

Three authentication modes are supported, selected via --auth-type.

Mode

--auth-type

Credentials required

Simple JWT

simple

username and password

OIDC via platform

oidc

client_id and client_secret (token exchange handled by the platform)

M2M direct to IdP

m2m

client_id, client_secret, and --oidc-token-url; optionally --oidc-scope

Credentials can be supplied in three ways:

1. Credentials JSON file (recommended for scripting)

Create a JSON file and pass it with --server-login-json.

For simple auth:

{
    "username": "admin",
    "password": "password"
}

For oidc or m2m auth:

{
    "client_id": "my-client",
    "client_secret": "my-secret"
}

For m2m with a token URL baked in:

{
    "client_id": "my-client",
    "client_secret": "my-secret",
    "token_url": "https://idp.example.com/oauth2/token",
    "scope": "oasis/m2m"
}

2. MDK config file (-C oasislmf.json)

Any api option can be stored in the MDK config file so you do not have to repeat it on every command:

{
    "server_url": "http://localhost:8000",
    "server_version": "v2",
    "server_login_json": "./credentials.json"
}

3. Interactive prompt

If no credentials file is provided and the default local credentials fail, the CLI prompts for the auth type and then the required fields.


Commands

All api subcommands share a common set of connection options:

Option

Description

--server-url URL

Base URL of the platform (default: http://localhost:8000)

--server-version {v1,v2}

v1 = single-server run mode; v2 = distributed/chunked run mode (default: v2)

--server-login-json FILE

Path to a JSON file containing credentials (see Authentication)

--auth-type {simple,oidc,m2m}

Force a specific authentication mode

-C FILE

MDK config JSON file; all options can be stored here

api run

Runs the model end-to-end: uploads exposure files, triggers input generation, triggers losses generation, and downloads results.

oasislmf api run \
    --server-url http://localhost:8000 \
    --server-version v1 \
    -x location.csv \
    -y accounts.csv \
    -a analysis_settings.json \
    -o ./results/

Key options:

Option

Description

-x / --oed-location-csv

OED location file

-y / --oed-accounts-csv

OED accounts file (optional)

-i / --oed-info-csv

Reinsurance info file (optional)

-s / --oed-scope-csv

Reinsurance scope file (optional)

-a / --analysis-settings-json

Analysis settings JSON

-o / --output-dir

Directory to write results to

--model-id ID

Use an existing model (skips model upload)

--portfolio-id ID

Use an existing portfolio (skips exposure upload)

--analysis-id ID

Re-use an existing analysis object

--analysis-chunks N

Number of loss-generation chunks for v2 runs

--lookup-chunks N

Number of input-generation chunks for v2 runs

api generate-oasis-files

Runs only the input-generation stage (keys lookup + Oasis file preparation) on the platform. Useful for isolating lookup or exposure-pre-analysis issues.

oasislmf api generate-oasis-files \
    --server-url http://localhost:8000 \
    --model-id 1 \
    -x location.csv \
    -a analysis_settings.json

api generate-losses

Runs only the losses-generation stage for an analysis whose inputs have already been generated. Requires an existing --analysis-id.

oasislmf api generate-losses \
    --server-url http://localhost:8000 \
    --analysis-id 42 \
    -o ./results/

api list

Lists models, portfolios, and/or analyses on the server. Pass one or more IDs to print full detail for those objects; omit IDs to list all.

# List everything
oasislmf api list --server-url http://localhost:8000

# Show detail for specific objects
oasislmf api list --server-url http://localhost:8000 \
    --models 1 2 \
    --analyses 10 11

api get

Downloads files associated with a model, portfolio, or analysis. Useful for retrieving intermediate files (generated inputs, lookup logs) after a run.

# Download outputs for analysis 42
oasislmf api get --server-url http://localhost:8000 \
    --analyses-output-file 42 \
    -o ./results/

# Download the traceback log after a failed run
oasislmf api get --server-url http://localhost:8000 \
    --analyses-run-traceback-file 42 \
    -o ./logs/

Available file types: --analyses-output-file, --analyses-input-file, --analyses-run-traceback-file, --analyses-run-log-file, --analyses-input-generation-traceback-file, --analyses-lookup-errors-file, --analyses-lookup-success-file, --analyses-lookup-validation-file, --analyses-settings-file, --analyses-summary-levels-file, --model-settings, --model-versions, --portfolio-location-file, --portfolio-accounts-file, --portfolio-reinsurance-info-file, --portfolio-reinsurance-scope-file.


api delete

Deletes models, portfolios, and/or analyses from the server.

oasislmf api delete --server-url http://localhost:8000 \
    --analyses 42 43 \
    --portfolios 5

Typical workflow

The following walkthrough shows how a model developer would test a new model against a local Platform instance.

Step 1 — start the platform

git clone https://github.com/OasisLMF/OasisEvaluation
cd OasisEvaluation
docker compose -f oasis-platform.yml up -d

Wait for the server to be ready (http://localhost:8000/healthcheck/ returns 200).

Step 2 — run the model end-to-end

oasislmf api run \
    --server-url http://localhost:8000 \
    --server-version v1 \
    -x /path/to/location.csv \
    -y /path/to/accounts.csv \
    -a /path/to/analysis_settings.json \
    -o ./output/

The command creates a portfolio, uploads the exposure, creates an analysis, triggers input generation and then losses generation, and finally downloads the results to ./output/.

Step 3 — inspect the results

ls ./output/

Step 4 — diagnose a failure

If the run fails, retrieve the traceback:

# First find the analysis ID
oasislmf api list --server-url http://localhost:8000 --analyses

# Then download the log
oasislmf api get --server-url http://localhost:8000 \
    --analyses-run-traceback-file <analysis-id> \
    -o ./logs/

Step 5 — clean up

oasislmf api delete --server-url http://localhost:8000 \
    --analyses <analysis-id> \
    --portfolios <portfolio-id>

Using a config file

For repeated runs it is more convenient to store connection and file path settings in an oasislmf.json config file and pass it with -C:

{
    "server_url": "http://localhost:8000",
    "server_version": "v1",
    "server_login_json": "./credentials.json",
    "oed_location_csv": "location.csv",
    "oed_accounts_csv": "accounts.csv",
    "analysis_settings_json": "analysis_settings.json",
    "output_dir": "./results/"
}

oasislmf api run -C oasislmf.json

Any command-line flag overrides the corresponding key in the config file.


See also