---
type: api
title: Create or update a snapshot repository
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-snapshot-create-repository
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-snapshot-create-repository
products:
  - Elasticsearch
---

# Create or update a snapshot repository


Availability:

## Paths

- `POST` (also `PUT`) `/_snapshot/{repository}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

#### Path Parameters

- `repository` (string Name)
  The name of the snapshot repository to register or update.

## Description

IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.
To register a snapshot repository, the cluster's global metadata must be writeable.
Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.

Several options for this API can be specified using a query parameter or a request body parameter.
If both parameters are specified, only the query parameter is used.

## Required authorization

* Cluster privileges: `manage`

[About managing snapshot](https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore/self-managed)

## Query String Parameters

- `master_timeout` (string Duration · default: 30s)
  The period to wait for the master node.
If the master node is not available before the timeout expires, the request fails and returns an error.
To indicate that the request should never timeout, set it to `-1`.
- `timeout` (string Duration · default: 30s)
  The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.
If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged.
To indicate that the request should never timeout, set it to `-1`.
- `verify` (boolean · default: true)
  If `true`, the request verifies the repository is functional on all master and data nodes in the cluster.
If `false`, this verification is skipped.
You can also perform this verification with the verify snapshot repository API.

## Request Body

`application/json`

One of:
- **AzureRepository** (`type: azure`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The Azure repository type.
    Values: `azure`
  - `settings` ({} AzureRepositorySettings) — optional
    The repository settings.
    - `chunk_size` (number | string ByteSize) — optional
      Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.
It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.
Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.
Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.
The default varies by repository type.
    - `compress` (boolean · default: true) — optional
      When set to `true`, metadata files are stored in compressed format.
This setting doesn't affect index files that are already compressed by default.
    - `max_restore_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot restore rate per node.
It defaults to unlimited.
Note that restores are also throttled through recovery settings.
    - `max_snapshot_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot creation rate per node.
It defaults to 40mb per second.
Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
    - `base_path` (string) — optional
      The path to the repository data within the container.
It defaults to the root directory.

NOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.
Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.
    - `client` (string · default: default) — optional
      The name of the Azure repository client to use.
    - `container` (string · default: elasticsearch-snapshots) — optional
      The Azure container.
    - `delete_objects_max_size` (number · default: 256) — optional
      The maxmimum batch size, between 1 and 256, used for `BlobBatch` requests.
Defaults to 256 which is the maximum number supported by the Azure blob batch API.
    - `location_mode` (string · default: primary_only) — optional
      Either `primary_only` or `secondary_only`.
Note that if you set it to `secondary_only`, it will force `readonly` to `true`.
    - `max_concurrent_batch_deletes` (number · default: 10) — optional
      The maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with `BlobBatch`.
Note that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits.
Defaults to 10, minimum is 1, maximum is 100.
    - `readonly` (boolean · default: false) — optional
      If `true`, the repository is read-only.
The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.

Only a cluster with write access can create snapshots in the repository.
All other clusters connected to the repository should have the `readonly` parameter set to `true`.
If `false`, the cluster can write to the repository and create snapshots in it.

IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.
Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository.
- **GcsRepository** (`type: gcs`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The Google Cloud Storage repository type.
    Values: `gcs`
  - `settings` ({} GcsRepositorySettings) — required
    The repository settings.
    - `chunk_size` (number | string ByteSize) — optional
      Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.
It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.
Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.
Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.
The default varies by repository type.
    - `compress` (boolean · default: true) — optional
      When set to `true`, metadata files are stored in compressed format.
This setting doesn't affect index files that are already compressed by default.
    - `max_restore_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot restore rate per node.
It defaults to unlimited.
Note that restores are also throttled through recovery settings.
    - `max_snapshot_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot creation rate per node.
It defaults to 40mb per second.
Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
    - `bucket` (string) — required
      The name of the bucket to be used for snapshots.
    - `application_name` (string) — optional — deprecated
      The name used by the client when it uses the Google Cloud Storage service.
    - `base_path` (string) — optional
      The path to the repository data within the bucket.
It defaults to the root of the bucket.

NOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.
Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.
    - `client` (string · default: default) — optional
      The name of the client to use to connect to Google Cloud Storage.
    - `readonly` (boolean · default: false) — optional
      If `true`, the repository is read-only.
The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.

Only a cluster with write access can create snapshots in the repository.
All other clusters connected to the repository should have the `readonly` parameter set to `true`.

If `false`, the cluster can write to the repository and create snapshots in it.

IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.
Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository.
- **S3Repository** (`type: s3`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The S3 repository type.
    Values: `s3`
  - `settings` ({} S3RepositorySettings) — required
    The repository settings.

NOTE: In addition to the specified settings, you can also use all non-secure client settings in the repository settings.
In this case, the client settings found in the repository settings will be merged with those of the named client used by the repository.
Conflicts between client and repository settings are resolved by the repository settings taking precedence over client settings.
    - `chunk_size` (number | string ByteSize) — optional
      Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.
It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.
Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.
Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.
The default varies by repository type.
    - `compress` (boolean · default: true) — optional
      When set to `true`, metadata files are stored in compressed format.
This setting doesn't affect index files that are already compressed by default.
    - `max_restore_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot restore rate per node.
