Start a realm import
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/import';
const options = {
method: 'POST',
headers: {
'API-Version': '2026-06-01.beta',
'API-Key': '<API-Key>',
'Content-Type': 'application/json'
},
body: '{"source_kind":"upload","upload_s3_key":"realm-imports/uploads/ws/abc.zip.enc","password":"a-strong-passphrase"}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}curl --request POST \
--url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/import \
--header 'API-Key: <API-Key>' \
--header 'API-Version: 2026-06-01.beta' \
--header 'Content-Type: application/json' \
--data '{ "source_kind": "upload", "upload_s3_key": "realm-imports/uploads/ws/abc.zip.enc", "password": "a-strong-passphrase" }'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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Where the artifact comes from. upload (default) or stored.
Object key of a previously-uploaded artifact (from the upload-url endpoint). Required when source_kind is upload.
A stored realm export id. Required when source_kind is stored.
Password to decrypt an encrypted artifact. Omit for a bare foreign JSON.
Example
{
"source_kind": "upload",
"upload_s3_key": "realm-imports/uploads/ws/abc.zip.enc",
"password": "a-strong-passphrase"
}Responses
Section titled “Responses”Returned when a realm import has been accepted for processing. Poll the resource until status is completed or failed.
object
The imported realm’s name, derived from the artifact.
Percent complete, 0-100.
Keycloak version that produced the artifact.
Target cluster’s Keycloak version at import time.
Failure description. Only set when status is failed.
Example
{
"id": "7b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
"cluster_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"realm": "cust-brasilia",
"source_kind": "upload",
"status": "completed",
"progress": 100,
"source_version": "26.6.1",
"target_version": "26.6.2",
"error_message": null,
"created_at": "2026-07-19T15:00:00Z",
"completed_at": "2026-07-19T15:03:00Z"
}Headers
Section titled “Headers”URL of the resource being created or modified. Poll this endpoint to track completion.
The server could not understand the request due to invalid syntax.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Access is unauthorized.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
Returned when a workspace plan quota would be exceeded. required_plan indicates the minimum plan needed to complete the request.
object
Machine-readable identifier of the quota that was hit, so a client can tell
quotas apart without parsing detail. Known values include cluster_limit
(the workspace’s total cluster allowance), cluster_size_quota (the
allowance for the requested cluster size) and cluster_size (the requested
size is not offered on the plan at all). New values may be added.
How many of the resource the workspace currently has.
Maximum allowed by the current plan. 0 means the plan does not include the resource at all.
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"current_plan": "example",
"required_plan": "example",
"code": "example",
"current_usage": 1,
"current_limit": 1
}Access is forbidden.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The server cannot find the requested resource.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The request conflicts with the current state of the server.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
object
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"errors": [
{
"field": "example",
"detail": "example",
"code": "example",
"value": "example"
}
]
}Client error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Headers
Section titled “Headers”Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}