Copy page

API

Metadata

Metadata stores your own key-value pairs on Domain Chief resources. Use it for identifiers, labels, or links that belong to your system but do not have a standard API field.

The API accepts metadata on:

• Domains during registration or update
• Contacts during creation or update
• DNS records during creation or update

Set metadata

Pass a metadata object when you create or update a supported resource. Keys and values are strings.

Code
{
  "metadata": {
    "customer_id": "customer_4821",
    "environment": "staging",
    "service": "mail"
  }
}

The API returns metadata on the resource:

Code
{
  "id": "7f942c3e-791f-4b24-9a84-2f7db248cf60",
  "domain": "mailbox-lab.example",
  "metadata": {
    "customer_id": "customer_4821",
    "environment": "staging",
    "service": "mail"
  }
}

Resources without metadata return an empty object in the metadata field.

Update metadata

An update merges the supplied keys with the existing metadata. It does not replace the full object.

Send a new value to add a key or change its value:

Code
{
  "metadata": {
    "environment": "production"
  }
}

Send an empty string to remove one key:

Code
{
  "metadata": {
    "environment": ""
  }
}

Send an empty object to remove all user-defined metadata:

Code
{
  "metadata": {}
}

Validation rules

Part	Rule
Key	Must be a non-empty string
Key length	At most 40 characters
Key characters	Cannot contain [ or ]
Value	Must be a string
Value length	At most 500 characters
Keys per resource	At most 50

For example, customer[id] is invalid because metadata keys cannot contain square brackets. A numeric value such as 123 is also invalid. Send it as the string "123".

Display in Domain Chief

Domain Chief displays all metadata in the web interface. Some values have extra behavior.

HTTPS URLs

A value that starts with https:// appears as a link.

Code
{
  "metadata": {
    "runbook": "https://ops.example.net/runbooks/mail"
  }
}

Tags

The tag key appears as a label on domains, contacts, and DNS records. On a domain, selecting the tag filters the domain list to domains with the same value.

Code
{
  "metadata": {
    "tag": "production"
  }
}

External links

The external_url key adds a link button to domains, contacts, and DNS records. Its value must be a valid https:// URL.

Code
{
  "metadata": {
    "external_url": "https://portal.example.net/resources/4821"
  }
}

Keep metadata safe

Metadata is plain text and appears in API responses. Do not store passwords, access tokens, API keys, or other secrets in it. Use one naming style for keys so integrations can read them consistently.