Inventory API Reference

This page documents the RESTful API endpoints for managing bucket inventory configurations. All inventory operations are scoped to a bucket and use the ?minio-inventory query parameter.

For CLI-based management, see mc inventory. For configuration details, see the Configuration Reference.

Permissions

Inventory API endpoints require the following IAM permissions:

Permission Operations
s3:GetInventoryConfiguration Retrieve configurations and job statuses
s3:PutInventoryConfiguration Create, update, and delete configurations
s3:ListBucket Required on the source bucket for jobs to run
admin:InventoryControl Cancel, suspend, and resume jobs (admin only)

Generate configuration template

Generate a YAML template for a new inventory configuration.

Request:

GET /{bucket}?minio-inventory&generate&id={id}
Parameter Type Required Description
bucket string yes Source bucket name
id string yes ID for the new inventory configuration

Response: 200 OK with Content-Type: application/x-yaml

Create or update a configuration

Create a new inventory configuration or update an existing one. Provide the configuration in the request body as a YAML document.

Request:

PUT /{bucket}?minio-inventory&id={id}
Parameter Type Required Description
bucket string yes Source bucket name
id string yes Inventory configuration ID

Request body: Complete inventory configuration in YAML format. See the Configuration Reference for the YAML schema.

Response: 200 OK

Get a configuration

Retrieve a specific inventory configuration.

Request:

GET /{bucket}?minio-inventory&id={id}

Response: 200 OK with Content-Type: application/json

{
  "bucket": "my-bucket",
  "id": "daily-report",
  "user": "admin",
  "yamlDef": "..."
}

Delete a configuration

Delete an inventory configuration from a bucket.

Request:

DELETE /{bucket}?minio-inventory&id={id}

Response: 200 OK

List configurations

List all inventory configurations for a bucket. Results are paginated.

Request:

GET /{bucket}?minio-inventory&continuation-token={token}

For the first request, provide an empty token: &continuation-token=

Response: 200 OK with Content-Type: application/json

{
  "items": [
    {
      "bucket": "my-bucket",
      "id": "daily-report",
      "user": "admin"
    }
  ],
  "nextContinuationToken": "..."
}

Use the nextContinuationToken value to retrieve subsequent pages.

Get job status

Retrieve the status of a specific inventory job.

Request:

GET /{bucket}?minio-inventory&id={id}&status

Response: 200 OK with Content-Type: application/json

{
  "bucket": "my-bucket",
  "id": "daily-report",
  "user": "admin",
  "schedule": "daily",
  "state": "completed",
  "startTime": "2025-10-11T10:30:00Z",
  "endTime": "2025-10-11T10:45:00Z",
  "scanned": "my-bucket/path/to/last/scanned/object",
  "matched": "my-bucket/path/to/last/matched/object",
  "scannedCount": 15234,
  "matchedCount": 8421,
  "recordsWritten": 8421,
  "outputFilesCount": 3,
  "executionTime": "15m0s",
  "manifestPath": "dest-bucket/prefix/source-bucket/daily-report/2025-10-11T10-30Z/manifest.json"
}

Status fields

Field Type Description
bucket string Source bucket name
id string Inventory configuration ID
user string User who created the job
accessKey string Access key used for job execution
schedule string Job schedule: once, hourly, daily, weekly, monthly, yearly
state string Current state: sleeping, pending, running, completed, failed, errored, suspended, canceled
nextScheduledTime timestamp Next execution time (periodic jobs in sleeping state only)
startTime timestamp When the current or last execution started
endTime timestamp When the execution completed
scannedCount uint64 Total objects scanned
scanned string Last scanned object path
matched string Last matched object path
matchedCount uint64 Objects matching the configured filters
recordsWritten uint64 Metadata records written to output files
outputFilesCount uint64 Number of output data files created
executionTime string Total execution time (for example, 15m0s, 2h30m)
numStarts uint64 Number of times the job has started
numErrors uint64 Total errors encountered
numLockLosses uint64 Times the job lost its distributed lock
manifestPath string Path to the manifest.json file (present after first output file)
retryAttempts uint64 Retry attempts for failed jobs
lastFailTime timestamp When the last failure occurred (present on errors only)
lastFailErrors string[] Up to 5 most recent error messages (present on errors only)

Timestamps use RFC 3339 format.

Admin control operations

These operations require admin:InventoryControl permission.

Cancel a job

Cancels a running inventory job. For periodic jobs, this stops only the current execution. For once jobs, cancellation is terminal.

POST /minio/admin/v3/inventory/{bucket}/{id}/cancel

Responses: 200 OK, 409 Conflict (already canceled), 404 Not Found, 403 Forbidden

Suspend a job

Suspends a job and prevents all future scheduled runs until resumed.

POST /minio/admin/v3/inventory/{bucket}/{id}/suspend

Responses: 200 OK, 409 Conflict (already suspended or completed), 404 Not Found, 403 Forbidden

Resume a job

Resumes a suspended job and re-enables scheduling.

POST /minio/admin/v3/inventory/{bucket}/{id}/resume

Responses: 200 OK, 409 Conflict (not suspended), 404 Not Found, 403 Forbidden