---
title: "Start a realm import"
method: POST
path: "/clusters/{cluster_id}/realms/import"
tags: ["Imports"]
---

# Start a realm import

`POST /clusters/{cluster_id}/realms/import`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/realms/import`
- Auth: API key in header `API-Key`

Imports a realm (configuration, users, and credentials) into the cluster via the Keycloak Admin
API. Preflight validates the target Keycloak version, refuses a name collision, and blocks on
missing password-hash providers. Poll `GET /realm-imports/{import_id}` until `status` is
`completed` or `failed`.

Required scope: `clusters:imports:write`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

- `API-Version` '2026-06-01.beta', required

## Request body

- CreateRealmImportRequest
  - `source_kind` 'upload' | 'stored'
  - `upload_s3_key` string: Object key of a previously-uploaded artifact (from the upload-url endpoint). Required when `source_kind` is `upload`.
  - `source_export_id` string: A stored realm export id. Required when `source_kind` is `stored`.
  - `password` string: Password to decrypt an encrypted artifact. Omit for a bare foreign JSON.

## Response `202`

Returned when a realm import has been accepted for processing. Poll the resource until `status` is `completed` or `failed`.

- RealmImport
  - `id` string, uuid, required
  - `cluster_id` string, uuid, required
  - `realm` string, required: The imported realm's name, derived from the artifact.
  - `source_kind` 'upload' | 'stored', required
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required
  - `progress` integer, required: Percent complete, 0-100.
  - `source_version` string, nullable: Keycloak version that produced the artifact.
  - `target_version` string, nullable: Target cluster's Keycloak version at import time.
  - `error_message` string, nullable: Failure description. Only set when `status` is `failed`.
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)