Get the record-import outcome

curl --request GET \
  --url https://dns.basaltic.sh/v1/zones/{zone_id}/record-import \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://dns.basaltic.sh/v1/zones/{zone_id}/record-import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dns.basaltic.sh/v1/zones/{zone_id}/record-import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://dns.basaltic.sh/v1/zones/{zone_id}/record-import"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://dns.basaltic.sh/v1/zones/{zone_id}/record-import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "record_import": {
    "state": "complete",
    "source": "query",
    "complete": false,
    "found": 14,
    "imported": 11,
    "notes": [
      "<string>"
    ],
    "error": "<string>",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You don't have permission to perform this action",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Zones

Get the record-import outcome

What came of import_existing_records — reading the domain’s records off the provider it was moving away from.

Its own resource rather than a field on the zone, because it describes one event that happened once when the zone was created and never changes.

Poll this after creating a zone with import_existing_records: true: state is pending while the background job runs. Read complete before you switch your old provider off — see the schema.

GET

zones

{zone_id}

record-import

Get the record-import outcome

curl --request GET \
  --url https://dns.basaltic.sh/v1/zones/{zone_id}/record-import \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://dns.basaltic.sh/v1/zones/{zone_id}/record-import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dns.basaltic.sh/v1/zones/{zone_id}/record-import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://dns.basaltic.sh/v1/zones/{zone_id}/record-import"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://dns.basaltic.sh/v1/zones/{zone_id}/record-import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "record_import": {
    "state": "complete",
    "source": "query",
    "complete": false,
    "found": 14,
    "imported": 11,
    "notes": [
      "<string>"
    ],
    "error": "<string>",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You don't have permission to perform this action",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The basaltic CLI signs for you.

Send Authorization, X-Date (UTC, YYYYMMDDTHHMMSSZ) and X-Nonce (random per request); add X-Content-Sha256 to bind a body, and X-Amz-Security-Token when using temporary credentials.

Authorization: BASALTIC-HMAC-SHA256 Credential=<access_key_id>/<date>/<region>/basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature=<hex>

<region> is the region code you are calling, or global for the global services. A signature is valid for 5 minutes from X-Date, and mutating requests are replay-guarded on the nonce.

Full signing procedure, including a working implementation: https://docs.basaltic.sh/authentication

Rate limits

There is no global request budget. A limit applies only where an operation documents a 429, and that operation says what it counts. Those responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and, on a 429, Retry-After — read them rather than hard-coding a number. Retrying before Retry-After is refused and extends the window. Everything else is bounded by quota, not by request rate.

Path Parameters

zone_id

string<uuid>

required

DNS Zone ID

Response

The import outcome

record_import

object

What came of import_existing_records — reading the domain's records off the provider it is moving away from.

Its own resource, at GET /v1/zones/{zone_id}/record-import, because it describes one event that happened once when the zone was created and never changes afterwards. 404 when the zone was created without asking for an import, which is the ordinary case and not an error.

A failed import is never a failed zone. The zone exists, resolves once delegated, and can be filled in by hand or from a zone file; only the convenience did not happen.

Show child attributes

Overview

Audit

Billing

Certificate

Compute

Database

DNS

Identity and account

KMS

Load balancer

Network

Quota

Secrets

Storage

Telemetry

Get the record-import outcome

Authorizations

Rate limits

Path Parameters

Response