# Provisioning API

The Lenses Provisioning System allows you to manage Lenses connections declaratively through YAML manifests. It provides a GitOps-friendly approach to managing your Lenses infrastructure, enabling version control, automated deployments, and consistent configuration across environments.

## Key Features

* **Declarative Configuration**: Define your entire Lenses infrastructure in YAML
* **File Management**: Upload and manage SSL certificates, keystores, and other binary files
* **Validation**: Comprehensive validation with detailed error messages
* **Selective Updates**: Update only specific connections without affecting others
* **File Preservation**: Existing files are preserved when not explicitly replaced
* **Connectivity Testing**: Optional connectivity validation for all connections

## API Endpoints

<a href="https://docs.lenses.io/latest/api-reference/reference/provisioning-state#get-api-v1-environments-environment-proxy-api-v1-state-connections" class="button primary" data-icon="rectangle-api">View full API Spec</a>

### File Upload

Files are uploaded as part of the multipart form data:

```bash
curl -X POST "https://lenses-server/api/v1/state/connections/upload" \
  -H "Authorization: Bearer your-token" \
  -F "provisioning=@provisioning.yaml" \
  -F "keystore.jks=@keystore.jks" \
  -F "truststore.jks=@truststore.jks"
```

#### File Preservation

When updating connections, existing files are preserved if not explicitly provided in the new request. This allows for selective updates without losing existing SSL certificates or other files.

{% hint style="warning" %}
file names must match the file names in the actual provisioning file
{% endhint %}

### Upload Provisioning Manifest

**Endpoint**: `POST /api/v1/state/connections/upload`

**Description**: Uploads a complete provisioning manifest with files. This replaces the entire connection state.

**Request**: `multipart/form-data`

* `provisioning`: YAML manifest file
* Additional files: SSL certificates, keystores, etc.

**Response**: `ProvisioningValidationResponse`

```http
POST /api/v1/state/connections/upload
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="provisioning"; filename="provisioning.yaml"
Content-Type: text/plain

kafka:
  - name: my-kafka
    version: 1
    tags: ["production"]
    configuration:
      kafkaBootstrapServers:
        value: ["localhost:9092"]
      protocol:
        value: "PLAINTEXT"

--boundary
Content-Disposition: form-data; name="keystore.jks"; filename="keystore.jks"
Content-Type: application/octet-stream

[binary keystore content]
--boundary--
```

### Validate Provisioning Manifest

**Endpoint**: `POST /api/v1/state/connections/validate/upload`

**Description**: Validates a provisioning manifest without applying changes (dry-run).

**Request**: Same as upload endpoint **Response**: `ProvisioningValidationResponse`

### Get Current Provisioning State

**Endpoint**: `GET /api/v1/state/connections`

**Description**: Retrieves the current provisioning.yaml file contents.

**Response**: Raw YAML content


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/deployment/configuration/agent/automation/provisioning-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.