> ## 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. # Configure record health check > Attach or replace the record's health check. The nameservers then answer only with the healthy targets at the most-preferred priority, failing over to the next priority when those go unhealthy, and answering with every configured value if none is healthy. Only A and AAAA records can carry a check, and only for addresses the control plane can reach — a check on a private (RFC1918 or unique-local) address is refused, because the prober runs in the control plane and could never reach a tenant VPC. ## OpenAPI ````yaml /api-reference/specs/dns.yaml put /v1/zones/{zone_id}/records/{record_id}/health-check 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}/records/{record_id}/health-check: put: tags: - DNS summary: Configure record health check description: >- Attach or replace the record's health check. The nameservers then answer only with the healthy targets at the most-preferred priority, failing over to the next priority when those go unhealthy, and answering with every configured value if none is healthy. Only A and AAAA records can carry a check, and only for addresses the control plane can reach — a check on a private (RFC1918 or unique-local) address is refused, because the prober runs in the control plane and could never reach a tenant VPC. operationId: putRecordHealthCheck parameters: - $ref: '#/components/parameters/ZoneId' - $ref: '#/components/parameters/RecordId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordHealthCheckRequest' responses: '200': description: Health check configured content: application/json: schema: $ref: '#/components/schemas/RecordHealthCheckResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - SignatureAuth: [] components: parameters: ZoneId: name: zone_id in: path description: DNS Zone ID required: true schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 RecordId: name: record_id in: path description: DNS Record ID required: true schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 schemas: RecordHealthCheckRequest: type: object required: - protocol - port properties: protocol: type: string enum: - http - https - tcp description: >- No `udp`: a UDP probe cannot distinguish a healthy target from a silent one. `https` probes do not verify the certificate, because the probe dials an address rather than a name — it measures whether the target is serving, not who it is. example: http port: type: integer minimum: 1 maximum: 65535 description: >- Required — a record's value is a bare address with no port to inherit. example: 80 path: type: string default: / description: Probed HTTP path. Ignored for `tcp`. example: /healthz interval_sec: type: integer minimum: 10 maximum: 3600 default: 30 timeout_sec: type: integer minimum: 1 maximum: 60 default: 5 description: >- Must be below `interval_sec`, or a slow target's probes overlap each other. healthy_threshold: type: integer minimum: 1 maximum: 10 default: 3 description: Consecutive successes before a target is answered again. unhealthy_threshold: type: integer minimum: 1 maximum: 10 default: 3 description: >- Consecutive failures before a target stops being answered. Every transition re-signs the whole zone, so this is damping rather than decoration. matcher: type: string default: '200' description: >- HTTP status or inclusive range counted as healthy. Ignored for `tcp`. example: 200-299 targets: type: array description: >- Failover positions. Any value left out defaults to priority 0. A value that is not one of the record's values is rejected. items: $ref: '#/components/schemas/RecordHealthCheckTarget' RecordHealthCheckResponse: type: object properties: health_check: $ref: '#/components/schemas/RecordHealthCheck' RecordHealthCheckTarget: type: object description: >- One of the record's values and its failover position. Lower priority is preferred; values sharing a priority are one tier and are answered together, so 0 and 1 is a failover pair and 0 and 0 is active/active. required: - content properties: content: type: string description: An address that is already one of the record's values. example: 203.0.113.10 priority: type: integer minimum: 0 maximum: 255 default: 0 example: 0 RecordHealthCheck: type: object properties: protocol: type: string enum: - http - https - tcp port: type: integer path: type: string interval_sec: type: integer timeout_sec: type: integer healthy_threshold: type: integer unhealthy_threshold: type: integer matcher: type: string targets: type: array items: $ref: '#/components/schemas/RecordHealthCheckTargetStatus' served: type: array readOnly: true description: >- The values the nameservers are answering with right now. The record's own `values` stay whatever was configured — the difference between the two IS the failover, so it is reported rather than left to be inferred. items: type: string example: - 203.0.113.20 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 RecordHealthCheckTargetStatus: type: object properties: content: type: string readOnly: true example: 203.0.113.10 priority: type: integer readOnly: true example: 0 status: type: string readOnly: true enum: - initial - healthy - unhealthy description: >- `initial` is a target no probe has yet reached a verdict on. It is ANSWERED while initial, so a freshly created record resolves immediately rather than being dark until its first probe. example: healthy last_checked_at: type: string format: date-time readOnly: true last_transition_at: type: string format: date-time readOnly: true responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 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 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload 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. ````