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

# MinIO

> Client-mode REST API connector for MinIO S3-compatible storage: PutObject, GetObject, HeadObject, ListBuckets, and PUT to a presigned URL

Technical Preview

## Overview

A client-mode connector for a **curated IIoT object-storage** slice of the [MinIO S3-compatible API](https://min.io/docs/minio/linux/developers/API.html) under path-style `https://play.min.io` (or your self-hosted host):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (smoke) | `GET /` | ListBuckets for the signing identity |
| PUT object (snapshot, CSV rollup) | `PUT /{bucket}/{key}` | SigV4 headers required |
| GET object | `GET /{bucket}/{key}` | SigV4 headers required |
| (optional) HeadObject | `HEAD /{bucket}/{key}` | Metadata without body |
| PUT to presigned URL | `PUT {presigned_path}` | No Authorization; switch BASE to URL origin |
| Bucket notifications → MQTT | — | Docs-only; configure MinIO to publish to Coreflux MQTT; future `ENABLE_SERVER` for HTTP notify |

`BASE_ADDRESS` defaults to `https://play.min.io` (no trailing slash; path-style). For self-hosted MinIO use `https://minio.example.com:9000` (or your TLS origin). Topics use `storage/minio/<object>/<verb>`.

> [!NOTE]
>
> **play.min.io** is MinIO's public playground. Access keys published in MinIO SDK docs are open; treat all play data as world-readable. Prefer self-hosted for production.

> [!NOTE]
>
> **Path-style vs virtual-hosted:** MinIO usually expects path-style (`/{bucket}/{key}`), which this template uses. If virtual-hosted is enabled, set `BASE_ADDRESS` to `https://{bucket}.your-host` and use endpoints like `/{key}`.

> [!NOTE]
>
> **Presigned PUT:** set `BASE_ADDRESS` to the presigned URL origin only, put path+query in `presigned_path`, and omit SigV4 headers — the query string carries the signature. Ideal for edge devices that must not hold access keys.

> [!NOTE]
>
> **Bucket notifications:** MinIO can publish object events directly to MQTT (point at your Coreflux broker). That fan-out is configured on the MinIO side and is not part of this client connector. Receiving HTTP notification POSTs would need a separate `ENABLE_SERVER` REST\_API (not packaged).

> [!NOTE]
>
> **Admin API** (`/minio/admin/…`, `mc admin`) is out of scope for this template — keep ops Admin calls outside the object-storage connector.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — MinIO curated S3-compatible slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256} — or PutPresigned (no Authorization)
# BASE_ADDRESS: https://play.min.io (path-style); swap for self-hosted

DEFINE ROUTE MinioRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://play.min.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT Listbuckets
        WITH SOURCE_TOPIC "storage/minio/buckets/list"
        WITH DESTINATION_TOPIC "storage/minio/buckets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putobject
        WITH SOURCE_TOPIC "storage/minio/object/put"
        WITH DESTINATION_TOPIC "storage/minio/object/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Getobject
        WITH SOURCE_TOPIC "storage/minio/object/get"
        WITH DESTINATION_TOPIC "storage/minio/object/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Headobject
        WITH SOURCE_TOPIC "storage/minio/object/head"
        WITH DESTINATION_TOPIC "storage/minio/object/head/response"
        WITH METHOD "HEAD"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putpresigned
        WITH SOURCE_TOPIC "storage/minio/object/put-presigned"
        WITH DESTINATION_TOPIC "storage/minio/object/put-presigned/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.presigned_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `MinioRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://play.min.io` (path-style default; swap for self-hosted) |
| Topic prefix | `storage/minio/...` |
| Default Content-Type | `application/octet-stream` |
| SigV4 region | commonly `us-east-1` (service `s3`) |
| Hub status | Technical preview (`WITH STATUS "beta"`) |

## Authentication

### AWS Signature Version 4

MinIO uses the same SigV4 scheme as S3 — **not** `Authorization: Bearer …`. Sign each request with [SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) (service `s3`) and pass:

| MQTT JSON field | HTTP header |
| - | - |
| `authorization` | `Authorization` (`AWS4-HMAC-SHA256 Credential=…`) |
| `x_amz_date` | `x-amz-date` |
| `x_amz_content_sha256` | `x-amz-content-sha256` |

Use Hub secrets for `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` (or AWS-named equivalents) in an upstream signing helper. Never commit real keys.

### Presigned URLs (recommended for edge)

Generate a time-limited PUT or GET URL with `mc`, the AWS CLI, or a MinIO SDK. For PutPresigned:

1. Point `BASE_ADDRESS` at the URL origin.
2. Put path + query into `presigned_path`.
3. Omit Authorization — do not re-sign on the broker.

## MQTT topics

| Event | Request topic | Response topic |
| - | - | - |
| ListBuckets | `storage/minio/buckets/list` | `…/response` |
| PutObject | `storage/minio/object/put` | `…/response` |
| GetObject | `storage/minio/object/get` | `…/response` |
| HeadObject | `storage/minio/object/head` | `…/response` |
| PutPresigned | `storage/minio/object/put-presigned` | `…/response` |

## Example payloads

**ListBuckets smoke (after signing):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "AWS4-HMAC-SHA256 Credential=AKIA.../20261004/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=...",
  "x_amz_date": "20261004T040000Z",
  "x_amz_content_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```

**PutObject CSV rollup:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "bucket": "my-iiot-rollups",
  "key": "line-a/2026-10-04/rollup.csv",
  "content_type": "text/csv",
  "authorization": "AWS4-HMAC-SHA256 Credential=...",
  "x_amz_date": "20261004T040100Z",
  "x_amz_content_sha256": "<sha256 of body>",
  "payload": "ts,device,temp\n2026-10-04T04:01:00Z,sensor-01,72.5\n"
}
```

**PutPresigned:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "presigned_path": "/my-iiot-rollups/line-a/snapshot.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
  "content_type": "application/json",
  "payload": "{\"device\":\"sensor-01\",\"temp\":72.5}"
}
```

## References

* [MinIO API](https://min.io/docs/minio/linux/developers/API.html)
* [MinIO Python SDK (play.min.io)](https://docs.min.io/aistor/developers/sdk/python/)
* [MinIO bucket notifications](https://min.io/docs/minio/linux/administration/monitoring/publish-events-to-mqtt.html)
* [Authenticating Requests (SigV4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
* [Amazon S3 connector (same surface)](/latest/lot-language/routes/rest-api-apps/amazon-s3)
* [Coreflux REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Package status

**Ready** on the factory after live SigV4 smoke against `https://play.min.io` (ListBuckets + Put/Get/Head) recorded in `TEST.md`. Hub / docs status remains **beta**. Swap `BASE_ADDRESS` to your self-hosted MinIO for production.


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