DNSMint

Every hostname this credential can see, with how many are active and the plan's cap. Check the cap before minting: a hostname is the unit the plan counts.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

What this account's plan allows and how much of it is used: hostnames, dedicated domains, and whether a plan is active at all. Also says whether a checkout is outstanding, which is how you find out a payment link you were given has not been completed yet. Call this after handing someone a checkout URL, instead of retrying a mint to see if it worked. It costs nothing and changes nothing.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One hostname's status and certificate mode. Does not say where it points: DNS is the authoritative answer for that, so use diagnose_hostname or resolve the name.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The hostname's id, from list_hostnames."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Why a hostname is or is not working: what the nameservers answer, what public resolvers see, and whether a certificate has been issued. Use this before assuming something is broken; a name minted moments ago may simply not have propagated.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The hostname's id, from list_hostnames."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Register an address and get back a stable hostname that survives the address changing. This is the tool to use when a machine or agent needs a name. The address class is fixed for the life of the name: mint with a public address and it stays public, mint with a private one and it stays private. Crossing later is refused, so pass the address the machine will actually serve on. A target fixes the class the same way, from whatever it resolves to. A hostname is one label above a domain. Names below a hostname are not hostnames and cannot be minted. Newly minted names report status 'pending' and go 'live' within about a minute.

{
  "type": "object",
  "properties": {
    "ip": {
      "description": "IPv4 or IPv6, public or private.",
      "type": "string"
    },
    "target": {
      "description": "A platform endpoint to mint on instead of an address, when the platform gave you a URL and no IP. Send either ip or target, not both.",
      "type": "string"
    },
    "subdomain": {
      "description": "The label to use. Omitted, DNSMint picks an opaque one.",
      "type": "string"
    },
    "domain": {
      "description": "Which of the account's domains to mint on. Omitted, DNSMint picks when the account holds one.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Point an existing hostname at a new address. This is what makes the name worth having: the machine moves, the name does not, and everything holding the URL keeps working. Repointing within an address class is free, including between IPv4 and IPv6. Crossing between public and private is refused, because one name resolving public then private is how DNS rebinding works.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The hostname's id, from list_hostnames."
    },
    "ip": {
      "description": "The new address.",
      "type": "string"
    },
    "target": {
      "description": "A platform endpoint to follow instead of a fixed address, when the platform gave you a URL and no IP. Send either ip or target, not both.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

PERMANENTLY give up a hostname. Read this before calling it. A released hostname is tombstoned and is never issued again, to anyone, including this account. There is no undo and it cannot be re-minted. This is not like deleting a DNS record. Only call this when the name is genuinely finished with and a human has asked for it. If the goal is to stop serving, repoint it or stop the machine instead. Pass the hostname in `confirm` exactly as it appears, so a name cannot be released by guessing an id.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The hostname's id, from list_hostnames."
    },
    "confirm": {
      "type": "string",
      "description": "The full hostname, exactly. Must match the name behind that id."
    }
  },
  "required": [
    "id",
    "confirm"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a payment link the account owner opens to raise this account's limits. Call this when minting fails because the account is at its hostname cap or has no plan. This charges nothing and buys nothing. It returns a URL, and the purchase only happens if a person opens it and enters card details. Give the URL to the human you are working with and say what it costs; do not try to complete it yourself, and do not call this repeatedly hoping the limit lifts. Nothing changes until somebody pays. Only for an account with no plan yet. If one already exists you get the billing page back instead, because changing a running plan charges a card on file and is a person's decision. Both numbers default to what the account already holds, so asking for hostnames alone keeps the domains. A plan smaller than what is in use is refused.

{
  "type": "object",
  "properties": {
    "hostnames": {
      "description": "Hostnames the plan should include. Ask for the cap you need, not the extra.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "domains": {
      "description": "Dedicated domains the plan should include. Leave unset to keep the current count.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}