Provisioning API · Internal testing only
cloneDomain
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/domains/dom_01k5nb3wz7q2hj8vd4rt6ye9ma/clone';const options = { method: 'POST', headers: {'Idempotency-Key': 'example', Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.builders.ac/api/provisioning/v1alpha1/domains/dom_01k5nb3wz7q2hj8vd4rt6ye9ma/clone \ --header 'Authorization: Bearer <token>' \ --header 'Idempotency-Key: example'Clone the domain’s current redirect target and serve the copy on the domain itself. Requires a redirect target (409 redirect_not_configured), an active domain (409 domain_not_active) and the DNS delegation connect sets up (409 domain_traffic_unavailable). Re-running it refreshes the clone.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Domain TypeIDs are accepted case-insensitively. Responses use canonical lowercase.
Header Parameters
Section titled “Header Parameters”A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.
Responses
Section titled “Responses”Accepted. Poll the operation.
object
Canonical lowercase TypeID.
Canonical lowercase TypeID.
Nearest ancestor public Operation which caused this child Operation. Omitted on root Operations.
object
object
object
Canonical lowercase TypeID.
object
Cancellation was requested. It is honoured only at a safe boundary, so keep polling state and done to learn whether it took effect.
Next date by which meaningful progress should be visible.
Public completion SLA for this Operation.
Example
{ "id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw", "object": "operation", "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h", "parent_operation_id": "op_01k5nf4b8yt3qd7vm2ae9rz6hx", "type": "domain.clone", "state": "pending", "done": false, "target": { "type": "domain", "ids": [ "dom_01k5nb3wz7q2hj8vd4rt6ye9ma" ] }, "metadata": { "domain": { "id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma", "name": "northwind-outbound.com" }, "redirect": { "target_url": "https://www.northwind-labs.com", "mode": "redirect" } }, "created_at": "2026-04-15T09:15:04Z", "update_by_date": "2026-04-15T09:45:04Z", "completion_by_date": "2026-04-15T10:15:04Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Idempotency key required. The example shows idempotency_key_required.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_key_required", "title": "Idempotency key required", "status": 400, "detail": "This request requires a valid Idempotency-Key header.", "code": "idempotency_key_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required", "title": "Authentication required", "status": 401, "detail": "Provide an active Provisioning API Key as a Bearer token.", "code": "authentication_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive", "title": "Account inactive", "status": 403, "detail": "This account is inactive.", "code": "account_inactive", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Not found. The example shows not_found.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/not_found", "title": "Not found", "status": 404, "detail": "The requested resource was not found.", "code": "not_found", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
There is no redirect target to clone, the domain is not live, it holds no DNS delegation of ours to serve traffic through, or another operation already holds it.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Where the domain is in its lifecycle. pending is accepted but not started; provisioning is in flight; awaiting_nameservers is waiting for the nameservers this API issued to be delegated at the registrar; active is live; failed needs a retry; deprovisioning and deprovisioned are teardown. Read-only: it moves through the actions, never through PATCH.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Where the domain is in its lifecycle. pending is accepted but not started; provisioning is in flight; awaiting_nameservers is waiting for the nameservers this API issued to be delegated at the registrar; active is live; failed needs a retry; deprovisioning and deprovisioned are teardown. Read-only: it moves through the actions, never through PATCH.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
The Operation holding the resource. Null when the blocking run is a dashboard workflow, which has no public Operation; absent on chapters that do not report it.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
No redirect target
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/redirect_not_configured", "title": "No redirect target", "status": 409, "detail": "There is nothing to clone until the domain has a redirect target. Set one with PUT /domains/{dom}/redirect first.", "code": "redirect_not_configured", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Domain is not active
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/domain_not_active", "title": "Domain is not active", "status": 409, "detail": "This action needs a live domain; `state` says where this one is. Wait for it to reach `active` — poll the connect operation — and try again.", "code": "domain_not_active", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "state": "pending"}Domain cannot serve traffic yet
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/domain_traffic_unavailable", "title": "Domain cannot serve traffic yet", "status": 409, "detail": "This domain is live but we do not hold the DNS delegation that serving a redirect or a clone needs; `state` shows where it is. It settles shortly after the domain is connected — poll the connect operation, then try again.", "code": "domain_traffic_unavailable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "state": "active"}Resource operation in progress
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/resource_operation_in_progress", "title": "Resource operation in progress", "status": 409, "detail": "Wait for the current operation to finish, then retry with a new Idempotency-Key.", "code": "resource_operation_in_progress", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "operation_id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw"}Request already in progress
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_in_progress", "title": "Request already in progress", "status": 409, "detail": "A request using this idempotency key is still in progress.", "code": "idempotency_in_progress", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Rate limit exceeded. The example shows rate_limit_exceeded.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Too many requests were made for this policy.", "code": "rate_limit_exceeded", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "retry_after": "2026-04-15T09:16:04Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Service unavailable. The example shows service_unavailable; this status is also answered with encryption_keys_unavailable, provider_unreachable. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Retry the request later; the service is temporarily unavailable.", "code": "service_unavailable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.