@@ -283,8 +283,194 @@ If you've written scripts to automate serialization, you'll need to:
Before exporting, you can also run a Metabase command to [drop entity IDs](./commands.md#drop-entity-ids).
## Serializing Metabase via the API
> Just like the CLI serialization commands, these endpoints are only available for [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.
You can initiate imports and exports of serialized Metabase data via the API.
There are two endpoints:
-`/api/ee/serialization/export`
-`/api/ee/serialization/import`
For now, these endpoints are synchronous. If the serialization process takes too long, the request can time out. In this case, we suggest using the CLI commands.
### Use parameters to customize what Metabase exports
You can append optional parameters to tell Metabase what to include or exclude from the export. You can also combine parameters (excluding, of course, `all_collections` and selective collections).
So, assuming you're testing on `localhost`, and you want to exclude all collections from the export, you'd format the URL like so:
Default value: Metabase will export all collections, unless `all_collections` is set to `false`.
To select which collections to export, include the collection IDs. For example, to include collections `1` and `2`:
```html
collection=1&collection=2
```
### `all_collections`
Type: Boolean
Default: `true` (unless you specify a subset of collections with `collection`).
To exclude all collections:
```html
all_collections=false
```
### `settings`
Type: Boolean.
Default: `true`.
To exclude settings:
```html
settings=false
```
### `data_model`
Type: Boolean.
Default: `true`.
To exclude the data model:
```
data_model=false
```
### `field_values`
Type: Boolean.
Default: `false`.
To include field values:
```
field_values=true
```
### `database_secrets`
Type: Boolean.
Default: `false`.
To include secrets:
```html
database_secrets=true
```
### `dirname`
Type: String.
Default: `<instance-name>-<YYYY-MM-dd_HH_mm>`
To specify a different directory:
```
dirname=name_of_your_directory
```
## You must compress your files when serializing via API calls
To keep file sizes over the network under control, both the `export` and `import` endpoints expect GZIP-compressed Tar files (`.tgz`).
### Compress a directory
To compress a directory (e.g., a directory named `metabase_data`).
```sh
tar-czf metabase_data
```
### Extract a directory
To extract/unzip a directory:
```sh
tar-xvf metabase_data.tgz
```
## Metabase adds logs to exports and imports
Exports: Metabase adds logs to the compressed directory as `export.log`.
Imports: You can add the `-o -` flag to export logs directly into the terminal, or `-o import.log` to save to a file.
### Example export request with `curl`
To export the contents of your Metabase, first set up an [API key](../people-and-groups/api-keys.md) and assign the key to the Admin group.
Then run:
```sh
curl \
-H'x-api-key: YOUR_API_KEY'\
-X POST 'http://localhost:3000/api/ee/serialization/export'\
-o metabase_data.tgz
```
Substituting `YOUR_API_KEY` with your API key. This command will download the files as a GZIP-compressed Tar file named `metabase_data.tgz`.
You'll then need to unzip the compressed file:
```sh
tar-xvf metabase_data.tgz
```
The extracted directory will be called something like `metabase-yyyy-MM-dd_HH-mm`, with the date and time of the export.
### Example import request with `curl`
To import contents into your Metabase, first set up an [API key](../people-and-groups/api-keys.md) and assign the key to the Admin group.
Let's say you have your YAML files with Metabase application data in a directory called `metabase_data`. Before importing those files to your target Metabase, you'll need to compress those files.
```sh
tar-czf metabase_data.tgz metabase_data
```
Then post to the `/api/ee/serialization/import`. From the directory where you've stored your GZIP-compressed file, run:
