Skip to content
TotalView API

Quickstart

This walks through a full round trip against the TotalView API. Base URL:

  • Production — https://api.totalview.energy
  • Development — https://devapi.totalview.energy

All paths are prefixed with /api/v1 and use no trailing slash.

  1. Get a token

    Terminal window
    curl -X POST https://api.totalview.energy/api/v1/auth/login/access-token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d "username=$EMAIL&password=$PASSWORD"
    { "access_token": "eyJhbGc…", "token_type": "bearer" }

    Send it as Authorization: Bearer <token> on every subsequent call. For automation, mint a long-lived key instead — see Authentication & API Keys.

  2. Create a project

    Terminal window
    curl -X POST https://api.totalview.energy/api/v1/projects \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
      -d '{
        "project_name": "West Texas Solar",
        "latitude": 32.5, "longitude": -97.3,
        "nameplate_capacity": 100,
        "tech_type_id": "solar_ground",
        "sam_profile_flag": true,
        "eia_ba_code": "ERCO",
        "project_nerc_code": "US-TRE"
      }'

    Returns { "project_id": "…", "config": { … } }. Admin tokens must also include customer_id. Full field list and tech types in the create-project reference.

  3. Queue a model run

    Terminal window
    curl -X POST https://api.totalview.energy/api/v1/projects/$PROJECT_ID/queue \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

    Returns { "model_run_id": "…" }. The run executes asynchronously.

  4. Poll for completion

    Terminal window
    curl https://api.totalview.energy/api/v1/projects/$PROJECT_ID/runs/latest \
      -H "Authorization: Bearer $TOKEN"

    202 means still running — poll until 200 with a summary_json.

  5. Read the results

    Terminal window
    curl https://api.totalview.energy/api/v1/projects/$PROJECT_ID/results \
      -H "Authorization: Bearer $TOKEN"

    The Impacts.Cradle_to_Grave_Analysis.Total block holds the headline DALYs / PDFs / USD. See LCIA Results to interpret them.

Where to next

Section titled “Where to next”