> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Import a zone file > Load an RFC 1035 master file — a BIND zone file, the format every DNS provider exports — into an existing zone. **Merges, never replaces.** An RRset in the file replaces the RRset at the same name and type wholesale; an RRset the file does not mention is left exactly as it is. So an import cannot delete a record, and importing the same file twice is a no-op rather than an error — which is what makes it safe to retry. **All or nothing.** The whole file is validated before any record is written: every record has to pass the same type, name, TTL and rdata checks `createRecord` applies, the same CNAME-coexistence rule, and the same per-zone and per-org record quota. One bad record refuses the file and the zone is untouched. **What is skipped rather than imported.** The SOA and the apex NS set are the platform's: the zone is served by our nameservers, and the apex NS is what the parent delegates to. The DNSSEC records (`RRSIG`, `DNSKEY`, `DS`, `NSEC`, `NSEC3`, `NSEC3PARAM`, `CDS`, `CDNSKEY`) are generated by our signer from keys your file cannot know. Records the file places outside this zone are skipped too. All of them come back in `skipped` with a reason — a file exported from a signed zone carries every one, so refusing the file over them would make export/import unusable. The file may be sent as JSON (`zone_file`) or as the raw request body under any other content type, so `curl --data-binary @db.example.com` works directly. Maximum 1 MiB. On success the zone's SOA serial advances once for the whole import and the change propagates to the authoritative nameservers. ## OpenAPI ````yaml /api-reference/specs/dns.yaml post /v1/zones/{zone_id}/import openapi: 3.0.3 info: title: Basaltic DNS API version: 1.0.0 description: | Authoritative hosted zones and their records, signed with DNSSEC. A zone is only served once its ownership is verified; associating a zone with a VPC makes it resolvable privately inside that network. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://dns.basaltic.sh description: Global API endpoint security: - SignatureAuth: [] paths: /v1/zones/{zone_id}/import: post: tags: - DNS summary: Import a zone file description: > Load an RFC 1035 master file — a BIND zone file, the format every DNS provider exports — into an existing zone. **Merges, never replaces.** An RRset in the file replaces the RRset at the same name and type wholesale; an RRset the file does not mention is left exactly as it is. So an import cannot delete a record, and importing the same file twice is a no-op rather than an error — which is what makes it safe to retry. **All or nothing.** The whole file is validated before any record is written: every record has to pass the same type, name, TTL and rdata checks `createRecord` applies, the same CNAME-coexistence rule, and the same per-zone and per-org record quota. One bad record refuses the file and the zone is untouched. **What is skipped rather than imported.** The SOA and the apex NS set are the platform's: the zone is served by our nameservers, and the apex NS is what the parent delegates to. The DNSSEC records (`RRSIG`, `DNSKEY`, `DS`, `NSEC`, `NSEC3`, `NSEC3PARAM`, `CDS`, `CDNSKEY`) are generated by our signer from keys your file cannot know. Records the file places outside this zone are skipped too. All of them come back in `skipped` with a reason — a file exported from a signed zone carries every one, so refusing the file over them would make export/import unusable. The file may be sent as JSON (`zone_file`) or as the raw request body under any other content type, so `curl --data-binary @db.example.com` works directly. Maximum 1 MiB. On success the zone's SOA serial advances once for the whole import and the change propagates to the authoritative nameservers. operationId: importZoneFile parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/ZoneId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ZoneImportRequest' text/dns: schema: type: string description: The zone file, sent as the raw request body. text/plain: schema: type: string description: The zone file, sent as the raw request body. responses: '200': description: | The file was imported. Read `skipped` before concluding the zone matches the file. content: application/json: schema: $ref: '#/components/schemas/ZoneImportResponse' '400': description: | The file was refused and nothing was written. The message names what was wrong: a syntax error carries the line and column, a record the zone may not hold is named by owner and type. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: | A record in the file conflicts with one created concurrently, or a CNAME in the file would share a name with another type. Nothing was written. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' security: - SignatureAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 ZoneId: name: zone_id in: path description: DNS Zone ID required: true schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 schemas: ZoneImportRequest: type: object required: - zone_file properties: zone_file: type: string description: > The zone file, as text. `$ORIGIN`, `$TTL`, `$GENERATE`, relative names and parenthesised multi-line records are all honoured; `$INCLUDE` is refused, because the path it names would be read on our filesystem rather than yours. example: | $ORIGIN example.com. $TTL 3600 www IN A 203.0.113.10 @ IN MX 10 mail.example.com. dkim IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqh" ZoneImportResponse: type: object properties: import: $ref: '#/components/schemas/ZoneImportResult' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 ZoneImportResult: type: object description: > What the import did. `records_created` plus `records_replaced` is every RRset taken from the file; anything in `skipped` is still in the file but not in the zone. properties: records_created: type: integer description: RRsets in the file that the zone did not already have. example: 7 records_replaced: type: integer description: | RRsets that existed at the same name and type and were replaced wholesale by the file's values. example: 2 records_by_type: type: object additionalProperties: type: integer description: Imported RRset count per record type. example: A: 4 MX: 1 TXT: 2 skipped: type: array items: $ref: '#/components/schemas/ZoneImportSkipped' warnings: type: array items: type: string description: > Records that were imported, but not exactly as written — an RRset the file gave more than one TTL, for instance. ZoneImportSkipped: type: object description: One RRset in the file that was not imported, and why. properties: name: type: string example: example.com type: type: string example: NS reason: type: string example: >- the apex NS set is the delegation this platform's nameservers answer for responses: Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > 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=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` 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. ````