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

Inventory API Reference

On this page