It defaults to unlimited.
Note that restores are also throttled through recovery settings.
    - `max_snapshot_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot creation rate per node.
It defaults to 40mb per second.
Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
    - `bucket` (string) — required
      The name of the S3 bucket to use for snapshots.
The bucket name must adhere to Amazon's S3 bucket naming rules.
    - `base_path` (string) — optional
      The path to the repository data within its bucket.
It defaults to an empty string, meaning that the repository is at the root of the bucket.
The value of this setting should not start or end with a forward slash (`/`).

NOTE: Don't set base_path when configuring a snapshot repository for Elastic Cloud Enterprise.
Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket.
    - `buffer_size` (number | string ByteSize) — optional
      The minimum threshold below which the chunk is uploaded using a single request.
Beyond this threshold, the S3 repository will use the AWS Multipart Upload API to split the chunk into several parts, each of `buffer_size` length, and to upload each part in its own request.
Note that setting a buffer size lower than 5mb is not allowed since it will prevent the use of the Multipart API and may result in upload errors.
It is also not possible to set a buffer size greater than 5gb as it is the maximum upload size allowed by S3.
Defaults to `100mb` or 5% of JVM heap, whichever is smaller.
    - `canned_acl` (string · default: private) — optional
      The S3 repository supports all S3 canned ACLs: `private`, `public-read`, `public-read-write`, `authenticated-read`, `log-delivery-write`, `bucket-owner-read`, `bucket-owner-full-control`.
You could specify a canned ACL using the `canned_acl` setting.
When the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects.
    - `client` (string · default: default) — optional
      The name of the S3 client to use to connect to S3.
    - `delete_objects_max_size` (number · default: 1000) — optional
      The maxmimum batch size, between 1 and 1000, used for `DeleteObjects` requests.
Defaults to 1000 which is the maximum number supported by the  AWS DeleteObjects API.
    - `get_register_retry_delay` (string Duration · default: 5s) — optional
      The time to wait before trying again if an attempt to read a linearizable register fails.
    - `max_multipart_parts` (number · default: 10000) — optional
      The maximum number of parts that Elasticsearch will write during a multipart upload of a single object.
Files which are larger than `buffer_size × max_multipart_parts` will be chunked into several smaller objects.
Elasticsearch may also split a file across multiple objects to satisfy other constraints such as the `chunk_size` limit.
Defaults to `10000` which is the maximum number of parts in a multipart upload in AWS S3.
    - `max_multipart_upload_cleanup_size` (number · default: 1000) — optional
      The maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions.
Defaults to 1000 which is the maximum number supported by the AWS ListMultipartUploads API.
If set to `0`, Elasticsearch will not attempt to clean up dangling multipart uploads.
    - `readonly` (boolean · default: false) — optional
      If true, the repository is read-only.
The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.

Only a cluster with write access can create snapshots in the repository.
All other clusters connected to the repository should have the `readonly` parameter set to `true`.

If `false`, the cluster can write to the repository and create snapshots in it.

IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.
Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository.
    - `server_side_encryption` (boolean · default: false) — optional
      When set to `true`, files are encrypted on server side using an AES256 algorithm.
    - `storage_class` (string · default: standard) — optional
      The S3 storage class for objects written to the repository.
Values may be `standard`, `reduced_redundancy`, `standard_ia`, `onezone_ia`, and `intelligent_tiering`.
    - `throttled_delete_retry.delay_increment` (string Duration · default: 50ms) — optional
      The delay before the first retry and the amount the delay is incremented by on each subsequent retry.
The default is 50ms and the minimum is 0ms.
    - `throttled_delete_retry.maximum_delay` (string Duration · default: 5s) — optional
      The upper bound on how long the delays between retries will grow to.
The default is 5s and the minimum is 0ms.
    - `throttled_delete_retry.maximum_number_of_retries` (number) — optional
      The number times to retry a throttled snapshot deletion.
The default is 10 and the minimum value is 0 which will disable retries altogether.
Note that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries.
- **SharedFileSystemRepository** (`type: fs`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The shared file system repository type.
    Values: `fs`
  - `settings` ({} SharedFileSystemRepositorySettings) — required
    The repository settings.
    - `chunk_size` (number | string ByteSize) — optional
      Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.
It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.
Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.
Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.
The default varies by repository type.
    - `compress` (boolean · default: true) — optional
      When set to `true`, metadata files are stored in compressed format.
This setting doesn't affect index files that are already compressed by default.
    - `max_restore_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot restore rate per node.
