# `LightningWeb.API.ProvisioningController`
[🔗](https://github.com/OpenFn/lightning/blob/main/lib/lightning_web/controllers/api/provisioning_controller.ex#L1)

API controller for project provisioning and deployment.

Handles creation, updates, and retrieval of project state for idempotent
deployments via the CLI. Supports both JSON and YAML formats.

## Endpoints

- `POST /api/provision` - Create or update a project
- `GET /api/provision/:id` - Get project state as JSON
- `GET /api/provision/:id.yaml` - Get project state as YAML

# `create`

```elixir
@spec create(Plug.Conn.t(), map()) :: Plug.Conn.t()
```

Creates or updates a project based on a JSON payload.

Performs idempotent project provisioning by accepting UUIDs for existing
resources. If a project ID is provided and exists, the project will be
updated; otherwise, a new project is created.

## Parameters

- `conn` - The Plug connection struct with the current resource assigned
- `params` - Map containing project configuration (workflows, jobs, triggers, etc.)

## Returns

- `201 Created` with project JSON on success
- `422 Unprocessable Entity` with changeset errors on validation failure
- `403 Forbidden` if user lacks provisioning permissions

## Examples

    # Create new project
    POST /api/provision
    {
      "name": "My Project",
      "workflows": [...]
    }

    # Update existing project
    POST /api/provision
    {
      "id": "a1b2c3d4-...",
      "name": "Updated Project",
      "workflows": [...]
    }

# `show`

```elixir
@spec show(Plug.Conn.t(), map()) :: Plug.Conn.t()
```

Returns a project state as JSON with UUIDs for idempotent deployments.

Retrieves the complete project configuration including workflows, jobs,
triggers, edges, and credentials. UUIDs are included to enable updates
to existing projects via the CLI.

## Parameters

- `conn` - The Plug connection struct with the current resource assigned
- `params` - Map containing:
  - `id` - Project UUID (required)
  - `snapshots` - Whether to include workflow snapshots (optional)

## Returns

- `200 OK` with project JSON on success
- `404 Not Found` if project doesn't exist
- `403 Forbidden` if user lacks describe permissions

## Examples

    # Get project state
    GET /api/provision/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d

    # Get project state with snapshots
    GET /api/provision/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d?snapshots=true

# `show_yaml`

```elixir
@spec show_yaml(Plug.Conn.t(), map()) :: Plug.Conn.t()
```

Returns a project state as YAML for CLI deployments.

Exports the complete project configuration in YAML format, equivalent to
the "Export to YAML" feature in the UI. Useful for version control and
CLI-based workflows.

## Parameters

- `conn` - The Plug connection struct with the current resource assigned
- `params` - Map containing:
  - `id` - Project UUID (required)
  - `snapshots` - Whether to include workflow snapshots (optional)

## Returns

- `200 OK` with YAML content on success
- `404 Not Found` if project doesn't exist
- `403 Forbidden` if user lacks describe permissions

## Examples

    # Get project state as YAML
    GET /api/provision/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d.yaml

    # Get project state as YAML with snapshots
    GET /api/provision/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d.yaml?snapshots=true

---

*Consult [api-reference.md](api-reference.md) for complete listing*