MinIO — API Surface#

API types#

REST/HTTP (S3-compatible) · Admin REST (madmin) · STS REST (AWS-compatible) · Prometheus Metrics HTTP · Internal Grid RPC (WebSocket/binary) · CLI · FTP/SFTP (protocol gateways)

REST/HTTP API — S3-Compatible (registerAPIRouter)#

Router#

github.com/minio/mux — a maintained fork of gorilla/mux. Routes registered imperatively in cmd/api-router.go:255 via registerAPIRouter(*mux.Router). Supports virtual-hosted-style bucket routing ({bucket}.domain) and path-style (/{bucket}). Both are registered simultaneously.

Route registration#

All routes are registered programmatically in registerAPIRouter. Each handler is wrapped in s3APIMiddleware(handlerFunc, flags...) which applies tracing, gzip, throttling, and stats collection per-endpoint using bit-flags (noGZS3HFlag, traceHdrsS3HFlag, noThrottleS3HFlag).

Middleware chain (global — globalMiddlewares in cmd/routers.go:54)#

Applied to every request before any route-specific handler:

Per-handler S3 middleware (s3APIMiddleware) additionally applies: tracing (headers only or full body), gzip response compression, and maxClients throttling.

Authentication#

• AWS Signature Version 4 (SigV4) — primary auth for all S3 and admin requests
• Presigned URLs — V2 and V4 signed URLs for time-limited object access
• STS bearer tokens — short-lived credentials from the STS API
• Anonymous access — for public bucket policies

Key S3 API endpoints (/{bucket}/{object} and /{bucket})#

Object operations:

Bucket operations:

Root operations:

Admin API (/minio/admin/v3/...)#

Registered in cmd/admin-router.go:138 via registerAdminRouter(*mux.Router, enableConfigOps bool). Uses adminMiddleware which adds logger.ReqInfo context, emits audit log on completion, and checks object layer availability.

Service management:

• POST /service?action=...&type=2 — restart/stop server (v2)
• POST /update?updateURL=...&type=2 — rolling update (v2)

Observability:

• GET /info — cluster/node info
• GET /storageinfo — storage capacity and drive health
• GET /datausageinfo — per-bucket data usage
• GET /metrics — cluster metrics snapshot
• GET /trace — live HTTP trace stream (SSE)
• GET /log — live console log stream
• GET /healthinfo / /obdinfo — health diagnostic bundle
• GET/POST /inspect-data — raw metadata inspection tool
• POST /speedtest/object|drive|net|site — benchmarking endpoints
• POST /profile?profilerType=... — pprof profiling

Healing (erasure mode only):

• POST /heal/[{bucket}[/{prefix}]] — trigger heal scan
• POST /background-heal/status — background healer status

Pool management (distributed erasure only):

• GET /pools/list — list all server pools
• GET /pools/status?pool=... — pool decommission status
• POST /pools/decommission?pool=... — start decommission
• POST /pools/cancel?pool=... — cancel decommission
• POST /rebalance/start | GET /rebalance/status | POST /rebalance/stop — data rebalancing

IAM (users, groups, policies):

• PUT /add-user?accessKey=... — create user
• DELETE /remove-user?accessKey=...
• GET /list-users[?bucket=...]
• GET /user-info?accessKey=...
• PUT /set-user-status?accessKey=...&status=...
• PUT /add-canned-policy?name=... — create policy
• DELETE /remove-canned-policy?name=...
• GET /info-canned-policy?name=...
• GET /list-canned-policies[?bucket=...]
• PUT /set-user-or-group-policy?policyName=...&userOrGroup=...&isGroup=...
• POST /idp/builtin/policy/{attach|detach} — attach/detach policies
• PUT/DELETE/GET /update-group-members | /group | /groups | /set-group-status
• PUT /add-service-account — create service account (AKID/secret pair)
• POST /update-service-account?accessKey=...
• GET /info-service-account?accessKey=...
• GET /list-service-accounts
• DELETE /delete-service-account?accessKey=...
• GET /temporary-account-info?accessKey=... — STS account info
• GET /list-access-keys-bulk?listType=... — bulk key listing
• GET /export-iam / PUT /import-iam[-v2] — IAM backup/restore
• GET /accountinfo — current user account info

Identity providers (LDAP, OpenID):

• PUT/POST/GET/DELETE /idp-config/{type}/{name} — IDP configuration CRUD
• PUT /idp/ldap/add-service-account — LDAP-linked service account
• GET /idp/ldap/list-access-keys[?userDN=...]
• POST /idp/ldap/policy/{attach|detach}
• GET /idp/builtin/policy-entities | /idp/ldap/policy-entities
• GET /idp/openid/list-access-keys-bulk

Bucket administration:

