> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dalyenergy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Endpoint architecture, auth model, and integration conventions for DalyAPI

# API Reference

DalyAPI is a FastAPI service for workspace-scoped solar + storage workflows.

## Base URL

Choose the production base for the workflow:

| Base URL | Workflow |
| - | - |
| `https://api.dalyenergy.com` | Retained standard solar runs and existing integrations |
| `https://api.dalyenergy.com/v2` | Maintained plant design, layout, native solar preparation and hybrid studies |

Native v2 simulations require `calculationEngine=hybrid` and a `hybrid-1` or
`plant-1` request. The selector alone does not convert a standard solar input;
use [solar preparation](https://docs.dalyenergy.com/energy-models/solar-template-preparation.md) when starting
from a solar template. Keep authentication, resource access, task polling,
results and reruns on the base appropriate to that workflow.

OpenAPI artifacts:

* Original FastAPI docs and OpenAPI JSON: `https://api.dalyenergy.com/docs`
  and `https://api.dalyenergy.com/openapi.json`.
* V2 FastAPI docs and OpenAPI JSON: `https://api.dalyenergy.com/v2/docs`
  and `https://api.dalyenergy.com/v2/openapi.json`.
* Mintlify retains the original origin as its shared `Try it` default.
  Maintained plant, layout and chat operations select `/v2`; shared model and
  task operations offer both. Check the operation's server selection and keep
  it consistent with the run's contract.

Local development default:

```text theme={null}
http://localhost:8000
```

## Authentication Model

Most endpoints require a Bearer token:

```text theme={null}
Authorization: Bearer <jwt>
```

Tokens are issued by:

* `POST /auth/token` (workspace API key + user API key exchange)
* `POST /auth/exchange-supabase` (Supabase token exchange)

See [Authentication](https://docs.dalyenergy.com/api-reference/authentication.md).

## Scope and Authorization

* Every authenticated request is scoped to `workspace_id` in JWT claims.
* RLS context is set server-side per request.
* Write/admin endpoints enforce workspace/organization role checks.

## ID Conventions

* Workspace-scoped IDs: resource IDs in route paths (for example `projectId`, `locationId`)
* Global IDs: Snowflake-style IDs returned in resource payloads (`globalProjectId`, etc.)
* Internal DB IDs are not returned

## Response Conventions

* Route responses are JSON.
* Resource responses use camelCase field names.
* Validation errors return HTTP `422`.
* Missing resources return HTTP `404`.
* Auth errors return `401`/`403`.

## Explore by Topic

* [Endpoint Catalog](https://docs.dalyenergy.com/api-reference/resources.md)
* [Object Models](https://docs.dalyenergy.com/api-reference/object-models.md)
* [Modeling Object Inputs](https://docs.dalyenergy.com/api-reference/modeling-object-inputs.md)
* [Async Tasks and Workflows](https://docs.dalyenergy.com/api-reference/async-workflows.md)
* [Energy Model Run Contract](https://docs.dalyenergy.com/api-reference/energy-model-runs.md)
* [Python SDK Overview](https://docs.dalyenergy.com/sdk/overview.md)

## Interactive Pages

Use the curated endpoint pages in this section when you want a stable path-specific view plus Mintlify `Try it` support.

* Auth: token exchange, workspace discovery, Supabase exchange
* Workspace and organization: settings reads/patches, invite creation/acceptance
* Modeling: shading-scene create/import, energy-model run/detail
* Async: task polling and workflow inspection


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.