# Metadata import {Head} from "zudoku/components"; Metadata | Domain Chief 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. ```json { "metadata": { "customer_id": "customer_4821", "environment": "staging", "service": "mail" } } ``` The API returns metadata on the resource: ```json { "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: ```json { "metadata": { "environment": "production" } } ``` Send an empty string to remove one key: ```json { "metadata": { "environment": "" } } ``` Send an empty object to remove all user-defined metadata: ```json { "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. ```json { "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. ```json { "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. ```json { "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.