• GET /get-bucket-quota?bucket=... | PUT /set-bucket-quota?bucket=...
• GET /list-remote-targets?bucket=...&type=...
• PUT /set-remote-target?bucket=... — configure replication remote
• DELETE /remove-remote-target?bucket=...&arn=...
• POST /replication/diff?bucket=... — pending replication diff
• GET /replication/mrf?bucket=... — most-recently-failed replication entries
• GET /export-bucket-metadata | PUT /import-bucket-metadata — migration

Batch jobs:

• POST /start-job | GET /list-jobs | GET /status-job | GET /describe-job | DELETE /cancel-job

Tiered storage (ILM):

• PUT /tier | POST /tier/{tier} | GET /tier | DELETE /tier/{tier} | GET /tier/{tier} (verify)
• GET /tier-stats

Site replication (cluster-level):

• PUT /site-replication/add|remove|edit
• GET /site-replication/info|metainfo|status
• Internal peer-to-peer sync endpoints: /site-replication/peer/*
• PUT /site-replication/resync/op?operation=...

Distributed locking (dist erasure only):

• GET /top/locks — active distributed locks
• POST /force-unlock?paths=...

KMS:

• POST /kms/status
• POST /kms/key/create?key-id=...
• GET /kms/key/status

Config KV:

• GET /get-config-kv?key=... | PUT /set-config-kv | DELETE /del-config-kv
• GET /list-config-history-kv | DELETE /clear-config-history-kv | PUT /restore-config-history-kv
• GET /config | PUT /config — bulk import/export

STS API — AWS-Compatible (registerSTSRouter)#

All endpoints receive POST / with application/x-www-form-urlencoded body. Distinguishes actions via query parameters.

All return temporary credentials (access key, secret, session token) with configurable duration.

Metrics API — Prometheus-Compatible (registerMetricsRouter)#

Mounted under /minio/.... Auth controlled by MINIO_PROMETHEUS_AUTH_TYPE (jwt [default] or public).

KMS API (/minio/kms/v1/...)#

Registered separately via cmd/kms-router.go. Endpoints for KMS key management and status.

• GET /metrics — KMS metrics
• POST /status, POST /key/create, GET /key/status

Internal Grid RPC (internal/grid)#

Not a user-facing API, but defines the intra-cluster communication surface:

• grid.RoutePath (/minio/grid/ws/) — general-purpose cluster RPC (typed handler registration)
• grid.RouteLockPath (/minio/grid/lock/) — distributed locking RPC

Handlers registered on startup in registerDistErasureRouters and registerLockRESTHandlers. Message types are code-generated; handlers registered with grid.Manager.Register(id, handler).

Also includes legacy REST-based peer protocols (/minio/storage/{version}/..., /minio/peer/{version}/...) for operations not yet migrated to the grid.

CLI#

• Framework: github.com/urfave/cli (v1-style)
• Entry point: cmd/main.go → newApp("minio")
• Commands:

The server command is the only meaningful command for end-users. Flags include:

• --address — listen address (default :9000)
• --console-address — embedded console listen address
• --certs-dir / --certs-file — TLS
• --config — YAML config file path
• --ftp / --sftp — enable FTP/SFTP protocol gateways
• --quiet, --anonymous, --json — output formatting

FTP / SFTP (Protocol Gateways)#

Started as background goroutines during serverMain() when --ftp or --sftp flags are present. Not HTTP — these are independent protocol servers that translate FTP/SFTP operations to ObjectLayer calls, providing an S3-equivalent surface over legacy protocols.

Plugin / Extension system#

MinIO has no external plugin mechanism. Extension happens via:

• Lambda functions / Object Lambda: GetObjectLambdaHandler routes GET requests through a configured ARN before returning data. The function URL is registered per-bucket via bucket configuration.
• Event notification targets: Kafka, NATS, Redis, Elasticsearch, AMQP, MySQL, PostgreSQL, NSQ, Webhook — configured as notification targets in the object store config. Not a plugin interface in the code; each target type is compiled in.
• Batch jobs: Users define YAML job specs (replicate, key-rotate, expire, archive) submitted via POST /admin/v3/start-job. Built-in job executor, not extensible by third-party code.
• Identity providers: LDAP and OpenID Connect are the two external integration points for IAM. New IDP types cannot be added without modifying the core.

Library API#

MinIO is primarily a server binary, not a library. However:

• github.com/minio/madmin-go — the separate madmin module provides the Go client library for the Admin API. It is versioned independently and widely used by tools (mc, operators).
• github.com/minio/minio-go — separate S3 client library (not in this repo).
• internal/ packages are not exported — internal/grid, internal/dsync, internal/hash, internal/crypto etc. are all private.
• cmd/ package is a single flat package with no public library intent. All exported symbols in cmd/ are incidental to Go’s visibility rules, not an intentional public API.