It defaults to unlimited.
Note that restores are also throttled through recovery settings.
    - `max_snapshot_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot creation rate per node.
It defaults to 40mb per second.
Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
    - `location` (string) — required
      The location of the shared filesystem used to store and retrieve snapshots.
This location must be registered in the `path.repo` setting on all master and data nodes in the cluster.
Unlike `path.repo`, this setting supports only a single file path.
    - `max_number_of_snapshots` (number · default: 2147483647) — optional
      The maximum number of snapshots the repository can contain.
The default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.
    - `readonly` (boolean · default: false) — optional
      If `true`, the repository is read-only.
The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.

Only a cluster with write access can create snapshots in the repository.
All other clusters connected to the repository should have the `readonly` parameter set to `true`.

If `false`, the cluster can write to the repository and create snapshots in it.

IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.
Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository.
- **ReadOnlyUrlRepository** (`type: url`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The read-only URL repository type.
    Values: `url`
  - `settings` ({} ReadOnlyUrlRepositorySettings) — required
    The repository settings.
    - `chunk_size` (number | string ByteSize) — optional
      Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.
It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.
Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.
Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.
The default varies by repository type.
    - `compress` (boolean · default: true) — optional
      When set to `true`, metadata files are stored in compressed format.
This setting doesn't affect index files that are already compressed by default.
    - `max_restore_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot restore rate per node.
It defaults to unlimited.
Note that restores are also throttled through recovery settings.
    - `max_snapshot_bytes_per_sec` (number | string ByteSize) — optional
      The maximum snapshot creation rate per node.
It defaults to 40mb per second.
Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
    - `http_max_retries` (number · default: 5) — optional
      The maximum number of retries for HTTP and HTTPS URLs.
    - `http_socket_timeout` (string Duration · default: 50s) — optional
      The maximum wait time for data transfers over a connection.
    - `max_number_of_snapshots` (number · default: 2147483647) — optional
      The maximum number of snapshots the repository can contain.
The default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.
    - `url` (string) — required
      The URL location of the root of the shared filesystem repository.
The following protocols are supported:

* `file`
* `ftp`
* `http`
* `https`
* `jar`

URLs using the HTTP, HTTPS, or FTP protocols must be explicitly allowed with the `repositories.url.allowed_urls` cluster setting.
This setting supports wildcards in the place of a host, path, query, or fragment in the URL.

URLs using the file protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster.
This location must be registered in the `path.repo` setting.
You don't need to register URLs using the FTP, HTTP, HTTPS, or JAR protocols in the `path.repo` setting.
- **SourceOnlyRepository** (`type: source`)
  - `uuid` (string) — optional
  - `type` (enum) — required
    The source-only repository type.
    Values: `source`
  - `settings` (SourceOnlyRepositorySettings) — required
    The repository settings.

## Response

`application/json`

- `acknowledged` (boolean)
  For a successful response, this value is always true. On failure, an exception is returned instead.
## Code Examples

#### Console

```console
POST /_snapshot/my_repository
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}
```

#### JavaScript

```javascript
const response = await client.snapshot.createRepository({
  name: "my_repository",
  repository: {
    type: "fs",
    settings: {
      location: "my_backup_location",
    },
  },
});
```

#### Python

```python
resp = client.snapshot.create_repository(
    name="my_repository",
    repository={
        "type": "fs",
        "settings": {
            "location": "my_backup_location"
        }
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_snapshot/my_repository" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fs",
    "settings": {
      "location": "my_backup_location"
    }
  }'
```

#### Java

```java
client.snapshot().createRepository(c -> c
    .name("my_repository")
    .repository(r -> r
        .fs(f -> f
            .settings(s -> s
                .location("my_backup_location")
            )
        )
    )
);
```

#### C#

```c#
var response = await client.Snapshot
    .CreateRepositoryAsync(name: "my_repository", d1 => d1
        .Repository(new SharedFileSystemRepository()
        {
            Settings = new()
            {
                Location = "my_backup_location"
            }
        })
    );
```

#### PHP

```php
$resp = $client->snapshot()->createRepository([
    "repository" => "my_repository",
    "body" => [
        "type" => "fs",
        "settings" => [
            "location" => "my_backup_location",
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.snapshot.create_repository(
  repository: "my_repository",
  body: {
    "type": "fs",
    "settings": {
      "location": "my_backup_location"
    }
  }
)
```