Quickstart

This quickstart uses the current DalyAPI auth flow:

Exchange workspace + user API keys for a JWT.
Use the JWT in Authorization: Bearer ... for protected routes.
Run an energy model sync (default) or async (?async=true) and track status.

1. Set Your API Base URL

Use your deployed API host. In local development, the default is:

export DALY_API_BASE_URL="http://localhost:8000"

2. Exchange API Keys for a JWT

Call POST /auth/token with your workspace and user API keys.

curl -sS -X POST "$DALY_API_BASE_URL/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_API_KEY",
    "user_id": "USER_API_KEY"
  }'

Example response:

{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 86400
}

3. Call Protected Endpoints

export DALY_TOKEN="<jwt-from-auth-token>"

curl -sS "$DALY_API_BASE_URL/projects" \
  -H "Authorization: Bearer $DALY_TOKEN"

4. Run an Energy Model (Sync Default)

By default, POST /energymodels runs synchronously. Use ?async=true when you want queued background execution. Current output-shaping controls live in the request body under output:

output.timeSeries=true adds plant-level timeSeries data to sync completed responses.
output.blockResults=true adds block-level blockTimeSeries data.
output.blockIndex filters the returned blockTimeSeries map to one zero-based block but does not reduce execution scope.
output.lossBreakdownTimestamps=true implies block-level results and nests timestamped loss detail under blockTimeSeries[<blockIndex>].lossBreakdown.
output.fullTimeSeries=true cannot be combined with output.blockResults=true.

Example async call:

curl -sS -X POST "$DALY_API_BASE_URL/energymodels?async=true" \
  -H "Authorization: Bearer $DALY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": 1,
    "blocks": [
      {
        "inverterId": 1,
        "moduleId": 1,
        "array": {"stringCount": 10, "stringLength": 28},
        "layout": {"arrayType": "fixed", "gcr": 0.4, "azimuth": 180, "axisTilt": 0, "tilt": 25},
        "shading": {"farShading": false, "nearShading": "unlimited", "electricalImpact": false},
        "losses": {
          "moduleQuality": 0.0,
          "mismatch": 0.02,
          "dcohmic": 0.01,
          "lid": 0.01,
          "stringVoltageMismatch": 0.01,
          "invAuxLoss": true,
          "uC": 25,
          "uV": 1.2
        },
        "acSystem": {
          "numberOfInverters": 1,
          "losses": {"acohmicLoss": 0.01, "transformer": {"ironLoss": 0.005, "copperLoss": 0.005}}
        },
        "albedo": {"jan": 0.2, "feb": 0.2, "mar": 0.2, "apr": 0.2, "may": 0.2, "jun": 0.2, "jul": 0.2, "aug": 0.2, "sep": 0.2, "oct": 0.2, "nov": 0.2, "dec": 0.2}
      }
    ]
  }'

Example response:

{
  "result": "success",
  "message": "Energy model queued for processing",
  "energyModelId": 56,
  "revision": "v0003",
  "taskDetails": {
    "message": "Energy model queued for processing",
    "taskId": 1234,
    "schemaMode": "legacy",
    "executionMode": "async_fanout",
    "calculationTime": null,
    "createdAtUtc": "2026-03-03T16:22:03Z",
    "warnings": [],
    "normalizationWarnings": []
  }
}

If you need immediate sync time-series output, set the output flags explicitly on the request body and inspect timeSeries and blockTimeSeries in the completed response. blockTimeSeries keys preserve the original zero-based block numbering, including filtered single-block responses. Each returned block result already represents the full configured numberOfInverters count for that block type, not a single inverter.

5. Poll Task Status

curl -sS "$DALY_API_BASE_URL/tasks/1234" \
  -H "Authorization: Bearer $DALY_TOKEN"

When complete, fetch results:

curl -sS "$DALY_API_BASE_URL/energymodels/56" \
  -H "Authorization: Bearer $DALY_TOKEN"

Task lifecycle is pending -> queued -> running -> completed|failed|cancelled.

6. Edit and Rerun a Saved Model In Place

Imported project variants from POST /projects/import and previously created energy models both use the same saved-row workflow:

GET /energymodels/{id}?include=inputs
edit the returned saved input JSON
PUT /energymodels/{id}
POST /energymodels/{id}/run

Example:

curl -sS "$DALY_API_BASE_URL/energymodels/56?include=inputs" \
  -H "Authorization: Bearer $DALY_TOKEN"

curl -sS -X PUT "$DALY_API_BASE_URL/energymodels/56" \
  -H "Authorization: Bearer $DALY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @edited-energy-model-input.json

curl -sS -X POST "$DALY_API_BASE_URL/energymodels/56/run?async=true" \
  -H "Authorization: Bearer $DALY_TOKEN"

The rerun stays on energy model 56; it does not create a second row.

7. Response Contracts

For full sync-complete vs queued 200 envelopes, taskDetails fields, and include-token behavior, see:

Energy Model Response Contracts

Where to Learn Input Contracts

Prefer Python Integration?

See the SDK Overview for a resource-oriented client flow with built-in token handling.

​Quickstart

​1. Set Your API Base URL

​2. Exchange API Keys for a JWT

​3. Call Protected Endpoints

​4. Run an Energy Model (Sync Default)

​5. Poll Task Status

​6. Edit and Rerun a Saved Model In Place

​7. Response Contracts

​Where to Learn Input Contracts

​Prefer Python Integration?

Quickstart

1. Set Your API Base URL

2. Exchange API Keys for a JWT

3. Call Protected Endpoints

4. Run an Energy Model (Sync Default)

5. Poll Task Status

6. Edit and Rerun a Saved Model In Place

7. Response Contracts

Where to Learn Input Contracts

Prefer Python Integration?